Re: Consistent terminology: cached/staged/index

[Jonathan Nieder <jrnieder@gmail.com>]

Hi Pete,

Pete Harlan wrote:

> 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?")

No, no.  I agree there's a problem to solve here.  The current
documentation for git (e.g., the user manual) has a nice, coherent,
user-oriented narrative about trees, commits, and blobs, and meanwhile
it is hard to find a clear story about the index.

Such a story would have to describe the conflict resolution process.
When you encounter a merge conflict, how do you resolve it?  The best
I can do for now is to point to the user manual[1].

http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#conflict-resolution

I even think it is okay to say "The index is a sort of staging area
for your next commit".  Because that is true.  But it is not the full
story, so if one wants to give the index a new name --- which is a
costly thing to do, anyway --- then I do not think "the staging area"
works.

I feel bad to only be presenting complications instead of an alternate
solution.  I do consider workflow oriented explanations very useful.
I've been giving technical explanations in this thread as background
for future storytelling, in the hope that someone more talented than I
am can digest it into a good narrative.

Jonathan

[1] Maybe the process is overdesigned.  After all, what would we lose
by saying

 - an unmerged path justs gets an "unmerged" flag set, meaning that
   flag is not ready for commit yet
 - to get the copy from the common ancestor, use
	git show $(git merge-base HEAD MERGE_HEAD):path/to/file
 - to get the copy from HEAD, use
	git show HEAD:path/to/file
 - likewise to get the copy from MERGE_HEAD

And while I can give answers about why that is a bad interface
(recomputing the merge base is a waste of time; in a recursive merge
the merge base is not a real commit; if there were renames, the copy
from HEAD could be HEAD:other/path and it is hard to find what
other/path is), are those answers enough to justify learning this new
trick?

So we need a better story.