A few usability question about git diff --cached

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:

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,

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

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

Wincent Colaiuta <win@wincent.com> writes:

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

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

-Miles

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

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

On 10/5/07, Wincent Colaiuta <win@wincent.com> wrote:

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

On Thu, Oct 04, 2007 at 02:27:41PM +0200, Paolo Ciarrocchi <paolo.ciarrocchi@gmail.com> wrote:

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

On 10/4/07, Miklos Vajna <vmiklos@frugalware.org> wrote:

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,

Miklos Vajna <vmiklos@frugalware.org> writes:

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.

On 10/4/07, Junio C Hamano <gitster@pobox.com> wrote:

Ouch!

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,

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

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

Hi,

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

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

Ciao, Dscho

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

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.

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

That is a rather shaky relation.

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.

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

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

On Thu, Oct 04, 2007 at 04:44:00PM +0200, Matthieu Moy wrote:

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.

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

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.

On Thu, Oct 04, 2007 at 06:02:21PM +0200, Matthieu Moy wrote:

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.

That's a big exception.--b.

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

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.

On 10/4/07, Matthieu Moy <Matthieu.Moy@imag.fr> wrote:

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.

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

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