[PATCH] git-reset.txt: Use commit~1 notation over commit^

[PATCH] git-reset.txt: Use commit~1 notation over commit^

[jari.aalto]

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

In order to easily read paragraphs, use same notation and do not mixed
both ^ and ~N. This helps digesting the information more easier as the
tokens stay the same (dcumentation uniformity).

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

diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index fd72976..b679c99 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -129,7 +129,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>
 ------------
@@ -166,7 +166,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.  (See the
 "RECOVERING FROM UPSTREAM REBASE" section in linkgit:git-rebase[1] for
@@ -237,7 +237,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>
 ------------
 +
-- 
1.7.2.3

Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^

[Drew Northup]

On Wed, 2010-12-01 at 20:14 +0200, jari.aalto@cante.net wrote:
> From: Jari Aalto <jari.aalto@cante.net>
> 
> In order to easily read paragraphs, use same notation and do not mixed
> both ^ and ~N. This helps digesting the information more easier as the
> tokens stay the same (dcumentation uniformity).
> 
> Signed-off-by: Jari Aalto <jari.aalto@cante.net>
> ---
>  Documentation/git-reset.txt |    6 +++---
>  1 files changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
> index fd72976..b679c99 100644
> --- a/Documentation/git-reset.txt
> +++ b/Documentation/git-reset.txt
> @@ -129,7 +129,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>
>  ------------
> @@ -166,7 +166,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.  (See the
>  "RECOVERING FROM UPSTREAM REBASE" section in linkgit:git-rebase[1] for
> @@ -237,7 +237,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>
>  ------------
>  +

I have to disagree here. Part of the task of good documentation is to
show not just what any one user may prefer (unless it is an accepted
standard, such as an RFC) but also what is possible. Removing the non
"~" examples is actually a disservice to the documentation reader in a
great many cases. What makes more sense in this case is to refer at some
point to the documentation which describes the allowed reference
formats. This makes it clear that:
(1) There are several allowed reference formats, and these are examples
using them;
(2) These, over here, are descriptions of the allowed reference formats.

Also, strictly speaking, each separate operation example is a
"paragraph" inside of a subsection and "EXAMPLES" is the containing
section. If you look at it this way it is already reasonably internally
consistent.

-- 
-Drew Northup N1XIM
   AKA RvnPhnx on OPN
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^

[Jari Aalto]

2010-12-01 21:13 Drew Northup <drew.northup@maine.edu>:
> "~" examples is actually a disservice to the documentation reader in a

Well. What I can say. I have witnessed close hand for thousands of
learners. Unfortunately they don't get educated that way. Bright people
may. But I'd rather address average Joe who is switching from SVN or the
like.

What people appreciate, while learning, is constency. Sticking to one
notation is better than giving multiple choices. And the "^" isn't
exactly readable, don't you agree?

    HEAD^^^^^^^^

Right. How many was there again?

Besides, the "^" key was probably inverted to work easily in US keybord.
It is not so in other parts of the world.

The fine print can be reserved to git-rev-parse(1) where you can get all
the details.

Jari

Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^

[Kevin Ballard]

On Dec 1, 2010, at 11:37 AM, Jari Aalto wrote:

> 2010-12-01 21:13 Drew Northup <drew.northup@maine.edu>:
>> "~" examples is actually a disservice to the documentation reader in a
> 
> Well. What I can say. I have witnessed close hand for thousands of
> learners. Unfortunately they don't get educated that way. Bright people
> may. But I'd rather address average Joe who is switching from SVN or the
> like.
> 
> What people appreciate, while learning, is constency. Sticking to one
> notation is better than giving multiple choices. And the "^" isn't
> exactly readable, don't you agree?
> 
>    HEAD^^^^^^^^
> 
> Right. How many was there again?

Your patch isn't touching any example of HEAD^^^^^^^. Every single one that
you've changed was a simple HEAD^. And this, I feel, is absolutely wrong.
HEAD^ is far more common notation than HEAD~1, and should be preserved as
such in the manpage. I also agree with Drew that giving examples with
different notation is useful to show alternative syntax. If the manpages
all use a single notation when there are several options, it gives the
impression that this one notation is what you should always use. And that's
not what the manpage is trying to say.

-Kevin Ballard

Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^

[Jari Aalto]

2010-12-02 00:01 Kevin Ballard <kevin@sb.org>:
> On Dec 1, 2010, at 11:37 AM, Jari Aalto wrote:
>
> Your patch isn't touching any example of HEAD^^^^^^^. Every single one that
> you've changed was a simple HEAD^.

Yes of course:

    >> What people appreciate, while learning, is constency. Sticking to one
    >> notation is better than giving multiple choices.

> And this, I feel, is absolutely wrong.

Whatever you feel. Consistency is important viewpoint. Try explaining to
a group of people these two variations. The make them write scripts to
use git commands. Guess which notation they choose? The "^" isnt' even
scriptable.

Jari

Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^

[Kevin Ballard]

On Dec 1, 2010, at 2:49 PM, Jari Aalto wrote:

> Whatever you feel. Consistency is important viewpoint. Try explaining to
> a group of people these two variations. The make them write scripts to
> use git commands. Guess which notation they choose? The "^" isnt' even
> scriptable.

What do you mean? I've personally taught nearly everybody at my office how
to use git, and every single one of them uses ^ when they want to go to the
previous commit and ~n when they want to go n commits back (where n > 1).
Even the few people who knew git before I talked to them use this convention.
And guess where those people learned it? By seeing the different syntaxes
in the manpage. Even for the people I taught, I never told them expressly to
use HEAD^ vs HEAD~3, but through the combination of my examples and the
examples in the manpages, they all understood both operators and how to use
them without any difficulty whatsoever.

You stated that you have "witnessed close hand for thousands of learners."
And you state that these people don't understand this sort of documentation.
I don't mean to give offense, but have you ever considered what the common
element here is?

-Kevin Ballard

Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^

[Junio C Hamano]

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

> What people appreciate, while learning, is constency. Sticking to one
> notation is better than giving multiple choices. And the "^" isn't
> exactly readable, don't you agree?
>
>     HEAD^^^^^^^^
>
> Right. How many was there again?

There is no question that you need to really count them, and that is why
we invented HEAD~8 notation in the first place.  It however is wrong to
use the above illustration to defend your change that replaces "HEAD^"
with "HEAD~1".  

The thing is, you need to name/call the previous one a lot more often than
you need to call the eighth previous one.  The previous one "HEAD~1" is
special because it directly relates to the current commit (it is the first
parent of the current commit) and that is why people often need to access
it.

And "HEAD^" is shorter and much easier to type, and more importantly, it
is more often used in the wild, so the readers of the documentation needs
to know it anyway to understand what other people do.

Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^

[Jari Aalto]

2010-12-02 00:06 Junio C Hamano <gitster@pobox.com>:
> And "HEAD^" is shorter and much easier to type

I don't know in which part of world that is, probably only using US
keyboard. Not so elsewhere with keyboards more than just only ASCII
characters.

Jari

Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^

[Andreas Schwab]

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

> 2010-12-02 00:06 Junio C Hamano <gitster@pobox.com>:
>> And "HEAD^" is shorter and much easier to type
>
> I don't know in which part of world that is, probably only using US
> keyboard. Not so elsewhere with keyboards more than just only ASCII
> characters.

On a German keyboard ~ is awkward to type (AltGr-+) whereas ^ is on an
unshifted key.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^

[Jari Aalto]

2010-12-02 02:07 Andreas Schwab <schwab@linux-m68k.org>:
> Jari Aalto <jari.aalto@cante.net> writes:
>
>> 2010-12-02 00:06 Junio C Hamano <gitster@pobox.com>:
>>> And "HEAD^" is shorter and much easier to type
>>
>> I don't know in which part of world that is, probably only using US
>> keyboard. Not so elsewhere with keyboards more than just only ASCII
>> characters.
>
> On a German keyboard ~ is awkward to type (AltGr-+) whereas ^ is on an
> unshifted key.

And notebook/laptops in German? For FI-keyboards everything is pain.

Jari

Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^

[Santi Béjar]

On Wed, Dec 1, 2010 at 11:06 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Jari Aalto <jari.aalto@cante.net> writes:
>
>> What people appreciate, while learning, is constency. Sticking to one
>> notation is better than giving multiple choices. And the "^" isn't
>> exactly readable, don't you agree?
>>
>>     HEAD^^^^^^^^
>>
>> Right. How many was there again?
>
> There is no question that you need to really count them, and that is why
> we invented HEAD~8 notation in the first place.  It however is wrong to
> use the above illustration to defend your change that replaces "HEAD^"
> with "HEAD~1".
>
> The thing is, you need to name/call the previous one a lot more often than
> you need to call the eighth previous one.  The previous one "HEAD~1" is
> special because it directly relates to the current commit (it is the first
> parent of the current commit) and that is why people often need to access
> it.

Additionaly, you must know about the ^ notation. That is the only way
refer to the second parent HEAD^2, for example.

HTH,
Santi

Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^

[Jari Aalto]

2010-12-02 00:56 Santi Béjar <santi@agolina.net>:
> On Wed, Dec 1, 2010 at 11:06 PM, Junio C Hamano <gitster@pobox.com> wrote:
>
> Additionaly, you must know about the ^ notation. That is the only way
> refer to the second parent HEAD^2, for example.

If "must" is a requirement, I have to regret that there has yet to have
been a situation where I would ahve a need to refer to "second parent".

I guess most of the basic features can be used without it.

Jari

Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^

[Miles Bader]

Jari Aalto <jari.aalto@cante.net> writes:
>> Additionaly, you must know about the ^ notation. That is the only way
>> refer to the second parent HEAD^2, for example.
>
> If "must" is a requirement, I have to regret that there has yet to have
> been a situation where I would ahve a need to refer to "second parent".
>
> I guess most of the basic features can be used without it.

It doesn't matter.  There needs to be a better reason than "Jari doesn't
like it."

-Miles

-- 
Somebody has to do something, and it's just incredibly pathetic that it
has to be us.  -- Jerry Garcia

Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^

[Jari Aalto]

2010-12-02 08:17 Miles Bader <miles@gnu.org>:
> Jari Aalto <jari.aalto@cante.net> writes:
>
>>> Additionaly, you must know about the ^ notation. That is the only way
>>> refer to the second parent HEAD^2, for example.
>>
>> If "must" is a requirement, I have to regret that there has yet to have
>> been a situation where I would ahve a need to refer to "second parent".
>>
>> I guess most of the basic features can be used without it.
>
> It doesn't matter.  There needs to be a better reason than "Jari doesn't
> like it."

This has nothing to do with liking. It how infomation is read. When
information is consistent, it lessens cognitive load.

In the  "fine print" git-rev-parse(1) there can be the gory details.

most of the commenters probably are already experts and therefor wear
"expert glasses on". It's not necessarily the same for starters.
Certainly not when you try to teach 100 people. One form is much better
in that situation than variations. You only do it at the end:

    "[After finishing 6 week training] Btw, if you need more details
    look at...."

Experts can later pick anything they want.

Jari

Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^

[Drew Northup]

On Thu, 2010-12-02 at 14:14 +0200, Jari Aalto wrote:
> 2010-12-02 08:17 Miles Bader <miles@gnu.org>:
> > Jari Aalto <jari.aalto@cante.net> writes:
> >
> >>> Additionaly, you must know about the ^ notation. That is the only way
> >>> refer to the second parent HEAD^2, for example.
> >>
> >> If "must" is a requirement, I have to regret that there has yet to have
> >> been a situation where I would ahve a need to refer to "second parent".
> >>
> >> I guess most of the basic features can be used without it.
> >
> > It doesn't matter.  There needs to be a better reason than "Jari doesn't
> > like it."
> 
> This has nothing to do with liking. It how infomation is read. When
> information is consistent, it lessens cognitive load.
> 
> In the  "fine print" git-rev-parse(1) there can be the gory details.
> 
> most of the commenters probably are already experts and therefor wear
> "expert glasses on". It's not necessarily the same for starters.
> Certainly not when you try to teach 100 people. One form is much better
> in that situation than variations. You only do it at the end:
> 
>     "[After finishing 6 week training] Btw, if you need more details
>     look at...."
> 
> Experts can later pick anything they want.
> 
> Jari

I have worked in instructional settings, as the instructor. I can say
flat out that this is an incomplete view of the learning patterns of
people being newly exposed to a concept or a technology. Besides, many
people who consult manpages often think of themselves as experts (and
may think better of the idea after consulting the documentation).

The reality is that learning is not nearly as proscribed and rote a
process as you are making it out to be. Rote memorization is good for
learning multiplications tables, alphabets, and the approximate values
of e and pi. It is not particularly suited for learning grammars and
syntaxes--which is why language and algebra are typically not taught
that way. Programming and using computers benefits greatly from
presenting multiple varied examples--even to the supposed experts who
probably don't know it all either.

Leave the odd examples in the manpages--people depend on them being
there.

-- 
-Drew Northup N1XIM
   AKA RvnPhnx on OPN
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^

[Miles Bader]

Jari Aalto <jari.aalto@cante.net> writes:
>> It doesn't matter.  There needs to be a better reason than "Jari doesn't
>> like it."
>
> This has nothing to do with liking. It how infomation is read. When
> information is consistent, it lessens cognitive load.

No, it has to do with your trying to impose your personal tastes.

^ (and ^^, etc) is a simpler and easier concept to deal with, and
sufficient for the vast majority of tasks -- beyond 1 or 2 levels,
it's typically easier to just use an absolute reference cut-and-pasted
from git log output than it is to count commits and get the right
value to use with ~ (and from experience, unless you're careful, it's
very easy to get counts for ~ wrong).  So it's ~ that's the "expert
notation", not ^.

[How do I know?   Because I've _been_ a git beginner, and spent a long
time trying to learn git.]

-Miles

-- 
Discriminate, v.i. To note the particulars in which one person or thing is,
if possible, more objectionable than another.

Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^

[jari]

| ^ (and ^^, etc) is a simpler and easier concept to deal with, and
| ... very easy to get counts for ~ wrong).  So it's ~ that's the
| "expert notation", not ^.

Not that it matters, but have you happende to notice that all git
outputs use

    commit~N

notation. Not the

    commit^

Jari

Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^

[Andreas Schwab]

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

> Not that it matters, but have you happende to notice that all git
> outputs use
>
>     commit~N
>
> notation. Not the
>
>     commit^

Did you try "git show-branch -a" recently?

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^

[Junio C Hamano]

Andreas Schwab <schwab@linux-m68k.org> writes:

> jari <jari.aalto@cante.net> writes:
>
>> Not that it matters, but have you happende to notice that all git
>> outputs use
>>
>>     commit~N
>>
>> notation. Not the
>>
>>     commit^
>
> Did you try "git show-branch -a" recently?

Perhaps we need to also fix "git name-rev master^" which currently does
not try to reduce "master~1" to "master^".

Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^

[Jeff King]

On Thu, Dec 02, 2010 at 09:55:03AM -0800, Junio C Hamano wrote:

> Perhaps we need to also fix "git name-rev master^" which currently does
> not try to reduce "master~1" to "master^".

This patch does it:

diff --git a/builtin/name-rev.c b/builtin/name-rev.c
index c946a82..417bae5 100644
--- a/builtin/name-rev.c
+++ b/builtin/name-rev.c
@@ -142,8 +142,12 @@ static const char *get_rev_name(const struct object *o)
 		int len = strlen(n->tip_name);
 		if (len > 2 && !strcmp(n->tip_name + len - 2, "^0"))
 			len -= 2;
-		snprintf(buffer, sizeof(buffer), "%.*s~%d", len, n->tip_name,
-				n->generation);
+		if (n->generation == 1)
+			snprintf(buffer, sizeof(buffer), "%.*s^", len,
+				 n->tip_name);
+		else
+			snprintf(buffer, sizeof(buffer), "%.*s~%d", len,
+				 n->tip_name, n->generation);
 
 		return buffer;
 	}

