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:

$ 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/

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:

quoted

$ 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

On Thu, Oct 04, 2007 at 02:27:41PM +0200, Paolo Ciarrocchi [off-list ref] 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

On 10/4/07, Miklos Vajna [off-list ref] wrote:

On Thu, Oct 04, 2007 at 02:27:41PM +0200, Paolo Ciarrocchi [off-list ref] wrote:

quoted

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