Re: [PATCHv2] git-diff: Clarify operation when not inside a repository.

From: Dale R. Worley <worley@alum.mit.edu>
Date: Aug 23, 2013, 18:11 UTC
Message-ID: <201308231811.r7NIBeH9027848@freeze.ariadne.com>
In-Reply-To: <xmqqioyxqwdr.fsf@gitster.dls.corp.google.com>

> From: Junio C Hamano <gitster@pobox.com>

Show 21 quoted lines

> I suspect that it may be a good idea to split the section altogether
> to reduce confusion like what triggered this thread, e.g.
> 
>     'git diff' [--options] [--] [<path>...]::
> 
>             This form is to view the changes you made relative to
>             the index (staging area for the next commit).  In other
>             words, the differences are what you _could_ tell Git to
>             further add to the index but you still haven't.  You can
>             stage these changes by using linkgit:git-add[1].
> 
>     'git diff' --no-index [--options] [--] <path> <path>::
> 
> 	    This form is to compare the given two paths on the
> 	    filesystem.  When run in a working tree controlled by
> 	    Git, if at least one of the paths points outside the
> 	    working tree, or when run outside a working tree
> 	    controlled by Git, you can omit the `--no-index` option.
> 
> For now, I'll queue your version as-is modulo style fixes, while
> waiting for others to help polishing the documentation better.

It'd difficult to figure out how to describe it well. In my opinion, the problem here is the DWIM nature of the command, which means that there is a lot of interaction between the options that are specified, the number of path arguments, and the circumstances. My preference is for "do what I say", that the options restrict the command to operate in exactly one way, which determines the way the paths are used (and thus their number) and the context in which it can be used. But that's not how git-diff works.

Dale