Re: Consistent terminology: cached/staged/index

[David <bouncingcats@gmail.com>]

On 1 March 2011 10:03, Jeff King <peff@peff.net> wrote:
> On Sun, Feb 27, 2011 at 10:34:00AM -0500, Drew Northup wrote:
>
> I'm not sure what you mean by "distint unified staging area". It is a
> conceptual idea that you will put your changes somewhere, and when they
> look good to you, then you will finalize them in some way.
>
> But note that it is a mental model. The fact that it is implemented
> inside the index, along with the stat cache, doesn't need to be relevant
> to the user. And the fact that the actual content is in the object
> store, with sha1-identifiers in the index, is not relevant either. At
> least I don't think so, and I am usually of the opinion that we should
> expose the data structures to the user, so that their mental model can
> match what is actually happening. But in this case, I think they can
> still have a pretty useful but simpler mental model.
>
>> If we use "staging area made up of the object store and information kept
>> in the Index" then we tie a knot on everything, make it clear that it
>> may be more complex than that--and you don't have to care, and we do not
>> foreclose on the possibility of more complete explanation later. That
>> does not bother me. We do however need to recognize that "staging area"
>> is an idiom of limited portability and deal with that appropriately.
>
> Sure, I'm willing to accept that the specific words of the idiom aren't
> good for people with different backgrounds.
>
> One analogy I like for the index is that it's a bucket. It starts out
> full of files from the last commit. You can put new, changed files in
> the bucket. When it looks good, you dump the bucket into a commit. You
> can have multiple buckets if you want. You can pull files from other
> commits and put them in the bucket. You can take files out of the bucket
> and put them in your work tree.
>
> So maybe it should just be called "the bucket"?
>
> I'm not sure that's a good idea, because while the analogy makes sense,
> it doesn't by itself convey any meaning. That is, knowing the concept, I
> can see that bucket is a fine term. But hearing about git's bucket, I
> have no clue what it means. Whereas "staging area" I think is a bit more
> specific, _if_ you know what a staging area is.
>
> So there are two questions:
>
>  1. Is there a more universal term that means something like "staging
>     area"?
>
>  2. Is the term "staging area", while meaningful to some, actually
>     _worse_ to others than a term like "bucket"? That is, does it sound
>     complex and scary, when it is really a simple thing. And while
>     people won't know what the "git bucket" is off the bat, it is
>     relatively easy to learn.
>
>     And obviously, replace "bucket" here with whatever term makes more
>     sense.

A suggestion: could your conceptual bucket be named as "the precommit".

Motives for this suggestion are:
1)  I imagine this word will be readily translatable;
2) Using an invented word like this neatly avoids the complication of
the various different connotations associated with existing words like
"index", "cache", and "stage" that others have raised.

The "precommit" would be a user concept that merely specifies the
content of the next commit. Its purpose is to simplify the user
interface and the documentation. For example, man git-status would
read like this:

"git status displays paths that have differences between the precommit
and the current HEAD commit, paths that have differences between the
working tree and the precommit, and paths in the working tree that are
not tracked by git."

The "precommit" is not to be associated to any specific data structure
in the implementation. For users who want more understanding, it can
be explained that the precommit is implemented by a combination of
data structures. Which are then free to be named anything appropriate
to their individual function (eg "the index file") without triggering
all the issues that give rise to this thread.