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@xxxxxxxxx>
> ---
>
> 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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html