Re: [PATCH] Documentation: fix misnested -l and --contains in git-tag synopsis

Philip Jägenstedt [off-list ref] writes:

... they do in fact interact in some non-obvious way or if -l <pattern>
--contains <commit> means something different from -l --contains
<commit> <pattern>, it would be great if that were made more clear.

There is no difference; at least there shouldn't be any, and if there are,
you found a bug in the implementation.

Let's try to see if I can explain it better.

"git tag" command operates in four modes:

 - "Creating" is the default mode.
 - "Verifying" is triggered with the -v option.
 - "Deleting" is triggered with the -d option.
 - "Listing" is triggered with the -l option.

In "Listing" mode, you can limit which ones are shown by adding <pattern>
at the end [*1*]; "--contains <commit>" can also be used to limit.  You
can change how tags are shown by "-n <lines>" option.

Absense of -v, -d, or -l options does not automatically mean "Creating"
mode; when it is clear from other options that "Listing" is requested, we
do so without "-l".  When you have "--contains <commit>", for example, it
is obvious that you want a listing.  The same if you have "-n1".

[Footnote]

*1* I think allowing <pattern> anywhere on the command line but at the end
is actually a bug.

Even though it can be argued that it does not _hurt_ not to refuse such a
command line (i.e. the command would do something useful), it appears to
me that it did hurt in this particular case by giving a false impression
that somehow "-l" takes an optional <pattern> argument by allowing other
options after "-l <pattern>" is given.

Arguably, it is the same kind of "usability measure" as our dwimming into
listing mode without "-l" when we can infer the intent of the user from
other options, but I think we sometimes overdo usability measures to the
point that they negatively affect the learning curve of users.

I also think allowing only one <pattern> is a bug.  The command should
filter the tags by union of <pattern>s, just like how pathspec works.