Re: Consistent terminology: cached/staged/index

[Pete Harlan <pgit@pcharlan.com>]

On 02/14/2011 03:19 PM, Jonathan Nieder wrote:
> 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.

Thank you for that explanation.

> "Staging area" only describes the first.

...which to me means only that "staging area" isn't enough to fully
describe what Git can do.

>From the user's perspective, merge conflict resolution is a separate
process from staging a commit; where does Git's usability benefit from
blending the two concepts by referring (in command syntax and
manpages) to their common internal data structure?

One of Git's charms is the simplicity of blobs, trees, commits and
tags and how those ingredients prove tremendously useful in developing
software.  And I don't think anyone can use Git well without fully
understanding what those structures are (and are not).

But I believe the rest of Git's internals are in a different category.
Regardless of how elegant the solution may be, as a user I can use Git
well without knowing _how_ Git can tell that foo.c contains staged and
unstaged changes.  Nor do I need to know how it knows that bar.c is in
conflict.  I don't need to know precisely how it implements its packed
object database to use it effectively.

Part of the issue could be that one intimately familiar with Git's
internals may find a process oriented interface irritating ("Why must
it say 'staging area' when it's just updating the index?"), while one
unfamiliar with the internals has the opposite reaction ("Why must it
make me use the internal name of the staging area?").

Someone suggested using a different top-level name for Git to allow
for completely rewriting the interface.  I expect that it's this
difference of perspective that makes that appear necessary.  I believe
that a rewrite is the wrong approach, but I believe that abstractions
like "staging area" move the user-interface a little more toward the
user and that there's value in that.

--Pete

> 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