but I am not sure the results are always more readable. I think "foo^"
is perhaps nicer than "foo~1". But in more complex examples, I kind of
think the ~1 is easier to read. E.g.:

  # old
  $ git name-rev 9904fadf
  9904fadf tags/v1.7.3-rc2~1^2~1

  # new
  $ git name-rev 9904fadf
  9904fadf tags/v1.7.3-rc2~1^2^

Somehow the visual appearance of "^2^" ends up being more confusing to
me than ~1^2~1, I guess because in the latter there is a regular set of
modifier-number pairs.

But I admit that is just my subjective opinion.

-Peff

Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> On Thu, Dec 02, 2010 at 09:55:03AM -0800, Junio C Hamano wrote:
>
>> Perhaps we need to also fix "git name-rev master^" which currently does
>> not try to reduce "master~1" to "master^".
>
> This patch does it:
>
> diff --git a/builtin/name-rev.c b/builtin/name-rev.c
> index c946a82..417bae5 100644
> --- a/builtin/name-rev.c
> +++ b/builtin/name-rev.c
> @@ -142,8 +142,12 @@ static const char *get_rev_name(const struct object *o)
>  		int len = strlen(n->tip_name);
>  		if (len > 2 && !strcmp(n->tip_name + len - 2, "^0"))
>  			len -= 2;
> -		snprintf(buffer, sizeof(buffer), "%.*s~%d", len, n->tip_name,
> -				n->generation);
> +		if (n->generation == 1)
> +			snprintf(buffer, sizeof(buffer), "%.*s^", len,
> +				 n->tip_name);
> +		else
> +			snprintf(buffer, sizeof(buffer), "%.*s~%d", len,
> +				 n->tip_name, n->generation);
>  
>  		return buffer;
>  	}
>
> but I am not sure the results are always more readable. I think "foo^"
> is perhaps nicer than "foo~1". But in more complex examples, I kind of
> think the ~1 is easier to read. E.g.:
>
>   # old
>   $ git name-rev 9904fadf
>   9904fadf tags/v1.7.3-rc2~1^2~1
>
>   # new
>   $ git name-rev 9904fadf
>   9904fadf tags/v1.7.3-rc2~1^2^

