threads / discuss / 43107

Re: Suggestion: drop 'g' in git-describe suffix

Subject: Re: Suggestion: drop 'g' in git-describe suffix

## tl;dr

19 messages between Nov 2, 2006 and Nov 2, 2006.

replies: 18people: 8as markdown or json

Han-Wen Nienhuys· Nov 2, 2006, 01:23 UTC · lore

Suggestion: drop 'g' in git-describe suffix

hi,
the convention to use a 'g' in the output of git-describe, eg.
   [lilydev@haring lilypond]$ git describe --abbrev=39
   lilypond_2_9_7-g47778d2297276484c861fc7536da13feb2d5fe8

is confusing: the g is also a hex digit, and without reading the manual carefully, you'd think this is the commit g4777.

Proposal: why not use
   tag#sha1
or some other non-hex character.
-- 
  Han-Wen Nienhuys - hanwen@xs4all.nl - http://www.xs4all.nl/~hanwen
Andy Whitcroft· Nov 2, 2006, 01:47 UTC · re: Han-Wen Nienhuys · lore
Han-Wen Nienhuys wrote:
Show 17 quoted lines
> 
> hi,
> 
> the convention to use a 'g' in the output of git-describe, eg.
> 
>   [lilydev@haring lilypond]$ git describe --abbrev=39
>   lilypond_2_9_7-g47778d2297276484c861fc7536da13feb2d5fe8
> 
> 
> is confusing: the g is also a hex digit, and without reading the manual
> carefully, you'd think this is the commit g4777.
> 
> Proposal: why not use
> 
>   tag#sha1
> 
> or some other non-hex character.
g is not a hex digit, hex is 0-f ??

In current versions of git, this whole string is also a valid name for the commit ie you can do the following:

	git show lilypond_2_9_7-g47778d2297276484c861fc7536da13feb2d5fe8
-apw
Han-Wen Nienhuys· Nov 2, 2006, 09:55 UTC · re: Andy Whitcroft · lore
Andy Whitcroft escreveu:
>> or some other non-hex character.
> 
> g is not a hex digit, hex is 0-f ??
>

Yes of course; silly me. Still I think it would be clearer if it used a non-alphabet char, eg.

   tag+sha1
to separate the tag and the committish.
-- 
  Han-Wen Nienhuys - hanwen@xs4all.nl - http://www.xs4all.nl/~hanwen
Andy Whitcroft· Nov 2, 2006, 10:37 UTC · re: Han-Wen Nienhuys · lore
Han-Wen Nienhuys wrote:
Show 12 quoted lines
> Andy Whitcroft escreveu:
>>> or some other non-hex character.
>>
>> g is not a hex digit, hex is 0-f ??
>>
> 
> Yes of course; silly me. Still I think it would be clearer if it used a
> non-alphabet char, eg.
> 
>   tag+sha1
> 
> to separate the tag and the committish.

Well there is a non-alphabet character in there, a minus (-). The g prefix on the sha1 _fragment_ it to indicate that it is in fact a truncated sha1, not a complete one. If you want the complete clean sha1 this is not the way to get it?

Han-Wen Nienhuys· Nov 2, 2006, 10:53 UTC · re: Andy Whitcroft · lore
Andy Whitcroft escreveu:
Show 15 quoted lines
> Han-Wen Nienhuys wrote:
>> Andy Whitcroft escreveu:
>>>> or some other non-hex character.
>>> g is not a hex digit, hex is 0-f ??
>>>
>> Yes of course; silly me. Still I think it would be clearer if it used a
>> non-alphabet char, eg.
>>
>>   tag+sha1
>>
>> to separate the tag and the committish.
> 
> Well there is a non-alphabet character in there, a minus (-).  The g
> prefix on the sha1 _fragment_ it to indicate that it is in fact a
> truncated sha1, not a complete one.  
is this policy documented somewhere?  None of the tools understand it.

[lilydev@haring git]$ git describe v1.4.3.3-g1e1f76e [lilydev@haring git]$ git show g1e1f76e fatal: ambiguous argument 'g1e1f76e': unknown revision or path not in the working tree. Use '--' to separate paths from revisions

My suggestion is to use
   v1.4.3.3+1e1f76e
