patchDocumentation: fix misnested -l and --contains in git-tag synopsis

This has been broken since the --contains option was added in commit 32c35cfb1e9c8523b9d60e5095f1c49ebaef0279

Signed-off-by: Philip Jägenstedt <philip@foolip.org>
---
 Documentation/git-tag.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

Philip Jägenstedt <philip@foolip.org> writes:

I do not think there is any "mis" nor "nesting" here. The -l option can be used to tell the command to operate in "list tags" mode, and in that mode it can use a pattern to limit the output (with or without --contains <commit>). All of these are supported:

    git tag -l --contains v1.7.0 v\*
    git tag -l v\*
    git tag --contains v1.7.0 -l v\*
    git tag -l v\* --contains v1.7.0

IOW, <pattern> is _not_ an optional argument to the -l option. In fact, I think we should support more than one patterns, even though currently this seems to silently ignore k\*:

    git tag --contains v1.7.0 -l v\* k\*

As I tend to consider that "limit by pattern" is like pathspecs (in this case, it is _not_ a pathspec, though), having the pattern at the end looks the most natural, but it may be just me. And that is why I think we ought to accept and apply more than one patterns here.

I would further say that "git tag -l <pattern> --contains <commit>" should be an error, even though the command currently seems to take it; perhaps parameter reordering is in effect? I didn't look closely enough.

On Thu, Nov 4, 2010 at 20:37, Junio C Hamano <gitster@pobox.com> wrote:

From the documentation it's not clear that -l and --contains are related at all, they look (and behave?) like orthogonal options. If 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. (I wouldn't have expected the later to work at all, thus my assumption that there was a typo in the documentation.)

Philip Jägenstedt <philip@foolip.org> writes:

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.