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

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 5, 2010, 16:51 UTC
Message-ID: <7vzktnu311.fsf@alter.siamese.dyndns.org>
In-Reply-To: <AANLkTikXM4BjRHOeS=3mirr9=YRW8sdaHFt05D-9BDxL@mail.gmail.com>

Philip Jägenstedt <philip@foolip.org> 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.