here.
> If you want the complete clean sha1
> this is not the way to get it?
-- 
  Han-Wen Nienhuys - hanwen@xs4all.nl - http://www.xs4all.nl/~hanwen
Santi Béjar· Nov 2, 2006, 11:12 UTC · re: Han-Wen Nienhuys · lore
On 11/2/06, Han-Wen Nienhuys <hanwen@xs4all.nl> wrote:
Show 10 quoted lines
> Andy Whitcroft escreveu:
> > Han-Wen Nienhuys wrote:
> >>
> >>   tag+sha1
> >>
> >> to separate the tag and the committish.
> >
> > Well there is a non-alphabet character in there, a minus (-).  The g
> > prefix on the sha1 _fragment_ it to indicate that it is in fact a
> > truncated sha1, not a complete one.
I think it is there to indicate it is a git commit sha1.
Show 10 quoted lines
>
> is this policy documented somewhere?  None of the tools understand it.
>
> [lilydev@haring git]$ git describe
> v1.4.3.3-g1e1f76e
> [lilydev@haring git]$ git show g1e1f76e
> fatal: ambiguous argument 'g1e1f76e': unknown revision or path not in
> the working tree.
> Use '--' to separate paths from revisions
>

Use the complete output of describe: $ git show v1.4.3.3-g1e1f76e

or the abbrev sha1: $ git show 1e1f76e

> My suggestion is to use
>
>    v1.4.3.3+1e1f76e
My suggestion is to use:
v1.4.3.3-git1e1f76e
to make clear that it is a git revision version.

One problem I see with this scheme (either 'g', 'git' of '+') is that it does not provide an increasing version number, even for fast-forwarding commits. Then it is not useful as a package version number (deb or rpm). I've already seen deb packages with version+git20061010. One possibility could be to add the number of commits between the tag and the commit as:

v1.4.3.3-git12g1e1f76e
to provide a weak ordering for fast-forwarding commits. What do you thing?
Andy Whitcroft· Nov 2, 2006, 11:21 UTC · re: Santi Béjar · lore
Santi Béjar wrote:
Show 51 quoted lines
> On 11/2/06, Han-Wen Nienhuys <hanwen@xs4all.nl> wrote:
>> Andy Whitcroft escreveu:
>> > Han-Wen Nienhuys wrote:
>> >>
>> >>   tag+sha1
>> >>
>> >> to separate the tag and the committish.
>> >
>> > Well there is a non-alphabet character in there, a minus (-).  The g
>> > prefix on the sha1 _fragment_ it to indicate that it is in fact a
>> > truncated sha1, not a complete one.
> 
> I think it is there to indicate it is a git commit sha1.
> 
>>
>> is this policy documented somewhere?  None of the tools understand it.
>>
>> [lilydev@haring git]$ git describe
>> v1.4.3.3-g1e1f76e
>> [lilydev@haring git]$ git show g1e1f76e
>> fatal: ambiguous argument 'g1e1f76e': unknown revision or path not in
>> the working tree.
>> Use '--' to separate paths from revisions
>>
> 
> Use the complete output of describe:
> $ git show v1.4.3.3-g1e1f76e
> 
> or the abbrev sha1:
> $ git show 1e1f76e
> 
>> My suggestion is to use
>>
>>    v1.4.3.3+1e1f76e
> 
> My suggestion is to use:
> 
> v1.4.3.3-git1e1f76e
> 
> to make clear that it is a git revision version.
> 
> One problem I see with this scheme (either 'g', 'git' of '+') is that
> it does not provide an increasing version number, even for
> fast-forwarding commits. Then it is not useful as a package version
> number (deb or rpm). I've already seen deb packages with
> version+git20061010. One possibility could be to add the number of
> commits between the tag and the commit as:
> 
> v1.4.3.3-git12g1e1f76e
> 
> to provide a weak ordering for fast-forwarding commits. What do you thing?
I think you'll restart the 1.2.3.4 versioning is better 'debate' again!

Surly if things are being pushed into a .deb or .rpm we should be using a real release version. We should be tagging that. If the project is not providing release number, there is nothing stopping you from tagging them yourself in your copy of the repository and using your tag. you could use like 'unofficial-N' where N increments in the way you want.

