Re: Consistent terminology: cached/staged/index

Hi Pete,

Pete Harlan wrote:

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.