From: Junio C Hamano <junio@siamese.dyndns.org>
Date: Thu, 21 Apr 2005 22:53:35 GMT
Subject: Re: [PATCH] Docs update
Message-ID: <7vy8bbd9n4.fsf@assigned-by-dhcp.cox.net>
In-Reply-To: <42680FCC.6030901@dgreaves.com>

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

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.