Re: Documentation/git-commit.txt

From: Junio C Hamano <junkio@cox.net>
Date: Dec 9, 2006, 04:25 UTC
Message-ID: <7vpsatelvv.fsf@assigned-by-dhcp.cox.net>
In-Reply-To: <Pine.LNX.4.64.0612082141260.2630@xanadu.home>

Nicolas Pitre <nico@cam.org> writes:

Show 7 quoted lines

> Frankly I feel unconfortable with this.
>
> 1) too many examples.
>
> Yes, examples are good, but somehow there is something in the current 
> text that make me feel they are not providing the clarification they 
> should.  Dunno... I think I'd still push them after option list.

Hmmm. I was merely trying to respond with recent requests on the list (might have been #git log) to make common usage examples more prominent. While I feel that following the UNIXy manpage tradition to push examples down is the right thing to do, you and I are not the primary audience of Porcelain manpages, so...

Show 5 quoted lines

> 2) explanation of how to resolve and commit a conflicting merge should 
>    really be found in git-merge.txt not in git-commit.txt.
>
> It feels a bit awkward to suddenly start talking about git ls-files and 
> merge here.

I agree that it looks a bit out of place; the primary reason I talked about the merge was to make it clear that a conflicted merge will still stage the changes for cleanly auto-resolved paths. In other words, it makes me feel uneasy that there is no mention of it in the list in your version that follows this sentence:

> +... All changes
> +to be committed must be explicitly identified using one of the following
> +methods:

It would make me happier if you had, at the end of enumeration, something like:

	Note that the contents of the paths that resolved
        cleanly by a conflicted merge are automatically staged
        for the next commit; you still need to explicitly
        identify what you want in the resulting commit using one
        of the above methods before concluding the merge.

Another reason I described the merge workflow is it would become much less clear why --only is useless in merge situation if the reader does not know that a conflicted merge stages the auto-resolved changes.