From: Jonathan Nieder <jrnieder@gmail.com>
Date: Thu, 04 Nov 2010 18:38:51 GMT
Subject: Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings
Message-ID: <20101104183851.GA16865@burratino>
In-Reply-To: <20101104181357.GA31016@sigill.intra.peff.net>

Jeff King wrote:

> 	git diff [options] [<commit>] [--] [<path>...]
> 	git diff [options] --cached [<commit>] [--] [<path>...]
> 	git diff [options] <commit> <commit> [--] [<path>...]
> 	git diff [options] [--no-index] [--] <path> <path>
> 
> which covers the four major modes.

Makes sense.  There is just one particularity of

	git diff --cached [<commit>]

I am worried about.  Namely: according to a recent patch,

	git diff --cached

should not be considered as

	git diff --cached HEAD

with the "HEAD" implicit, but a distinct operation meaning
"show me what changes git commit would store".

> On Thu, Nov 04, 2010 at 01:02:42PM -0500, Jonathan Nieder wrote:

>> I would rather treat --cached as one of the options ("instead of
>> comparing the worktree, compare its cached content in the index to the
>> specified commit"),
>
> Except it is not quite that. For the first two that I listed above,
> --cached makes that distinction. But --cached doesn't make sense at all
> in the third or fourth ones. So I think in practice it ends up defining
> a mode of operation more than simply an option.

Not sure I understand your logic.  Is your point that --cached in
those cases does not print

	fatal: --cached does not make sense in this operation mode

but

	usage: git diff <options> <rev>{0,2} -- <path>*

that implies the operation mode is not known?

>                                   There are pretty few unix programs
> that don't take [options] at the beginning, so it really is kind of
> superfluous. But it's also pretty standard, and clues the user in that
> we are a normal program.

Yes, sorry about the tangent.