Jari Aalto [off-list ref] writes:
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 still would prefer to teach people HEAD^ earlier. If you _REALLY_
insist, I can live with spelling the HEAD~2 as HEAD^^ for
consistency.
Wasn't with you that earlier I discussed that very basic things
such as revision naming and range notation should be moved from
rev-list documentation to more central place, and sructure the
documentation in such a way that these should be read even
before individual manual pages are consulted? If we follow
that, then by the time people read these examples, they _ought_
to know that HEAD~1 is a longer-to-type way to say HEAD^ already.
On Sat, Sep 01, 2007 at 02:40:22AM -0700, Junio C Hamano wrote:
Jari Aalto [off-list ref] writes:
quoted
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 still would prefer to teach people HEAD^ earlier. If you _REALLY_
insist, I can live with spelling the HEAD~2 as HEAD^^ for
consistency.
Wasn't with you that earlier I discussed that very basic things
such as revision naming and range notation should be moved from
rev-list documentation to more central place, and sructure the
documentation in such a way that these should be read even
before individual manual pages are consulted? If we follow
that, then by the time people read these examples, they _ought_
to know that HEAD~1 is a longer-to-type way to say HEAD^ already.
Well I am a new user to git and I didn't find the mixed notation
confusing at all. Perhaps this is because I read the tutorial first,
then the git user manual which both explain this clearly.
In either case I think eliminating either notation from the man pages is
a bad idea. I'm quite confident that in the worst case a user will
think that if they want to refer to the parent they have to say HEAD^
and if they want to refer to the grandparent they have to say HEAD~2.
Most won't even find that strange since HEAD^ just seems shorter. I
also think many users will be smart enough to infer that if they wanted
to they could say HEAD~3 or perhaps HEAD~1, though unless I saw it
somewhere I might not have guessed HEAD^^.
Shawn Bohrer [off-list ref] writes:
On Sat, Sep 01, 2007 at 02:40:22AM -0700, Junio C Hamano wrote:
quoted
Jari Aalto [off-list ref] writes:
quoted
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 still would prefer to teach people HEAD^ earlier. If you _REALLY_
insist, I can live with spelling the HEAD~2 as HEAD^^ for
consistency.
Well I am a new user to git and I didn't find the mixed notation
confusing at all. Perhaps this is because I read the tutorial first,
then the git user manual which both explain this clearly.
Naturally one's learning path is naturally different. Did you come
from other SCM/VCS before intorduced to git?
In either case I think eliminating either notation from the man pages is
a bad idea.
That was not proposed. There a mnay pages that use and shoudl use the
^ notations. I was proposing that only (git-COMMAND) were dealt with.
After all, the ^ very differento to what other SCM/VCSs use.
Jari
--
Welcome to FOSS revolution: we fix and modify until it shines