A few usability question about git diff --cached

A few usability question about git diff --cached

[Paolo Ciarrocchi]

Hi all,
I'm having and interesting discussion with an happy mercurial users
which started reading the git documentation. He raised aquestion that
I'm not able to answer:

> $ git diff --cached
>
> (Without —cached, git-diff(1) will show you any changes that you've
> made but not yet added to the index.) You can also get a brief summary
> of the situation with git-status(1):

Why do we have the option "--cached" and not "--index"?

I believe that, just reading the documentation, is not very easy to
fully understand the role of the index and then we have an option
"--cached" that refers to the index.
Is it a good idea to add and document an option "--index" and remove
from the doc the option "--cached"?

Thanks.

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

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

[Wincent Colaiuta]

El 4/10/2007, a las 14:27, Paolo Ciarrocchi escribió:

> Hi all,
> I'm having and interesting discussion with an happy mercurial users
> which started reading the git documentation. He raised aquestion that
> I'm not able to answer:
>
>> $ git diff --cached
>>
>> (Without —cached, git-diff(1) will show you any changes that you've
>> made but not yet added to the index.) You can also get a brief  
>> summary
>> of the situation with git-status(1):
>
> Why do we have the option "--cached" and not "--index"?

I am not an "old timer", but I believe that it's because what we now  
know as "the index" was original called "the cache". See:

<http://git.or.cz/gitwiki/GitHistory>

You're probably right that the option name is confusing, I guess  
changing it to "--index" would be a good idea, continuing to support  
"--cached" but marking it as deprecated before finally removing it at  
some point in the future.

Cheers,
Wincent

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

[Miklos Vajna]

[-- Attachment #1: Type: text/plain, Size: 375 bytes --]

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

- VMiklos

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

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

[Paolo Ciarrocchi]

On 10/4/07, Miklos Vajna <vmiklos@frugalware.org> wrote:
> 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

Believe me, for a GIT newbie git --cached is confusing.

That user started reading "A tutorial introduction to git (for version
1.5.1 or newer)",
after a cuple of minutes of reading he reached "Making changes" saw:

" You are now ready to commit. You can see what is about to be
committed using git-diff(1) with the —cached option:

$ git diff --cached "

$ git diff --index sound a lof more consistent with the general documentation.

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

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

[Junio C Hamano]

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.

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.

An example of a command that supports both is "git apply".
Actually it is an extreme case in that it allows "no index" form
of operation, so it has "git apply", "git apply --cached", and
"git apply --index".  The --cached would only apply to index
without touching work tree, the --index would apply to both
index and work tree.

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

[Paolo Ciarrocchi]

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

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

[Wincent Colaiuta]

El 4/10/2007, a las 15:14, Junio C Hamano escribió:

> 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.
>
> 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.

Look at that with fresh eyes and you can see how it makes very little  
sense.

The option named "--index" works on more than the index and the  
option named "--cached" works only on the index. This sounds back-to- 
front.

IMO, better names would be:

--index : means work only on the index (and ignore the work tree);  
ie. it means what it says

--index-and-worktree : it also means what it says

The latter is more keystrokes but it's clearer.

Having said all this, I recognize that the likelihood of these option  
names ever being changed is close to zero. Like Paolo says in his  
other email, the documentation could be made clearer to avoid  
possible confusion.

Cheers,
Wincent

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

[Johannes Schindelin]

Hi,

On Thu, 4 Oct 2007, Junio C Hamano wrote:

>  * --cached means work only on index and ignore work tree.

I guess I could live with "--staged" as a synonym for "--cached" (and 
maybe deprecating "--cached").

Ciao,
Dscho

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

[Junio C Hamano]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

> On Thu, 4 Oct 2007, Junio C Hamano wrote:
>
>>  * --cached means work only on index and ignore work tree.
>
> I guess I could live with "--staged" as a synonym for "--cached" (and 
> maybe deprecating "--cached").

A handy mnemonic might be:

 * --index means work work tree through the index.  Once you get
   git, this is natural as you would not interact with files in
   the work tree that is not known to the index.

 * --cached means work only on the cached information in index.

Any change like swapping them or renaming --cached to --index
and making something else to mean what --index always meant will
break existing setups and people's scripts.  Won't happen.

Giving them synonyms without deprecation is a viable option, if
necessary.  I do not however see the need yet.  A few people who
haven't learned the lingo of the land yet can worry about
possible confusion, but I do not think that "worry" itself does
not count as real need.

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

