I dunno Michael, your idea sounds dangerous. You're saying that the user interface should be defined with concepts that have nothing to do with the plumbing. That's crazy talk! Next you'll be arguing that users don't need to know that the Index file has 4 stages! ;) Jakub: "it is unnecessary power" Yeah, like that an argument that anyone here will listen to. "I can't let you have diff3. It's too much power for you. You might trash the repository with ... uh... diff3." Peff: "... use tokens to describe non-treeish sources and destinations" What defines "tree-ish"ness? What is non-treeish about NEXT/WTREE/etc.? Do you know of anything in the INDEX file that would not be visible from NEXT/WTREE/OURS/THEIRS? Mike On Thu, Jun 9, 2011 at 5:37 PM, Michael Haggerty <mhagger@xxxxxxxxxxxx> wrote: > On 06/09/2011 10:04 PM, Jeff King wrote: >> I'm less sure about these new tokens, for a few reasons: >> >> 1. You get less useful answers in some situations by treating each >> stage as a separate tree (e.g., lack of combined diff). So why >> would I want to use them? > > Wouldn't it be nice to be able to do a combined diff between *any* two > trees? Then the nonuniform merge behavior of "git diff" would be a > special case of a general concept: > > git diff3 OURS NEXT THEIRS > >> 4. They're supposed to be simpler to understand than index stages. But >> are they? The latest definitions seem to be: >> >> OURS is a tree of each path in the index, either from stage 2 if >> it exists, or from NEXT otherwise. >> >> NEXT is a tree of each path in the index, either from stage 0 if >> it exists, or from HEAD otherwise. >> >> But that doesn't seem any simpler to me than just saying "the index >> has numbered stages, and they correspond to resolved, base, ours, >> and theirs". > > There is no need to explain the pseudotrees in terms of the index > stages; the pseudotrees are easier to understand and should therefore > become the primary way to describe the index. Let me give it a try, at > tutorial level. Assume that the concepts HEAD and WTREE have already > been introduced: > > The "index" is a special area that can hold one or more temporary > snapshots of your version-controlled content. Each snapshot is > called a "tree" because it is analogous to a filesystem tree such > as the working tree [1]. > > Usually the index holds a single tree called "NEXT". NEXT is a > snapshot of the state of the working tree that is ready to be > committed. This usually consists of the contents from the commit > that was last checked out (HEAD), plus any changes that have been > staged for commit using "git stage". > > It is possible to use "git diff" to view the difference between any > two trees, whether they be trees in the index, trees in commits, or > the working tree. For example, to see the difference between the > last commit and the working tree, use > > git diff HEAD WTREE > > If you would like to see the changes that are ready to be committed, > type > > git diff HEAD NEXT > > To see the changes in your working tree that have not yet been staged > for commit, use > > git diff NEXT WTREE > > (The previous command can be abbreviated to "git diff".) > > However, things become more complicated during a merge, when the > index is used to keep track of the merge's progress. During a > merge, the index contains four trees: "NEXT", "OURS", "THEIRS", and > "BASE". These four trees are modified as merge conflicts are > resolved. > > NEXT, as usual, contains the contents that are ready to be committed. > Specifically, NEXT contains: > > * the original contents of the branch being merged into > * plus the merged versions of any files that merged cleanly > * plus any changes that have been staged for commit using > "git stage"; for example, files whose conflicts have been > resolved manually. > > OURS contains all of the resolved merges from NEXT, with any > remaining conflicts resolved by using the version from the branch > being merged *into*. > > THEIRS contains all of the resolved merges from NEXT, with any > remaining conflicts resolved by using the content from the branch > being merged *from*. > > BASE contains all of the resolved merges from NEXT, with any > remaining conflicts resolved by using the content from the most > recent ancestor of the two branches being merged. > > As before, "git diff" can be used to view the differences between > these various trees. For example, the following command displays the > conflicts that still have to be resolved: > > git diff NEXT WTREE > > To see how the resolved version differs from the contents of each of > the original branches, use > > git diff HEAD NEXT > git diff MERGE_HEAD NEXT > > The "git diff3" command can be used to compare three trees at once: > > git diff3 OURS NEXT THEIRS > > The previous command can be abbreviated to "git diff3". > > [1] The trees that are stored in the index are in an internal format > that is optimized for efficiency. They are not stored as > individual files like in your working copy. > > Thoughts? > > Michael > > -- > Michael Haggerty > mhagger@xxxxxxxxxxxx > http://softwareswirl.blogspot.com/ > -- 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