Re: [PATCH] Documentation/git-reset.txt: Use HEAD~N syntax everywhere (unify examples)

From: Jari Aalto <jari.aalto@cante.net>
Date: Feb 2, 2008, 20:10 UTC
Message-ID: <abmj3ysj.fsf@blue.sea.net>
In-Reply-To: <m3d4rf7a4r.fsf@localhost.localdomain>

* Sat 2008-02-02 Jakub Narebski <jnareb@gmail.com>
* Message-Id: m3d4rf7a4r.fsf@localhost.localdomain

Show 5 quoted lines

> Jari Aalto <jari.aalto@cante.net> writes:
>> I use HEAD~1 always, because I think the consistency in learning the
>> most important factor.
>
> "HEAD~1" and "HEAD~2" are not shorter than original notation.

I'm afreaid that "optiomization" is seen a virtua in the manual pages. I certainly do not wish to use "shorter", if it would mean "less readable"

It's certianly true that the cognitive burder to see foreign construct is higer than, when you can associate a thing to familiar one.

Here, he familiarity from other CVSs is term HEAD or TIP, which follows that

    HEAD~1

in context of other similar ones (HEAD~2, HEAD~2 ...) is self evident without further explanations.

> The documentation should cater to both advanced users and newcomers,

The advanced user's don't matter. People will become advanced over time, with their own learning paths.

The documentation should prefer the most readable format. There can always be separate geek manaual if needed.

> IMHO the sequence: 
>   "HEAD^1"     -> "HEAD^", 
>   "HEAD^1^1^1" -> "HEAD^^^" -> "HEAD~3"
> is the proper sequence to teach.

Only from GIT perspective, if you've gwon with git. For every other designer used to the CVSs, it's the RCS/CVS/SVN temrinology and concept of HEAD. Only then comes the other issues.

We don't expect to grasp the "decentralization", without first being familiar with older systems, so the more natural progression is:

    HEAD~1  ->  HEAD^1 > HEAD^
    HEAD~2  ->  ...

> Especially that "rev^sth" is used also for other things, like
> "HEAD^{tree}", or "v1.3.0^{commit}" peeling operators, or even
> "master^0" used to force detach HEAD to 'master'.

Only very small grou of persons will ever need very advanced features. I don't even understand what those mean and haven't have any ose for those. The "get previous version", "get N version backward in diff" are the 99% daily bread.

Show 11 quoted lines

>> People usually migrate to git from other VCSs, which have very
>> consistent UI - There are no alternatives
>> 
>>     -r1:10      Subversion
>>     -r1..19     Bzr
>>     ...etc
>> 
>> It's unfortunate is the focus is given to comments like "easier type",
>> when the context is the manual pages.
>
> This is stupid example.

It's perfect example. The key was "consistent UI", which git does not yet have, nor does the documentation. The version numers were not my point.

You really want to count this:

    HEAD^^^^^^^^^^^^

How many revisions again that was? That tells something about the UI.

> It is also much less powerfull, as it can only follow first-parent
> line. In the presence of merges you usually use ^n more.

Everything is powerfull in git. There is no doubt about it, but there is difference how "to serve the audience". If Git wishes, and I sincerely hope, that the focus is not "advanced users" per se.

> That said, I personally don't have strong preference whether to use
> "HEAD", "HEAD^", "HEAD^^", "HEAD~3" in examples, or "HEAD", "HEAD~1",
> "HEAD~2", "HEAD~3". It is a bit of "bikeshed" discussion.

I feel that this is very essence of the the path. What, if any, is the strategy to develop the documentation towards. What kind of conversations, exmaples and notations are used to convey the content in uniform way to the reader.

Jari

-- 
Welcome to FOSS revolution: we fix and modify until it shines