Re: Documentation/git-commit.txt

[Junio C Hamano <junkio@cox.net>]

Nicolas Pitre <nico@cam.org> writes:

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

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