On Sat, Sep 01, 2007 at 02:40:22AM -0700, Junio C Hamano wrote: > Jari Aalto <jari.aalto@xxxxxxxxx> 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. 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^^. - 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
