Re: Consistent terminology: cached/staged/index

[Jonathan Nieder <jrnieder@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.
[...]
> 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