Re: Command-line interface thoughts

[Michael Haggerty <mhagger@alum.mit.edu>]

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@alum.mit.edu
http://softwareswirl.blogspot.com/