Re: [PATCH] More docs

From: David Greaves <david@dgreaves.com>
Date: Apr 22, 2005, 21:44 UTC
Message-ID: <4269704A.9090503@dgreaves.com>
In-Reply-To: <7vwtqu5ymu.fsf@assigned-by-dhcp.cox.net>

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...

Show 6 quoted lines

> 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>

Show 6 quoted lines

> 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.

Show 6 quoted lines

> 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