Re: [PATCH] More docs

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

>>>>> "DG" == David Greaves <david@dgreaves.com> writes:

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])*
>> Although I like it, I do not think -t is in core.  It is Pasky.
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.