Santi Béjar· Nov 2, 2006, 12:39 UTC · re: Andy Whitcroft · lore
On 11/2/06, Andy Whitcroft <apw@shadowen.org> wrote:
Show 13 quoted lines
> Santi Béjar wrote:
> > One problem I see with this scheme (either 'g', 'git' of '+') is that
> > it does not provide an increasing version number, even for
> > fast-forwarding commits. Then it is not useful as a package version
> > number (deb or rpm). I've already seen deb packages with
> > version+git20061010. One possibility could be to add the number of
> > commits between the tag and the commit as:
> >
> > v1.4.3.3-git12g1e1f76e
> >
> > to provide a weak ordering for fast-forwarding commits. What do you thing?
>
> I think you'll restart the 1.2.3.4 versioning is better 'debate' again!
Sorry, I don't undestand this.
Show 5 quoted lines
> Surly if things are being pushed into a .deb or .rpm we should be using
> a real release version.  We should be tagging that.  If the project is
> not providing release number, there is nothing stopping you from tagging
> them yourself in your copy of the repository and using your tag.  you
> could use like 'unofficial-N' where N increments in the way you want.

And where do you store this tag? It is an upstream commit and you just refer to this. With the unofficial-N there is no way to know which upstream commit you are refering without having access to the git repository of the packager .

Andy Whitcroft· Nov 2, 2006, 13:52 UTC · re: Santi Béjar · lore
Santi Béjar wrote:
Show 17 quoted lines
> On 11/2/06, Andy Whitcroft <apw@shadowen.org> wrote:
>> Santi Béjar wrote:
>> > One problem I see with this scheme (either 'g', 'git' of '+') is that
>> > it does not provide an increasing version number, even for
>> > fast-forwarding commits. Then it is not useful as a package version
>> > number (deb or rpm). I've already seen deb packages with
>> > version+git20061010. One possibility could be to add the number of
>> > commits between the tag and the commit as:
>> >
>> > v1.4.3.3-git12g1e1f76e
>> >
>> > to provide a weak ordering for fast-forwarding commits. What do you
>> thing?
>>
>> I think you'll restart the 1.2.3.4 versioning is better 'debate' again!
> 
> Sorry, I don't undestand this.

There was a long running debate between sha1's and version 'numbers' 1.2.3.4 for each revision.

Show 11 quoted lines
> 
>> Surly if things are being pushed into a .deb or .rpm we should be using
>> a real release version.  We should be tagging that.  If the project is
>> not providing release number, there is nothing stopping you from tagging
>> them yourself in your copy of the repository and using your tag.  you
>> could use like 'unofficial-N' where N increments in the way you want.
> 
> And where do you store this tag? It is an upstream commit and you just
> refer to this. With the unofficial-N there is no way to know which
> upstream commit you are refering without having access to the git
> repository of the packager  .

Yes that is completly true, but its normally the packer who is doing the bug fixing of the .deb when its broken. The key problem is you need your numbering to be stable. The only guarenteed stable thing is the sha1, tags can change. IMHO you should be including the full sha1 in the --version output and the package descript, whatever versioning you are using on the .deb itself.

That said I guess it would be pretty easy to come up with something to count the number of commits since the last valid tag, something like that below. Might not be pretty, nor so easy to turn back into a commit of course.

