Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings

[Jeff King <peff@peff.net>]

On Thu, Nov 04, 2010 at 06:18:17PM +0100, Štěpán Němec wrote:

> This was the only occurence of that usage, and square brackets are
> sufficient and already well-established for that purpose.
> 
> Signed-off-by: Štěpán Němec <stepnem@gmail.com>
> ---
> 
> As per discussion upthread, this notation is not worth keeping; hence
> not mentioning it in the v2 of the CodingGuidlines patch and this
> removal.

I agree the notation is kind of odd. But the intent of the original is
to point out that diff has several modes of operation, depending on the
number of arguments it is given. Your change seems to make that even
more subtle. I would be more in favor of showing the major modes of
operation, one per line, which is what we do in other places. E.g., see
git-branch(1).

Now in the case of diff, as soon as the "description" section starts, we
do start talking about those modes (and there are a lot of them). But I
think it may make sense to cover them with a short comment in the
synopsis. Something like:


  # diff between index and working tree
  git diff [options] [--] [<path>...]

  # diff between HEAD and index
  git diff --cached [options] [--] [<path>...]

  # diff between commit and working tree
  git diff [options] <commit> [--] [<path>...]

  # diff between commit and index
  git diff --cached [options] <commit> [--] [<path>...]

  # diff between commits
  git diff [options] <commit> <commit> [--] [<path>...]

  # diff two paths
  git diff [options] [--] <path> <path>

which obviously is way more verbose, but I think it improves in two
ways:

  1. New users will immediately see what diff is for: it is the
     all-purpose diffing tool in git, and it has several modes of
     operation.

  2. People who know what diff does but need a quick reference on which
     mode they are looking for can quickly scan the list.

If it's too verbose, we could collapse a few cases (e.g., "HEAD and
index" and "commit and index" could come in one line).

-Peff