Re: Consistent terminology: cached/staged/index

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Feb 15, 2011, 18:38 UTC
Message-ID: <20110215183816.GB26405@elie>
In-Reply-To: <AANLkTim3g15GRZUhrq4=Bs28JHr3M53U_QavtyUxsh7L@mail.gmail.com>

Piotr Krukowiecki wrote:

>> Piotr Krukowiecki wrote:

>>>  --refresh::
>>>       Don't add the file(s), but only refresh their stat()
>>> -     information in the index.
>>> +     information in the staging area.

[...]

Show 6 quoted lines

> If there is no staging - no commit, then you're right. But then you don't
> have to mention index at all:
>
>   --refresh::
>        Don't add the file(s), but only refresh their stat()
>        information.

Yes, that sounds like an improvement. Though I'd suggest something like:

  --refresh::
	Don't add the files' content and mode, but refresh their stat(2)
	information if it is out of date.  For example, you'd want to
	do this after restoring a repository from backup, to link up
	the stat index details with the proper files.

The exact wording could use tweaking, but hopefully the idea is clear (to explain what the option is actually used for).

> index is just part of git. How or where the stat information is
> refreshed does not matter.

I agree with that. That this is (1) specific to that index, so the operation needs to be repeated if you use GIT_INDEX_FILE to work with a second index and (2) has as its only purpose speeding up operations that compare the index to the worktree are relevant, though.

Anyway, I don't want to argue. Many of the places pointed out in the manual could use help. It could even involve inserting the phrase "a staging area".

Hopefully I have made clear why excising the word "index" from git vocabulary (like the word "current directory cache" was eventually eliminated over time in the past) does not seem like a good idea when we don't even have a good alternative for it. As the original post mentioned, using three terms in documentation for fundamentally the same thing is going to get confusing after a while. Why not just use one ("the index")?

Sorry for the ramble. Jonathan