Summary of "read-tree -m O A B" mechanism

[Junio C Hamano <junkio@cox.net>]

Earlier I wrote down a list of issues your recent "merge
stage" changes have introduced to the rest of the plumbing, with
a set of suggested adaptions.  I think all of them are cleared
now (you have a pile of patches from me in your mailbox).

I do not know what percentage of people on this list are using
git without the Cogito part, but I suspect that the number might
be quite small.  I also suspect, from the description Petr gave
us on how the merging in Cogito works, Cogito does not currently
use the "read-tree -m O A B" mechanism, and those majority who
do not deal with the low level tools themselves would not have
to know about the merge issues yet.  But I think it is a good
time, now things have started to settle down, to summarize how
various commands work when they see those "funny" dircache
entries created after "read-tree -m O A B" has run.  Of course,
people working on Cogito needs to know them, once they decide to
use the "reed-tree -m O A B" mechanism.

 * read-tree -m O A B

   - For description on how this works, the definitive reading
     is [*R1*].  In short:

     - unlike ordinary read-tree, "-m" form reads up to three
       trees and creates paths that are "unmerged".  

     - trivial merges are done by read-tree itself.  only
       conflicting paths will be in unmerged state when
       read-tree returns.

 * write-tree

     - write-tree refuses to give you a tree until all the
       unmerged paths are resolved.

 * show-files

   - "show-files --unmerged" and "show-files --stage" can be
     used to examine detailed information on unmerged paths.
     For an unmerged path, instead of recording a single
     mode/SHA1 pair, the dircache records up to three such
     pairs; one from tree O in stage 1, A in stage 2, and B in
     stage 3.  This information can be used by the user (or
     Cogito) to see what should eventually be recorded at the
     path.

 * update-cache

   - An explicit "update-cache [--add] path" or "update-cache
     [--add] --cacheinfo mode SHA1 path" tells the plumbing that
     the user (or Cogito) wants to resolve it by storing
     mode/SHA1 of the given working file or mode SHA1 specified
     on the command line.  The path ceases to be in unmerged
     state after this happens.

     Similarly, "update-cache --remove path" resolves the
     unmerged state and the merge result is not having anything
     at that path.

   - "update-cache --refresh", in addition to the "needs update"
     message people are now familiar with, says "needs merge"
     for unmerged paths.

 * show-diff

   - show-diff on an unmerged path simply says "unmerged" (the
     plumbing would not know what to diff with what among three
     stages and the working file).  

 * checkout-cache

   - "checkout-cache -a" warns about unmerged paths and checks
     out only the merged paths.

   - "checkout-cache [-f] path" on an unmerged path says
     "Unmerged", just like the same command on non-existent path
     says "not in the cache", and does not touch the working
     file.
 

I hope the descriptions in this summary is correct enough to be
useful to somebody.


[Reference]

*R1* http://marc.theaimsgroup.com/?l=git&m=111363270608902&w=2