Re: Documentation/git-commit.txt

Nicolas Pitre wrote:

On Fri, 8 Dec 2006, Junio C Hamano wrote:

[...]

quoted

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.

Sure, but the whole merge concept might still not make any sense at the 
moment the user is learning about commit.  In other words, the "commit" 
documentation must not depend on the "merge" concept.  It should rather 
be the other way around, i.e. the "merge" documentation can easily 
depend on the "commit" documentation.

Just like I carefully avoided talking about "commit -a" in the git-add 
man page to avoid circular conceptual dependencies.  But obviously the 
git-commit man page must talk about the "add" concept.

This way you get a progressive knowledge base with git-add which pretty 
much stands on its own, then you move to git-commit that depends on 
git-add, then you move to merging and resolving conflicts that depend on 
git-commit.  And so without being distracted by concepts you don't need 
to know just yet along the way.

IMVHO for reference documentation (and manpages for commands are such
documentation) it is more important to be complete, than to be
self-contained and without circular conceptual dependencies. The latter
(and defining things before using it) is more important for things like
tutorial or quickstart.

If one is not doing merge then one can skip the talk about merges. If one
git-commit complains about using --only (because of merge), one would
rather search for information in git-commit(1), not git-merge(1) or
git-pull(1); well, the merge might be result of git-checkout -m.
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git