Documentation/git-reset.txt: Use HEAD~N syntax everywhere (unify examples)
PATCH 1/1 Documentation/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.
--- Documentation/git-reset.txt | 6 +++--- 1 files changed, 3 insertions(+), 3 deletions(-)
Documentation/git-reset.txt +3 -3
@@ -58,7 +58,7 @@ Undo a commit and redo:: + ------------ $ git commit ... -$ git reset --soft HEAD^ <1> +$ git reset --soft HEAD~1 <1> $ edit <2> $ git commit -a -c ORIG_HEAD <3> ------------
@@ -80,7 +80,7 @@ $ git commit ... $ git reset --hard HEAD~3 <1> ------------ + -<1> The last three commits (HEAD, HEAD^, and HEAD~2) were bad +<1> The last three commits (HEAD, HEAD~1, and HEAD~2) were bad and you do not want to ever see them again. Do *not* do this if you have already given these commits to somebody else.
@@ -165,7 +165,7 @@ $ git checkout master $ fix fix fix $ git commit ;# commit with real log $ git checkout feature -$ git reset --soft HEAD^ ;# go back to WIP state <2> +$ git reset --soft HEAD~1 ;# go back to WIP state <2> $ git reset <3> ------------ +
Signature · 6 lines
1.5.4-rc5.GIT-dirty -- Welcome to FOSS revolution: we fix and modify until it shines
Quoted 11 lines · Jari Aalto
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>-$ git reset --soft HEAD^ <1>
+$ git reset --soft HEAD~1 <1>
-<1> The last three commits (HEAD, HEAD^, and HEAD~2) were bad +<1> The last three commits (HEAD, HEAD~1, and HEAD~2) were bad -$ git reset --soft HEAD^ ;# go back to WIP state <2> +$ git reset --soft HEAD~1 ;# go back to WIP state <2>
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^".
Quoted 21 lines · Junio C Hamano
Quoted 11 lines · Jari Aalto
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>-$ git reset --soft HEAD^ <1>
+$ git reset --soft HEAD~1 <1>
-<1> The last three commits (HEAD, HEAD^, and HEAD~2) were bad +<1> The last three commits (HEAD, HEAD~1, and HEAD~2) were bad -$ git reset --soft HEAD^ ;# go back to WIP state <2> +$ git reset --soft HEAD~1 ;# go back to WIP state <2>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.
Quoted 6 lines
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^".
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 <[email protected]> gmane.comp.version-control.git
* Message-Id: [email protected]
Quoted 10 lines
Quoted 10 lines
Quoted 7 lines
-$ git reset --soft HEAD^ <1>
+$ git reset --soft HEAD~1 <1>
-<1> The last three commits (HEAD, HEAD^, and HEAD~2) were bad +<1> The last three commits (HEAD, HEAD~1, and HEAD~2) were bad -$ git reset --soft HEAD^ ;# go back to WIP state <2> +$ git reset --soft HEAD~1 ;# go back to WIP state <2>People need to refer to the HEAD^ (one commit ago) much more often than HEAD~N for larger values of N.
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
...etcIt's unfortunate is the focus is given to comments like "easier type", when the context is the manual pages.
Quoted 1 line
Quoted 1 line
Especially about HEAD~1, nobody sane would type that.
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
Signature · 1 line
Welcome to FOSS revolution: we fix and modify until it shines
Quoted 10 lines · Jari Aalto
* Sat 2008-02-02 Mike Hommey <[email protected]> gmane.comp.version-control.git
* Message-Id: [email protected]Quoted 7 lines
Quoted 7 lines
Quoted 7 lines
-$ git reset --soft HEAD^ <1>
+$ git reset --soft HEAD~1 <1>
-<1> The last three commits (HEAD, HEAD^, and HEAD~2) were bad +<1> The last three commits (HEAD, HEAD~1, and HEAD~2) were bad -$ git reset --soft HEAD^ ;# go back to WIP state <2> +$ git reset --soft HEAD~1 ;# go back to WIP state <2>
Quoted 8 lines
Quoted 2 lines
Quoted 2 lines
People need to refer to the HEAD^ (one commit ago) much more often than HEAD~N for larger values of N.
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.
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 <[email protected]>
* Message-Id: [email protected]
Quoted 10 lines · Jari Aalto
Quoted 5 lines
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.
That could have been an argument for disallowing the HEAD^ syntax entirely, but it's too late for that.
Quoted 7 lines
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.
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
Signature · 1 line
Welcome to FOSS revolution: we fix and modify until it shines
lördagen den 2 februari 2008 skrev Jari Aalto:
Quoted 11 lines
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.
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
Quoted 5 lines · J. Bruce Fields
Quoted 2 lines
It does not matter what advanced users use. The documentation should primarily focus the newcomers.
That could have been an argument for disallowing the HEAD^ syntax entirely, but it's too late for that.
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.
Quoted 4 lines
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.
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.
Quoted 2 lines
One way we can help them is by continuing to mix the two in examples, so let's continue with the current mixture.
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.
Quoted 3 lines · Jari Aalto
I use HEAD~1 always, because I think the consistency in learning the most important factor.
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.
Quoted 2 lines
It does not matter what advanced users use. The documentation should primarily focus the newcomers.
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.
Quoted 2 lines
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".
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"?
Quoted 6 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
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 <[email protected]>
* Message-Id: [email protected]
Quoted 2 lines
^-syntax is very natural to specify the _previous_ commit. Have you notice we usually say "previous", not "one commit before"?
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
Signature · 1 line
Welcome to FOSS revolution: we fix and modify until it shines
Quoted 6 lines · Jari Aalto
* Sun 2008-02-03 Dmitry Potapov <[email protected]>
* Message-Id: [email protected]Quoted 2 lines
^-syntax is very natural to specify the _previous_ commit. Have you notice we usually say "previous", not "one commit before"?
Only if you're grown with git.
Hmm... I always thought that the word "previous" existed well before Git...
Quoted 2 lines
Everywhere else the concept of HEAD or
TIP is more natural,
How so?
Quoted 3 lines
thus progression:
HEAD, HEAD~1, HEAD~2
Non sequitur.
Dmitry
Quoted 5 lines · Jari Aalto
* Sun 2008-02-03 Dmitry Potapov <[email protected]>
* Message-Id: [email protected]Quoted 3 lines
^-syntax is very natural to specify the _previous_ commit. Have you notice we usually say "previous", not "one commit before"?
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.
Quoted 4 lines
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
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.
Signature · 3 lines
Jakub Narebski Poland ShadeHawk on #git
Quoted 10 lines · Jari Aalto
* Sat 2008-02-02 Mike Hommey <[email protected]> gmane.comp.version-control.git
* Message-Id: [email protected]Quoted 7 lines
Quoted 7 lines
Quoted 7 lines
-$ git reset --soft HEAD^ <1>
+$ git reset --soft HEAD~1 <1>
-<1> The last three commits (HEAD, HEAD^, and HEAD~2) were bad +<1> The last three commits (HEAD, HEAD~1, and HEAD~2) were bad -$ git reset --soft HEAD^ ;# go back to WIP state <2> +$ git reset --soft HEAD~1 ;# go back to WIP state <2>
Quoted 5 lines
Quoted 2 lines
Quoted 2 lines
People need to refer to the HEAD^ (one commit ago) much more often than HEAD~N for larger values of N.
I use HEAD~1 always, because I think the consistency in learning the most important factor.
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.
Quoted 2 lines
It does not matter what advanced users use. The documentation should primarily focus the newcomers.
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.
Quoted 5 lines
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?
Quoted 7 lines
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".
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'.
Quoted 9 lines
People usually migrate to git from other VCSs, which have very consistent UI - There are no alternatives
-r1:10 Subversion -r1..19 Bzr ...etcIt's unfortunate is the focus is given to comments like "easier type", when the context is the manual pages.
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.
Quoted 7 lines
Quoted 1 line
Quoted 1 line
Especially about HEAD~1, nobody sane would type that.
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.
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.
Signature · 4 lines
Jakub Narebski In related news: there is really no question that bike sheds should be painted red. Really. (Johannes Schindelin)
* Sat 2008-02-02 Jakub Narebski <[email protected]>
* Message-Id: [email protected]
Quoted 5 lines
Quoted 2 lines · Jari Aalto
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.
Quoted 1 line
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.
Quoted 4 lines
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 -> ...Quoted 3 lines
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.
Quoted 11 lines
Quoted 9 lines
People usually migrate to git from other VCSs, which have very consistent UI - There are no alternatives
-r1:10 Subversion -r1..19 Bzr ...etcIt'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.
Quoted 2 lines
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.
Quoted 3 lines
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
Signature · 1 line
Welcome to FOSS revolution: we fix and modify until it shines
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?]
Quoted 10 lines · Jari Aalto
* Sat 2008-02-02 Jakub Narebski <[email protected]>
* Message-Id: [email protected]Quoted 5 lines
Quoted 2 lines · Jari Aalto
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"
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
Hi,
Quoted 2 lines · Jari Aalto
The examples in the documentation refer to multiple ~N commits. To Keep the exampels unified with the same syntax, use ~N in all examples.
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