Junio C Hamano <gitster@xxxxxxxxx> writes:
> Jari Aalto <jari.aalto@xxxxxxxxx> writes:
>
>> The manual mixed both caret(HEAD^) and tilde (HEAD~N) notation in
>> examples. This may be xconfusing to new users. The "counting" notation
>> HEAD~N likely to be grasped more easily because it allow successive
>> numbering 1, 2, 3 etc.
>
> I am mildly negative on this change.
>
> Referring to (rather, "having to refer to" to fix mistakes) the
> previous commit happens far more often than referring to an
> ancestor of an arbitrary generation away (i.e. HEAD~$n). I
> think it is a better idea to expose users early on that HEAD^
> notation which is shorter to type.
If the page contains/combines many different ways of doing things,
this creates confusion, especially if the distictions are not explained.
And it would be unnecessary to explain the HEAD^ and HEAD~1 similarities
in every page where these two get mixed.
PRICPLES:
1. The novice user is best served by making things simple and uniform.
2. Utilize concepts that may already be familar. E.g. other VCS/SCM tools
have concept of counting back revisions with negative numbers: -1,
-2, -3; so following this same idea in git manual pages would
already rang associated bells.
Like:
HEAD, HEAD~1, HEAD~2
If the syntax is changed in the middle (as it was in manual page),
that interrupts the kognitive flow of reading.
HEAD, HEAD^, HEAD~2
I'm sure when user progresses with his learning, the differences or
similarities of the notations become no-op.
But manual pages are served for wide audience. They are most
important to new users.
I hope we could strive for KISS is possible.
--
Welcome to FOSS revolution: we fix and modify until it shines
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