Curious.  Why does the "first take the first parent of rc2" is left as-is,
while "then lastly take its parent" does get shortened?

> Somehow the visual appearance of "^2^" ends up being more confusing to
> me than ~1^2~1, I guess because in the latter there is a regular set of
> modifier-number pairs.
>
> But I admit that is just my subjective opinion.
>
> -Peff

Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^

[Jeff King]

On Thu, Dec 02, 2010 at 10:54:03AM -0800, Junio C Hamano wrote:

> > but I am not sure the results are always more readable. I think "foo^"
> > is perhaps nicer than "foo~1". But in more complex examples, I kind of
> > think the ~1 is easier to read. E.g.:
> >
> >   # old
> >   $ git name-rev 9904fadf
> >   9904fadf tags/v1.7.3-rc2~1^2~1
> >
> >   # new
> >   $ git name-rev 9904fadf
> >   9904fadf tags/v1.7.3-rc2~1^2^
> 
> Curious.  Why does the "first take the first parent of rc2" is left as-is,
> while "then lastly take its parent" does get shortened?

Because my patch is crappy and I didn't spend more than 30 seconds
testing it? :)

It needs a similar change elsewhere, so the full patch should be:

diff --git a/builtin/name-rev.c b/builtin/name-rev.c
index c946a82..03d7bce 100644
--- a/builtin/name-rev.c
+++ b/builtin/name-rev.c
@@ -64,9 +64,15 @@ copy_data:
 
 			if (len > 2 && !strcmp(tip_name + len - 2, "^0"))
 				len -= 2;
