Re: Documentation/git-commit.txt

Nicolas Pitre [off-list ref] 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:

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.