Re: A few usability question about git diff --cached

["Paolo Ciarrocchi" <paolo.ciarrocchi@gmail.com>]

On 10/4/07, Junio C Hamano <gitster@pobox.com> wrote:
> Miklos Vajna <vmiklos@frugalware.org> writes:
>
> > On Thu, Oct 04, 2007 at 02:27:41PM +0200, Paolo Ciarrocchi <paolo.ciarrocchi@gmail.com> wrote:
> >> Why do we have the option "--cached" and not "--index"?
> >
> > according to glossary.txt, 'cache' is an obsolete for 'index'. probably
> > this is the reason
> >
> > probably cache.h will be never renamed to index.h, i don't know if diff
> > --cached will be ever renamed to diff --index
>
> Probably never.

Ouch!

> Some commands support both --index and --cached and have
> different meanings.  For them,
>
>  * --index means work on both index and work tree;
>  * --cached means work only on index and ignore work tree.
>
> In the case of "diff --cached", the latter is exactly what's
> happening.  We do not say "git diff-index --index $commit"
> because "git diff-index" (and by extension, when you give only
> one commit to "git diff" as parameter) is all about a commit vs
> your uncommitted changes, so having you say "--index" is just
> silly.  "git diff --cached" is just a shorthand for "git diff
> --cached HEAD".  Because --cached would make sense to no other
> form of diff, its presense by definition means you are talking
> about the one-tree form of diff i.e. compare a commit with your
> uncommitted changes.

I see. But the problem is real. If we cannot solve the problem
changing the code of git we'll need to avoid this kind of
misunderstanding having "better" documentation.

As soon as I'll find some spare time I'll propose a patch to "A
tutorial introduction to git (for version 1.5.1 or newer)".

Thanks!

Regards,
-- 
Paolo
http://paolo.ciarrocchi.googlepages.com/
http://ubuntista.blogspot.com