Re: [PATCH] More docs

DG> Removed Cogito stuff

DG>  commit-id

This is Cogito invention, not in the core.  Neither is tree-id.

DG> ################################################################ DG> +diff-cache DG> ... DG> +-z 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.

DG> diff-tree DG> - diff-tree [-r] [-z] <tree sha1> <tree sha1> DG> + diff-tree [-r] [-z] <tree/commit sha1> <tree/commit sha1> DG> +... 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...

DG> ################################################################ DG> read-tree DG> - read-tree [-m] <sha1> DG> + read-tree (<sha> | -m <sha1> [<sha2> <sha3>])" DG> + DG> +Reads the tree information given by <sha> into the directory cache, DG> +but does not actually _update_ any of the files it "caches". (see: DG> +checkout-cache) DG> + DG> +Optionally, it can merge a tree into the cache or perform a 3-way DG> +merge. DG> + DG> +Trivial merges are done by read-tree itself. Only conflicting paths DG> +will be in unmerged state when read-tree returns. DG> +... 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:

    - 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

Originally it merged only when all stages are the same.

Also you do not describe the single tree merge ("read-tree -m sha1"). Its semantics is:

    Operate as if the user did not specify "-m", but if the
    original cache had an entry for the same pathname already
    and the contents of the original matches with the tree being
    read, use the stat info from the original instead.

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

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.
Also you missed "show-files --unmerged".