patchDocumentation/git-reset.txt: Use HEAD~N syntax everywhere (unify examples)

The examples in the documentation refer to multiple ~N commits. To Keep the exampels unified with the same syntax, use ~N in all examples.

Signed-off-by: Jari Aalto <jari.aalto AT cante.net>
---
 Documentation/git-reset.txt |    6 +++---
 1 files changed, 3 insertions(+), 3 deletions(-)

Hi,

On Sat, 2 Feb 2008, Jari Aalto wrote:

AFAIR it was already shot down. Personally, I think it is not expecting too much of people to have the ambiguity between ~1 and ^1. Even worse, if you hide the ^-syntax from new users, they will be puzzled how to access the different parents of merge commits.

Ciao, Dscho

Jari Aalto <jari.aalto@cante.net> writes:

I personally think this is a regression, not an improvement.

People need to refer to the HEAD^ (one commit ago) much more often than HEAD~N for larger values of N. And we should give them exposure to HEAD^ and HEAD^^; both are faster and easier to type and read than HEAD~1 and HEAD~2.

Especially about HEAD~1, nobody sane would type that. It is there only for consistency.

Otherwise, twisted people would complain "I can say HEAD~4 instead of HEAD^^^^ and it helps brevity; but it is inconsistent that I cannot say HEAD~1 instead of HEAD^".

On Fri, Feb 01, 2008 at 06:59:29PM -0800, Junio C Hamano wrote:

I wonder if it wouldn't make sense to have ^ described with ^1 ^2, and add the possibility to also have ~, which would have the same meaning by side effect, described with ~1 ~2, etc.

The problem with ^ being described with ~1 ~2 is that it makes things harder to understand than they actually are. The real problem being that ^ sounds like having different meanings depending whether it's followed by a number or not.

Mike

* Sat 2008-02-02 Mike Hommey <mh@glandium.org> gmane.comp.version-control.git
* Message-Id: 20080202084406.GA15305@glandium.org

I use HEAD~1 always, because I think the consistency in learning the most important factor.

It does not matter what advanced users use. The documentation should primarily focus the newcomers.

The first question a newbie asks, if manual pages mixes syntaxes:

    What the heck "^" ?. I just saw HEAD~N, is the other one somehow
    special?

All the other examples refer to

    HEAD~N

Those used to git may prefer ^, but it does not follow that others necessarily do so and that that should be the "proper learning path". 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.

You consider all such users insane? It actually helps to select onlyt one sytax, and HEAD~N is much more readable without further explanations, (becasue people are already used to knowing, from other VCSs, what a HEAD or TIP is). It's not all that different from prefering the "--quiet" over "-q" e.g. e.g. in shell scripts.

Jari

Jari Aalto <jari.aalto@cante.net> writes:

I think that focusing on the fact that "HEAD^1" is peel-like operator,
selecting first parent of HEAD, That "HEAD^" is a shortcut for that,
and that "HEAD~3" is a shortcut for "HEAD^^^" similarly to how "3 * 2"
is a shortcut for "2 + 2 + 2" is better solution. "HEAD~1" and
"HEAD~2" are not shorter than original notation.
 

The documentation should cater to both advanced users and newcomers, unless it is specifically targeted towards newcomers like different intro documentation, or first part of Git User's Manual.

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

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'.

This is stupid example. Numbering revisions is possible only in centralized SCMs, or semi-centralized SCMs (with one repository given special, central position). You need an authority to assign sequential numbers to revisions.

Besides git uses the same notation, <rev1>..<rev2>, only it doesn't need '-r' option to select revision or revision range.

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

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.

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

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 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.

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  ->  ...

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.

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.

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.

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

Hi,

[don't cut the Cc' list. It is rude. _Especially_ if you cull the one you are responding to. Or do you like people looking the other way when they talk to you?]

On Sat, 2 Feb 2008, Jari Aalto wrote:

IMO this is not just a matter of "shorter" or "longer". People familiar with Git use both forms. So if you want to be able to receive help from Git experts, you better understand both forms.

That's why Git newbies have to learn about _both_ syntaxes right away. Keeping them dumb serves _noone_.

Ciao, Dscho

On Sat, Feb 02, 2008 at 02:59:43PM +0200, Jari Aalto wrote:

That could have been an argument for disallowing the HEAD^ syntax entirely, but it's too late for that.

Even if we eradicated all mention of ^ from the in-tree documentation, it would still show up in lots of out-of-tree documentation and examples. So we have to introduce it to newbies. Fortunately, it isn't that hard.

One way we can help them is by continuing to mix the two in examples, so let's continue with the current mixture.

--b.

* Sat 2008-02-02 J. Bruce Fields <bfields@fieldses.org>
* Message-Id: 20080202161813.GA19797@fieldses.org

Yeah let's continue as usual. And every time you need to explain the difference, when you could just teach one. The is no doubt that

    HEAD~N

is superior to

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

Count that. Optimizing keystrokes is hardly ever a brilliant idea from learning perspective.

Jari

lördagen den 2 februari 2008 skrev Jari Aalto:

You generally do not type HEAD~largeN, defining large as 3 or more. It's typically one or maybe two ^'s only. When the target is farther away you refer to the SHA-1 (or abbreviated form) tag or branch name instead, just to make sure you point to the right commit. 'HEAD~N' is useful for scripting and testing git itself, it's an advanced feature.

UI's that have only one way of accomplishing every task suck. Google this term "the case against user interface consistency" for reasons why, in case you haven't seen them for yourself.

