Re: Documentation/git-commit.txt
- From
Jakub Narebski <jnareb@gmail.com>
- Date
- Dec 9, 2006, 20:49 UTC
- Message-ID
- <elf7bt$hiq$1@sea.gmane.org>
- In-Reply-To
- <Pine.LNX.4.64.0612091442470.2630@xanadu.home>
Nicolas Pitre wrote:
> On Fri, 8 Dec 2006, Junio C Hamano wrote:
[...]
Show 20 quoted lines
>> 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