Re: Command-line interface thoughts

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 [off-list ref] wrote:

On 06/09/2011 10:04 PM, Jeff King wrote:

quoted

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

quoted

  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/