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

From: Jeff King <peff@peff.net>
Date: Nov 4, 2010, 17:49 UTC
Message-ID: <20101104174917.GA30628@sigill.intra.peff.net>
In-Reply-To: <87hbfxgg86.fsf_-_@gmail.com>

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

Show 9 quoted lines

> 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