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:
+... 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.
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
On Fri, Dec 08, 2006 at 08:25:24PM -0800, Junio C Hamano wrote:
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...
I think manpages are primarily reference documents, so it's more
important to be able to get to the list of options without paging down
too far....
We could always say "see EXAMPLES below for more detail", or "see the
chapter 3 of the tutorial/user manual/whatever".
On Fri, 8 Dec 2006, Junio C Hamano wrote:
Nicolas Pitre [off-list ref] writes:
quoted
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...
Sure, but sometimes too much is just as bad as not enough. And given
the amount of text in your version I feel the essence of the information
gets dilluted too much.
quoted
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:
quoted
+... 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.
But why couldn't this be in the git-merge man page instead? That is
precisely the sort of addition that makes me feel like we're trying to
say too much at the same time. When in the context of learning how
"commit" works, it is certainly not necessary to talk about how "merge"
works. That should really be mentioned in the "merging" documentation
(with a link to git-commit for more options on commit).
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.