Subject: Re: Consistent terminology: cached/staged/index

From: Jonathan Nieder <[email-masked]>
Date: Sat, 26 Feb 2011 15:51:39 -0600

Hi Felipe et al,

Felipe Contreras wrote:
> On Tue, Feb 15, 2011 at 1:19 AM, Jonathan Nieder <[email-masked]> wrote:

>>  - mode and blob name for paths as requested by the user with
>>   "git add"
>
> A commit stage.
>
>>  - competing versions for paths whose proposed content is
>>   uncertain during a merge
>
> Multiple commit stages.
>
>>  - stat(2) information to speed up comparison with the worktree
>
> If only a subset of the files are there, it's an 'index', if not, then
> I'd say it's a 'registry'.

These terms you suggest aren't the established ones (as I'm sure you
know).  Just as with everyday language, there is some resistance to
moving to new terms that have not been established for a while.  In
everyday language, many terms gained popularity by

 - appearing in some document that people read for another reason
 - describing the notion they are meant to describe clearly (or
   having some other feature that makes them likeable)

This is how "staging area" has been gaining popularity, I think ---
some (out-of-tree) documentation that is good for other reasons uses
it, and it really does seem to be a clearer term than "index" for
"place where the next commit is being prepared".  Unfortunately, I do
not think it is a clearer term than "index" for "the git index, which
contains stat() information and pointers to blobs that either belong
in the next commit or are participating in a merge conflict".  So it
does not seem to justify rewriting everything to use it.

Which suggests one way forward --- if you believe you have terms that
do describe those concepts clearly, one way to promote them is to
write some good, clear (out-of-tree, to begin with) documentation
using them.  Presumably this documentation would also mention that
other people use other terms to avoid confusing the reader.

Hope that helps,
Jonathan