-			if (generation > 0)
-				sprintf(new_name, "%.*s~%d^%d", len, tip_name,
+			if (generation > 0) {
+				int w = sprintf(new_name, "%.*s", len, tip_name);
+				if (generation == 1)
+					sprintf(new_name + w, "^^%d",
+						parent_number);
+				else
+					sprintf(new_name + w, "~%d^%d",
 						generation, parent_number);
+			}
 			else
 				sprintf(new_name, "%.*s^%d", len, tip_name,
 						parent_number);
@@ -142,8 +148,12 @@ static const char *get_rev_name(const struct object *o)
 		int len = strlen(n->tip_name);
 		if (len > 2 && !strcmp(n->tip_name + len - 2, "^0"))
 			len -= 2;
-		snprintf(buffer, sizeof(buffer), "%.*s~%d", len, n->tip_name,
-				n->generation);
+		if (n->generation == 1)
+			snprintf(buffer, sizeof(buffer), "%.*s^", len,
+				 n->tip_name);
+		else
+			snprintf(buffer, sizeof(buffer), "%.*s~%d", len,
+				 n->tip_name, n->generation);
 
 		return buffer;
 	}

However, IMHO that looks even worse:

  $ git name-rev 9904fadf
  9904fadf tags/v1.7.3-rc2^^2^

-Peff

Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^

[Miles Bader]

Junio C Hamano <gitster@pobox.com> writes:
> And "HEAD^" is shorter and much easier to type, and more importantly, it
> is more often used in the wild, so the readers of the documentation needs
> to know it anyway to understand what other people do.

Seriously:  People like ^.

This doc change is not good (and seems to demonstrate a lack of
familiarity with typical git usage)....

-Miles

-- 
o The existentialist, not having a pillow, goes everywhere with the book by
  Sullivan, _I am going to spit on your graves_.