Re: [PATCH] More docs

DG> Merging DG> If -m is specified, read-tree performs 2 kinds of merge, a subservient DG> tree-read if only 1 tree is given or a 3-way merge if 3 trees are DG> provided.

AFAICR Linus never used the word "subservient" to describe this case [*R1*]. I do not know if the word is a good fit for describing what it does. Sorry, I cannot help you in deciding if this is the right word nor in picking a better word. I am not a native speaker so I had to look it up in the dictionary.

DG> Furthermore, "read-tree" has special-case logic that says: if you see DG> a file that matches in all respects in the following states, it DG> "collapses" back to "stage0": DG> - stage 2 and 3 are the same DG> - stage 1 and stage 2 are the same and stage 3 is different DG> - stage 1 and stage 3 are the same and stage 2 is different

That is what I wrote so I should say "sounds good", but after re-reading it I realize we should describe how these trivial ones are resolved, like so:

    Furthermore, "read-tree" has special-case logic that says: if you see
    a file that matches in all respects in the following states, it
    "collapses" back to "stage0":

     - stage 2 and 3 are the same;
       take one or the other (it does not make a difference)
     - stage 1 and stage 2 are the same and stage 3 is different;
       take stage 3
     - stage 1 and stage 3 are the same and stage 2 is different
       take stage 2
    
DG> show-files
DG> show-files [-z] [-t] (--[cached|deleted|others|ignored|stage])*

DG> Well, it says Copyright (C) Linus Torvalds, 2005 - and Linus describes DG> it in his discussion so...

My comment was only about the '-t' option. It is not one of the options in the core. Pasky may want to feed the change to Linus.

[References] *R1*

    Date:	Tue, 19 Apr 2005 11:27:34 -0700 (PDT)
    From:	Linus Torvalds <torvalds@osdl.org>
    Subject: Re: naive question
    Message-ID: <Pine.LNX.4.58.0504191117570.19286@ppc970.osdl.org>

    On Tue, 19 Apr 2005, Linus Torvalds wrote:
    > 
    > The real expense right now of a merge is that we always forget all the
    > stat information when we do a merge (since it does a read-tree). I have a
    > cunning way to fix that, though, which is to make "read-tree -m" read in
    > the old index state like it used to, and then at the end just throw it
    > away except for the stat information.

    Ok, done. That was really the plan all along, it just got dropped in the 
    excitement of trying to get the dang thing to _work_ in the first place ;)

    ... I'll also make it do the same for a "single-tree merge":

            read-tree -m <newtree>

    so that you can basically say "read a new tree, and merge the stat 
    information from the current cache".  That means that if you do a
    "read-tree -m <newtree>" followed by a "checkout-cache -f -a", the 
    checkout-cache only checks out the stuff that really changed.