Re: Consistent terminology: cached/staged/index

[Jonathan Nieder <jrnieder@gmail.com>]

Hi again,

Piotr Krukowiecki wrote:

> In other places "index" is called "staging area" and act of updating the index
> is called "staging in the index".
>
> I ask: why do we need the "index" term at all?
>
>    - instead of "index" use "staging" and "staging area"
>    - instead of "listed in index" use "staged" or "tracked"

Unlike "staging area", the word "index" is unfamiliar and opaque.  So
there is a sense that there is something to learn.

When people talk about the staging area I tend to get confused.  I
think there's an idea that because it sounds more concrete, there is
less to explain --- or maybe I am just wired the wrong way.

There is a .git/index file, with a well defined file format.  And
there is an in-core copy of the index, too.  It contains:

 - mode and blob name for paths as requested by the user with
   "git add"

 - competing versions for paths whose proposed content is
   uncertain during a merge

 - stat(2) information to speed up comparison with the worktree

There are some other pieces, too --- "intent-to-add" entries added
with "git add -N", cached tree names for unmodified subtrees to
speed up "git commit", and so on.  But the 3 pieces listed above are
the main thing.

"Staging area" only describes the first.

All that said, I am not against formulations like "content of the next
commit" that might be more concrete from a user's point of view.

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

git add/update-index --refresh are precisely meant for _not_ changing
the content of the next commit, so this particular change seems
confusing.

Hoping that is clearer.  Thanks for caring.
Jonathan