Re: [PATCH] Docs update

Looks nice. I agree with Petr's comment that separating core part and Cogito part would be good, and I would appreciate if you pushed the core part documentation to Linus as well.

Some nitpicks and notes on your core part description.

DG>  commit-tree
DG> -	commit-tree <sha1> [-p <sha1>]* < changelog
DG> +	commit-tree <sha1> [-p <parent sha1>...] < changelog
 
The above does not describe what commit-tree expects.  It wants

    commit-tree <tree-sha1> [-p <parent1 sha1>]* <changelog

That is, you need -p before every parent. I however think what coommit-tree does here this aspect is wrong, unless Linus has plans to give parameters other than parent IDs to commit-tree later. Even if that is the case, those non-parent things can have their own -flag in front of them so not requiring -p would be a good change. I'll ask opinion from Linus on this (I just sent out a patch).

DG> +A commit object usually has 1 parent (a commit after a change) or 2 DG> +parents (a merge) although there is no reason it cannot have more than DG> +2 parents.

I'd rewrite the "or 2 parents..." part to "up to 16 parents. More than one parent represents merge of branches that led to them."

DG> +If not provided, commit-tree uses your name, hostname and domain to DG> +provide author and committer info. This can be overridden using the DG> +following environment variables. DG> + ... DG> +(nb <,> and CRs are stripped)

CRs are kept.  It removes '\n' (which is not necessarily LF).

DG> +diff-cache DG> + diff-cache [-r] [-z] <tree/commit sha1> DG> + DG> +Compares the content and mode of the blobs found via a tree object DG> +with the content of the current cache and, optionally, the stat state DG> +of the file on disk.

And the option to use working tree is not having the --cached flag you describe later. Please also update the usage at the top as well:

	diff-cache [-r] [-z] [--cached] <tree/commit sha1>

DG> +In the special case of the file being changed on disk and out of sync with the cache, the sha1 DG> + DG> +Operating Modes

Is the description truncated after "the sha1"???

DG> ################################################################ DG> diff-tree DG> - diff-tree [-r] [-z] <tree sha1> <tree sha1> DG> + diff-tree [-r] [-z] <tree sha1> <tree sha1>

This command can take commit ID in place of tree ID.