[Matthieu Moy]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

> Hi,
>
> On Thu, 4 Oct 2007, Junio C Hamano wrote:
>
>>  * --cached means work only on index and ignore work tree.
>
> I guess I could live with "--staged" as a synonym for "--cached" (and 
> maybe deprecating "--cached").

It makes more sense to me.

For me, a "cache" is a fast-access copy of something, that I can
rebuild at any time. Cache should be only a matter of performance, if
the "cache" for an application changes its functionality, it means the
cache has been too optimistic. Git's index is not that, "git add"
means "add this to the index", which itself means "put that in the
list of things to commit", and not "get a copy of that to work faster
with it".

So, to me (non-native speaker), "index" doesn't mean much, "cache" is
worse, it means something which isn't correct, and "staging area"
means the right thing (but is longer to type). For example, I
understand immediately when git-gui talks me about staging/unstaging
changes ;-).

-- 
Matthieu

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

[David Kastrup]

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

>  * --index means work work tree through the index.  Once you get
>    git, this is natural as you would not interact with files in
>    the work tree that is not known to the index.
>
>  * --cached means work only on the cached information in index.

That is a rather shaky relation.

> Giving them synonyms without deprecation is a viable option, if
> necessary.  I do not however see the need yet.  A few people who
> haven't learned the lingo of the land yet can worry about possible
> confusion, but I do not think that "worry" itself does not count as
> real need.

The "lingo of the land" as documented in the manuals no longer uses
the term "cache" or "cached" as something with an official meaning.

So the current state of affairs does not really look overly convincing
with regard to consistency.

-- 
David Kastrup

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

[Wincent Colaiuta]

El 4/10/2007, a las 16:34, Johannes Schindelin escribió:

> On Thu, 4 Oct 2007, Junio C Hamano wrote:
>
>>  * --cached means work only on index and ignore work tree.
>
> I guess I could live with "--staged" as a synonym for "--cached" (and
> maybe deprecating "--cached").

Good idea. I think that would partly address the consistency  
problems, be more accessible to new users, and easier to explain in  
the documentation.

Not that it makes much difference to me personally. One of the first  
things I did when I started using Git was set up two shell aliases  
(not Git aliases) seeing as looking at my staged and unstaged changes  
is for me such an extremely frequent operation:

   alias staged='git diff --cached'
   alias unstaged='git diff'

Cheers,
Wincent

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

[J. Bruce Fields]

On Thu, Oct 04, 2007 at 04:44:00PM +0200, Matthieu Moy wrote:
> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
> 
> > Hi,
> >
> > On Thu, 4 Oct 2007, Junio C Hamano wrote:
> >
> >>  * --cached means work only on index and ignore work tree.
> >
> > I guess I could live with "--staged" as a synonym for "--cached" (and 
> > maybe deprecating "--cached").
> 
> It makes more sense to me.
> 
> For me, a "cache" is a fast-access copy of something, that I can
> rebuild at any time. Cache should be only a matter of performance, if
> the "cache" for an application changes its functionality, it means the
> cache has been too optimistic. Git's index is not that, "git add"
> means "add this to the index", which itself means "put that in the
> list of things to commit", and not "get a copy of that to work faster
> with it".

Yes, the index differs from the work tree or HEAD temporarily, but most
of it's life it's just a fast-access copy of something that you can
rebuild at any time.

So it's partly a "cache", partly a "staging area", and "index" is as
good a term for it as any.

--b.

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

[Matthieu Moy]

"J. Bruce Fields" <bfields@fieldses.org> writes:

> Yes, the index differs from the work tree or HEAD temporarily, 

