Re: Consistent terminology: cached/staged/index

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Feb 14, 2011, 23:19 UTC
Message-ID: <20110214231920.GA24814@elie>
In-Reply-To: <AANLkTim4UKxYwRagCk3R20e7wsRb7CxvS_ze9b8MfWjL@mail.gmail.com>

Hi again,

Piotr Krukowiecki wrote:

Show 7 quoted lines

> 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