Re: [PATCH] More docs

[David Greaves <david@dgreaves.com>]

Junio C Hamano wrote:

Thanks for the comments Junio

>>>>>>"DG" == David Greaves <david@dgreaves.com> writes:
> 
> This is Cogito invention, not in the core.  Neither is tree-id.
OK - hard to tell sometimes...

> DG> +	/0 line termination on output
> 
> Write this either '\0' (for C literate) or NUL (ASCII character
> name), please.  The same for other commands with -z.
hmm, this...

> DG> +--cached
> DG> +	Cached only (private?)
> 
> What?  The beauty of diff-tree is it does not care about
> dircache at all.  Maybe this is a Pasky addition, but I wonder
> what the semantics of this option and why it is here...
...and this, are pre-final-polish
I must have committed the wrong one - <sigh>

> DG> +NOTE NOTE NOTE! although read-tree coule do some of these nontrivial
> DG> +merges, only the "matches in all three states" thing collapses by
> DG> +default.
> 
> The above "NOTE" is taken from the initial message from Linus
> but it is no longer true.  These days, it merges when:
OK - will edit

how does this sound:

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

Subservient Tree Read
If only 1 tree is specified, read-tree operates as if the user did not
specify "-m", except that if the original cache has an entry for a
given pathname; and the contents of the path matches with the tree
being read, the stat info from the cache is used. (In other words, the
cache's stat()s take precedence over the subservient tree's)

This is used to avoid unnecessary false hits when show-diff is
run after read-tree.

3-Way Merge
Each "index" entry has two bits worth of "stage" state. stage 0 is the
normal one, and is the only one you'd see in any kind of normal use.

However, when you do "read-tree" with multiple trees, the "stage"
starts out at 0, but increments for each tree you read. And in
particular, the "-m" flag means "start at stage 1" instead.

This means that you can do

	read-tree -m <tree1> <tree2> <tree3>

and you will end up with an index with all of the <tree1> entries in
"stage1", all of the <tree2> entries in "stage2" and all of the
<tree3> entries in "stage3".

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
     - stage 1 and stage 2 are the same and stage 3 is different
     - stage 1 and stage 3 are the same and stage 2 is different

NOTE NOTE NOTE para removed.

> DG>  ################################################################
> DG> @@ -151,8 +603,145 @@
> 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.
Well, it says Copyright (C) Linus Torvalds, 2005 - and Linus describes 
it in his discussion so...

> Also you missed "show-files --unmerged".
I did - that's me using the usage() string!!

David

--