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