Temporarily, yes, but the _point_ of having it is to have it differ
from HEAD (otherwise, you can't create a new revision), and from the
tree (otherwise, index-related commands are useless).

The stat-information, and sha1sum are actually a cache, but they don't
have to be user-visible, except for speed. "diff --cached" has nothing
to do with the stat information for the user.

-- 
Matthieu

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

[J. Bruce Fields]

On Thu, Oct 04, 2007 at 06:02:21PM +0200, Matthieu Moy wrote:
> "J. Bruce Fields" <bfields@fieldses.org> writes:
> 
> > Yes, the index differs from the work tree or HEAD temporarily, 
> 
> Temporarily, yes, but the _point_ of having it is to have it differ
> from HEAD (otherwise, you can't create a new revision), and from the
> tree (otherwise, index-related commands are useless).

Getting a nearly-instantaneous "git diff" would be sufficiently
important to justify its existance on its own, so I think you're
overstating the case.

> The stat-information, and sha1sum are actually a cache, but they don't
> have to be user-visible, except for speed.

That's a big exception.--b.

> "diff --cached" has nothing to do with the stat information for the
> user.

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

[David Tweed]

On 10/4/07, Matthieu Moy <Matthieu.Moy@imag.fr> wrote:
> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
> It makes more sense to me.
>
> For me, a "cache" is a fast-access copy of something, that I can
> rebuild at any time. Cache should be only a matter of performance, if
> the "cache" for an application changes its functionality, it means the
> cache has been too optimistic. Git's index is not that, "git add"
> means "add this to the index", which itself means "put that in the
> list of things to commit", and not "get a copy of that to work faster
> with it".

Just to say this interpretation is also the natural interpretation I
have for the term "cached", and it confused me no end when I was first
learning about git that the index was referred to as a cache. To be
fair, git the documentation was in flux at that time and it's now
referred too as a cache in very few places now.

An example of the kind of thing I have to think carefully about even
now, Junio said in a different mail:

"--cached means work only on the "cached information in index."

If I understand correctly, the term "cached information in index" is
more correctly "stored information in index" (or perhaps more
technically "staged information in index") since there may be
information in there which isn't a cache because it's no longer
present anywhere else (ie, not in a commit yet but also changed in the
working tree).

It's not a big thing, but the usage of cached in git still quite confuses me.

-- 
cheers, dave tweed__________________________
david.tweed@gmail.com
Rm 124, School of Systems Engineering, University of Reading.
"we had no idea that when we added templates we were adding a Turing-
complete compile-time language." -- C++ standardisation committee

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

[Miles Bader]

Wincent Colaiuta <win@wincent.com> writes:
> You're probably right that the option name is confusing, I guess  
> changing it to "--index" would be a good idea, continuing to support  
> "--cached" but marking it as deprecated before finally removing it at  
> some point in the future.

Personally all I want is a short-option alias for --cached!

Hopefully something easily type-able (not uppercase)...

-Miles

-- 
Americans are broad-minded people.  They'll accept the fact that a person can
be an alcoholic, a dope fiend, a wife beater, and even a newspaperman, but if a
man doesn't drive, there is something wrong with him.  -- Art Buchwald

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

[Matthieu Moy]

"J. Bruce Fields" <bfields@fieldses.org> writes:

>> The stat-information, and sha1sum are actually a cache, but they don't
>> have to be user-visible, except for speed.
>
> That's a big exception.--b.

Speed _is_ important, of course. But the user only benefits from
speed, he doesn't have to manipulate it explicitely. I may be
repeating myself, but "diff --cached" doesn't mean "diff using the
stat-cache", it means "diff using the cached _content_", which is
really unrelated from the stat-cache.

Mercurial also has fast diff (perhaps a bit slower that git, but same
order of magnitude), and has no user-visible index.

-- 
Matthieu

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

[Wincent Colaiuta]

El 5/10/2007, a las 7:59, Miles Bader escribió:

> Wincent Colaiuta <win@wincent.com> writes:
>> You're probably right that the option name is confusing, I guess
>> changing it to "--index" would be a good idea, continuing to support
>> "--cached" but marking it as deprecated before finally removing it at
>> some point in the future.
>
> Personally all I want is a short-option alias for --cached!
>
> Hopefully something easily type-able (not uppercase)...

Did you see the aliases I posted earlier in the thread? I can't think  
of anything shorter or semantically clearer than "staged" and  
"unstaged".

Cheers,
Wincent

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

[Miles Bader]

On 10/5/07, Wincent Colaiuta <win@wincent.com> wrote:
> > Personally all I want is a short-option alias for --cached!
> >
> > Hopefully something easily type-able (not uppercase)...
>
> Did you see the aliases I posted earlier in the thread? I can't think
> of anything shorter or semantically clearer than "staged" and
> "unstaged".

The words are ok, I guess, but aliases are not a replacement for short
options.... really all frequently used, non-dangerous, options should
have a short variant (and diff --cached meets both criteria handily)!

-Miles
-- 
Do not taunt Happy Fun Ball.

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

[Court Rankin]

Courtney 

Sent from my iPhone

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

[Mohammed Al-Mahmeed]

Sent from my iPhone