Re: Documentation/git-commit.txt

[Jakub Narebski <jnareb@gmail.com>]

Nicolas Pitre wrote:

> On Fri, 8 Dec 2006, Junio C Hamano wrote:
[...]
>> 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