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.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html