-- robin

"J. Bruce Fields" <bfields@fieldses.org> writes:

It's not "it's too late" unless you are proposing to revamp git and to remove support for nonlinear history. With ^ and digits you can name anything. With ~ and digits you cannot.

Jari might be thinking that absolute newbies do not do any merges themselves, but even then, people need to know $commit^2 as soon as they start to interact with a history that have any merge. And people won't stay newbies forever.

Yeah, I am pretty much for it.

HEAD~2 and upwards are very good usability enhancement compared to "HEAD^^^(many uparrows...)". The reason we accept HEAD~1 is not because that is easier to type, nor easier to understand, nor makes you more productive. It is solely for consistency for the consistency's sake.

In an introductory document, we could present things in this order:

 1. "HEAD^" means the parent.  It's parent is "HEAD^^".

        Side note: You read the ^ operator from right to left.
        When you see "HEAD^^", you read the rightmost ^ as "the
        parent of", and tuck the remainder to form "the parent
        of HEAD^".

 2. You can have merges, so the above "_the_ parent" is a white
    lie.  The other branch that was merged is HEAD^2 (the second
    parent).

        Side note: this means "HEAD^" we introduced in 1. is
        "the first parent"; a natural consequence of this is
        that you could also say HEAD^1 if you really wanted to
        be explicit.

 3. As major parts of your history consists of a sequence of
    commits that have only single parent, you would often need
    to refer to ancestor that is Nth generation back following
    the first parent.  You can of course say "HEAD^^^^" to mean
    the first parent of the first parent of the first parent of
    the first parent of the HEAD, but that quickly becomes
    combersome.  Instead you can say HEAD~4.

        Side note: "HEAD^" we introduced in 1. is "the first
        generation ancestor in the first parent chain"; a
        natural consequence of this is that you could also say
        HEAD~1 if you really wanted to be explicit.

But that's for introductory document. Once people get past to the stage and understand what these two notation mean, we should freely use the more convenient form in the reference part of the documentation.

On Sat, Feb 02, 2008 at 02:59:43PM +0200, Jari Aalto wrote:

People may have different preferences and there is nothing wrong with that. However, imposing a single style on everyone is *wrong*. What you propose is to hide a legitimate syntax on the ground that you do not use it, and I don't think that is a good enough reason.

Wrong... and wrong again. First, this documentation is intended for all users. It is not "SVN Crash Course" or something like that intended for newcomers. Second, there is nothing wrong with having more than one way to express the same thing, and newcomers should be aware of that even if they prefer to use HEAD~1 all the time. If you don't tell them that, they may be confused when encounter it later, and they will encounter it sooner or later, because many of us use this ^-syntax.

It seems to me that your "proper learning path" is based solely on what you prefer, and not everyone shares your preferences here. In fact, ^-syntax is very natural to specify the _previous_ commit. Have you notice we usually say "previous", not "one commit before"?

First of all, this comparison is incorrect, because SVN uses fixed numbers, which does not change over time. The true equivalent of that numbers in Git is SHA-1. ~N-syntax is *alternative*, which is useful when you think in relative terms, and it is rarely used with for large N. Second, deficiency of other SCMs is not a good enough reason for Git to impose the same restriction on its users.

Besides, I don't know about Bzr, but SVN CLI is insane. If you need to do something simple, like compare your working directory with some tag, you end up typing:

 $ svn diff --old=A_VERY_LONG_URL/tags/tagname --new=.

with Git you can do that as simple as

 $ git diff tagname

Before SVN 1.4, there was no option to show the change made by some revision, so you had to type: svn diff -r PREV_REV:REV. One would think that after they added '-c' in SVN 1.4, no one needs to do that manually, but this option does not work in one of most common case:

 $ svn diff -c HEAD
 svn: Non-numeric change argument given to -c

so you need to figure out what is the number of the HEAD manually, and only then you can use 'svn diff -c'.

With git, you can do that easily:
 $ git show

Also, using 'svn switch' to switch between branches is slow and painful as hell. First, you have to type A_VERY_LONG_URL and if you happen to forgot to check in some changes, you end up with completely mess in your working directory. 'git checkout' has much more consistent behavior, and it does not destroy your work...

So, IMNSHO, recent versions of Git is way easier to use than SVN even in those cases where SVN provides similar functionality...

Dmitry

* Sun 2008-02-03 Dmitry Potapov <dpotapov@gmail.com>
* Message-Id: 20080203193024.GV29522@dpotapov.dyndns.org

Only if you're grown with git. Everywhere else the concept of HEAD or TIP is more natural, thus progression:

    HEAD, HEAD~1, HEAD~2

Jari

Jari Aalto <jari.aalto@cante.net> writes:

And you usually say "yesterday", "the day before" and not "1 day ago", "2 days ago".

<rev>^ means (first) parent of commit-ish <rev>, or 'previous' commit. <rev>~N means Nth parent in first-parent line of commit-ish <rev>; as you can see full explanation is decidely longer.

The fact that other SCMs are poorer in expressive power doesn't mean that we have to bend backwards and follow (well, not braindamaged, just poor) other SCM limitations / conventions. Git is git is git :-)

So "everywhere else" doesn't matter any... unless in "SCM rosetta" or something like that chapter in Git User's Manual.

On Mon, Feb 04, 2008 at 01:48:15AM +0200, Jari Aalto wrote:

Hmm... I always thought that the word "previous" existed well before Git...

How so?

Non sequitur.

Dmitry