-apw
#!/bin/sh
let n=0
git log --pretty=one "$@" | \
        awk '{print $1}' | \
        git name-rev --tags --stdin | \
{
        while read sha1 name
        do
                if [ "$name" != "" ]; then
                        echo "$sha1 $name $n"
                        exit 0
                fi
                let "n=n+1"
        done
        echo "- unknown 0"
        exit 1
Han-Wen Nienhuys· Nov 2, 2006, 11:23 UTC · re: Santi Béjar · lore
Santi Béjar escreveu:
Show 10 quoted lines
> One problem I see with this scheme (either 'g', 'git' of '+') is that
> it does not provide an increasing version number, even for
> fast-forwarding commits. Then it is not useful as a package version
> number (deb or rpm). I've already seen deb packages with
> version+git20061010. One possibility could be to add the number of
> commits between the tag and the commit as:
> 
> v1.4.3.3-git12g1e1f76e
> 
> to provide a weak ordering for fast-forwarding commits. What do you thing?
Is that number well defined if you merge branches in between?
I'd prefer
   v1.4.3.3+git-12-1e1f76e
or similar. Pasting together words without separator is bad for readability.
Santi Béjar· Nov 2, 2006, 12:44 UTC · re: Han-Wen Nienhuys · lore
On 11/2/06, Han-Wen Nienhuys <hanwen@xs4all.nl> wrote:
Show 13 quoted lines
> Santi Béjar escreveu:
> > One problem I see with this scheme (either 'g', 'git' of '+') is that
> > it does not provide an increasing version number, even for
> > fast-forwarding commits. Then it is not useful as a package version
> > number (deb or rpm). I've already seen deb packages with
> > version+git20061010. One possibility could be to add the number of
> > commits between the tag and the commit as:
> >
> > v1.4.3.3-git12g1e1f76e
> >
> > to provide a weak ordering for fast-forwarding commits. What do you thing?
>
> Is that number well defined if you merge branches in between?
Yes.
$ git-rev-list 1e1f76e ^v1.4.3.3 | wc -l
Show 9 quoted lines
>
> I'd prefer
>
>    v1.4.3.3+git-12-1e1f76e
>
> or similar. Pasting together words without separator is bad for readability.
>
> --
>   Han-Wen Nienhuys - hanwen@xs4all.nl - http://www.xs4all.nl/~hanwen
Jakub Narebski· Nov 2, 2006, 14:07 UTC · re: Han-Wen Nienhuys · lore
Han-Wen Nienhuys wrote:
Show 19 quoted lines
> Santi Béjar escreveu:
>> One problem I see with this scheme (either 'g', 'git' of '+') is that
>> it does not provide an increasing version number, even for
>> fast-forwarding commits. Then it is not useful as a package version
>> number (deb or rpm). I've already seen deb packages with
>> version+git20061010. One possibility could be to add the number of
>> commits between the tag and the commit as:
>> 
>> v1.4.3.3-git12g1e1f76e
>> 
>> to provide a weak ordering for fast-forwarding commits. What do you thing?
> 
> Is that number well defined if you merge branches in between?
> 
> I'd prefer
> 
>    v1.4.3.3+git-12-1e1f76e
> 
> or similar. Pasting together words without separator is bad for readability.
Or even IMVHO better:
    v1.4.3.3+12--1e1f76e

or something like that. v1.4.3.3+12 part meaning that v1.4.3.3 is 12 ancestor in direct shortest direct line, or that v1.4.3.3+12 is 12 generations away from v1.4.3.3.

Of course that is _costly_ to confitm that, and v1.4.3.3+12 might mean more than one revision in presence of branching points, especially that there is no equivalent of "first parent" to distinguish like in case of v1.4.3.3~12

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git
Nicolas Vilz 'niv'· Nov 2, 2006, 14:48 UTC · re: Santi Béjar · lore
Santi Béjar wrote:
Show 27 quoted lines
> On 11/2/06, Han-Wen Nienhuys <hanwen@xs4all.nl> wrote:
>> Andy Whitcroft escreveu:
>> > Han-Wen Nienhuys wrote:
>> >>
>> >>   tag+sha1
>> >>
>> >> to separate the tag and the committish.
>> >
>> > Well there is a non-alphabet character in there, a minus (-).  The g
>> > prefix on the sha1 _fragment_ it to indicate that it is in fact a
>> > truncated sha1, not a complete one.
> 
> I think it is there to indicate it is a git commit sha1.
> 
>>
>> is this policy documented somewhere?  None of the tools understand it.
>>
>> [lilydev@haring git]$ git describe
>> v1.4.3.3-g1e1f76e
>> [lilydev@haring git]$ git show g1e1f76e
>> fatal: ambiguous argument 'g1e1f76e': unknown revision or path not in
>> the working tree.
>> Use '--' to separate paths from revisions
>>
> 
> Use the complete output of describe:
> $ git show v1.4.3.3-g1e1f76e
this one doesn't work for me in my repository.

$ git-describe release_1_22_v0.7-g85eb121

$ git show release_1_22_v0.7-g85eb121 fatal: ambiguous argument 'release_1_22_v0.7-g85eb121': unknown revision or path not in the working tree. Use '--' to separate paths from revisions

> or the abbrev sha1:
> $ git show 1e1f76e
this one works with my repository
$ git show 85eb121
i use git version 1.4.2.rc2.g2686c
(that was next branch of git one or two days ago or so..)
it would be great to let the full output of git describe work as well.
Sincerly
Johannes Schindelin· Nov 2, 2006, 15:01 UTC · re: Nicolas Vilz 'niv' · lore
Hi,
On Thu, 2 Nov 2006, Nicolas Vilz 'niv' wrote:
> > Use the complete output of describe:
> > $ git show v1.4.3.3-g1e1f76e
> 
> this one doesn't work for me in my repository.

You need at least v1.4.3-rc1^0~69 (v1.4.2.1-g7dd45e1) for this. You indicated in your email that your version is older.

Ciao, Dscho

Nicolas Vilz 'niv'· Nov 2, 2006, 19:12 UTC · re: Johannes Schindelin · lore
Johannes Schindelin wrote:
Show 10 quoted lines
> Hi,
> 
> On Thu, 2 Nov 2006, Nicolas Vilz 'niv' wrote:
> 
>>> Use the complete output of describe:
>>> $ git show v1.4.3.3-g1e1f76e
>> this one doesn't work for me in my repository.
> 
> You need at least v1.4.3-rc1^0~69 (v1.4.2.1-g7dd45e1) for this. You 
> indicated in your email that your version is older.

strange, from time to time i have to delete the whole git repository, not to get stuck on old revisions. Now with a fresh repository i get a current revision and with this version, it works.

Thx for help
Andy Whitcroft· Nov 2, 2006, 11:12 UTC · re: Han-Wen Nienhuys · lore
Han-Wen Nienhuys wrote:
Show 31 quoted lines
> Andy Whitcroft escreveu:
>> Han-Wen Nienhuys wrote:
>>> Andy Whitcroft escreveu:
>>>>> or some other non-hex character.
>>>> g is not a hex digit, hex is 0-f ??
>>>>
>>> Yes of course; silly me. Still I think it would be clearer if it used a
>>> non-alphabet char, eg.
>>>
>>>   tag+sha1
>>>
>>> to separate the tag and the committish.
>>
>> Well there is a non-alphabet character in there, a minus (-).  The g
>> prefix on the sha1 _fragment_ it to indicate that it is in fact a
>> truncated sha1, not a complete one.  
> 
> is this policy documented somewhere?  None of the tools understand it.
> 
> [lilydev@haring git]$ git describe
> v1.4.3.3-g1e1f76e
> [lilydev@haring git]$ git show g1e1f76e
> fatal: ambiguous argument 'g1e1f76e': unknown revision or path not in
> the working tree.
> Use '--' to separate paths from revisions
> 
> My suggestion is to use
> 
>   v1.4.3.3+1e1f76e
> 
> here.
The 'whole' thing is valid as an object reference:
apw@pinky$ git describe
v1.4.3.3-g8cf249b
apw@pinky$ git show v1.4.3.3-g8cf249b
commit 8cf249b755c257ea19100b888ac612e601cdf96b
Merge: 15c3ffb... fa438a2...
[...]
Petr Baudis· Nov 2, 2006, 11:03 UTC · re: Andy Whitcroft · lore

Dear diary, on Thu, Nov 02, 2006 at 11:37:31AM CET, I got a letter where Andy Whitcroft <apw@shadowen.org> said that...

> The g prefix on the sha1 _fragment_ it to indicate that it is in fact
> a truncated sha1, not a complete one.
I think it's rather to indicate that it is a sha1 at all.
-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1
Carl Worth· Nov 2, 2006, 13:45 UTC · re: Petr Baudis · lore
On Thu, 2 Nov 2006 12:03:31 +0100, Petr Baudis wrote:
Show 7 quoted lines
>
> Dear diary, on Thu, Nov 02, 2006 at 11:37:31AM CET, I got a letter
> where Andy Whitcroft <apw@shadowen.org> said that...
> > The g prefix on the sha1 _fragment_ it to indicate that it is in fact
> > a truncated sha1, not a complete one.
>
> I think it's rather to indicate that it is a sha1 at all.

Frankly, I've never understood the 'g' prefix at all. I don't use git-describe much, but some people have sent me things with this 'g' on the front and every time I've received that I was annoyed to find the commit identifier they sent didn't work until I manually removed it.

It's definitely never provided any useful semantic information to me.
-Carl

← back to recent threads