{"thread":{"id":"21428","subject":"[PATCH] More precise description of 'git describe --abbrev'","startedAt":"2009-10-29T21:38:29Z","lastAt":"2009-11-04T22:04:56Z","messageCount":8,"participants":["Gisle Aas","Junio C Hamano","Andreas Schwab"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"126335","messageId":"b48ea8a00910291438r8b66a0fq9e821393ecfff0bf@mail.gmail.com","threadId":"21428","inReplyTo":null,"subject":"[PATCH] More precise description of 'git describe --abbrev'","fromName":"Gisle Aas","fromEmail":"gisle@aas.no","sentAt":"2009-10-29T21:38:29Z","receivedAt":"2009-10-29T21:38:29Z","isPatch":true,"sender":{"key":"gisle@aas.no","avatar":"https://avatars.githubusercontent.com/u/4326?v=4"},"body":"Also make the examples show what 'git describe' actually outputs\ncurrently.  I guess the default --abbrev value has been changed from 4\nto 7 at some point.\n\nSigned-off-by: Gisle Aas <gisle@aas.no>\n---\n Documentation/git-describe.txt |   12 +++++++-----\n 1 files changed, 7 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt\nindex b231dbb..743eb95 100644\n--- a/Documentation/git-describe.txt\n+++ b/Documentation/git-describe.txt\n@@ -44,7 +44,9 @@ OPTIONS\n\n --abbrev=<n>::\n \tInstead of using the default 7 hexadecimal digits as the\n-\tabbreviated object name, use <n> digits.\n+\tabbreviated object name, use <n> digits or as many digits\n+\tare needed to form a unique object name.  An <n> of 0\n+\twill suppress long format, only showing the closest tag.\n\n --candidates=<n>::\n \tInstead of considering only the 10 most recent tags as\n@@ -68,8 +70,8 @@ OPTIONS\n \tThis is useful when you want to see parts of the commit object name\n \tin \"describe\" output, even when the commit in question happens to be\n \ta tagged version.  Instead of just emitting the tag name, it will\n-\tdescribe such a commit as v1.2-0-deadbeef (0th commit since tag v1.2\n-\tthat points at object deadbeef....).\n+\tdescribe such a commit as v1.2-0-gdeadbee (0th commit since tag v1.2\n+\tthat points at object deadbee....).\n\n --match <pattern>::\n \tOnly consider tags matching the given pattern (can be used to avoid\n@@ -106,10 +108,10 @@ With --all, the command can use branch heads as\nreferences, so\n the output shows the reference path as well:\n\n \t[torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2\n-\ttags/v1.0.0-21-g975b\n+\ttags/v1.0.0-21-g975b3\n\n \t[torvalds@g5 git]$ git describe --all HEAD^\n-\theads/lt/describe-7-g975b\n+\theads/lt/describe-7-g975b31d\n\n With --abbrev set to 0, the command can be used to find the\n closest tagname without any suffix:\n-- \n1.6.2.95.g934f7\n"},{"id":"126344","messageId":"7vws2d4y3d.fsf@alter.siamese.dyndns.org","threadId":"21428","inReplyTo":"b48ea8a00910291438r8b66a0fq9e821393ecfff0bf@mail.gmail.com","subject":"Re: [PATCH] More precise description of 'git describe --abbrev'","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-10-29T22:47:02Z","receivedAt":"2009-10-29T22:47:02Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Gisle Aas <gisle@aas.no> writes:\n\n> Also make the examples show what 'git describe' actually outputs\n> currently.  I guess the default --abbrev value has been changed from 4\n> to 7 at some point.\n\nSome are good changes, but I do not think the example with --abbrev=4 is.\n\n$ git describe 975bf9cf5ad5d440f98f464ae8124609a4835ce1\nv1.3.2-216-g975bf9c\n$ git describe 975b31dc6e12fba8f7b067ddbe32230995e05400\nv1.0.0-21-g975b31d\n\nNext time somebody adds a new object whose name happens to begin with\n975b3 you would need to update the example output.\n\n> Signed-off-by: Gisle Aas <gisle@aas.no>\n> ---\n>  Documentation/git-describe.txt |   12 +++++++-----\n>  1 files changed, 7 insertions(+), 5 deletions(-)\n>\n> diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt\n> index b231dbb..743eb95 100644\n> --- a/Documentation/git-describe.txt\n> +++ b/Documentation/git-describe.txt\n> @@ -44,7 +44,9 @@ OPTIONS\n>\n>  --abbrev=<n>::\n>  \tInstead of using the default 7 hexadecimal digits as the\n> -\tabbreviated object name, use <n> digits.\n> +\tabbreviated object name, use <n> digits or as many digits\n> +\tare needed to form a unique object name.  An <n> of 0\n> +\twill suppress long format, only showing the closest tag.\n>\n>  --candidates=<n>::\n>  \tInstead of considering only the 10 most recent tags as\n> @@ -68,8 +70,8 @@ OPTIONS\n>  \tThis is useful when you want to see parts of the commit object name\n>  \tin \"describe\" output, even when the commit in question happens to be\n>  \ta tagged version.  Instead of just emitting the tag name, it will\n> -\tdescribe such a commit as v1.2-0-deadbeef (0th commit since tag v1.2\n> -\tthat points at object deadbeef....).\n> +\tdescribe such a commit as v1.2-0-gdeadbee (0th commit since tag v1.2\n> +\tthat points at object deadbee....).\n>\n>  --match <pattern>::\n>  \tOnly consider tags matching the given pattern (can be used to avoid\n> @@ -106,10 +108,10 @@ With --all, the command can use branch heads as\n> references, so\n>  the output shows the reference path as well:\n>\n>  \t[torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2\n> -\ttags/v1.0.0-21-g975b\n> +\ttags/v1.0.0-21-g975b3\n>\n>  \t[torvalds@g5 git]$ git describe --all HEAD^\n> -\theads/lt/describe-7-g975b\n> +\theads/lt/describe-7-g975b31d\n>\n>  With --abbrev set to 0, the command can be used to find the\n>  closest tagname without any suffix:\n> -- \n> 1.6.2.95.g934f7\n"},{"id":"126356","messageId":"b48ea8a00910300101i38f2e4a8q2c2e014d2df1a150@mail.gmail.com","threadId":"21428","inReplyTo":"7vws2d4y3d.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] More precise description of 'git describe --abbrev'","fromName":"Gisle Aas","fromEmail":"gisle@aas.no","sentAt":"2009-10-30T08:01:38Z","receivedAt":"2009-10-30T08:01:38Z","isPatch":true,"sender":{"key":"gisle@aas.no","avatar":"https://avatars.githubusercontent.com/u/4326?v=4"},"body":"On Thu, Oct 29, 2009 at 23:47, Junio C Hamano <gitster@pobox.com> wrote:\n> Gisle Aas <gisle@aas.no> writes:\n>\n>> Also make the examples show what 'git describe' actually outputs\n>> currently.  I guess the default --abbrev value has been changed from 4\n>> to 7 at some point.\n>\n> Some are good changes, but I do not think the example with --abbrev=4 is.\n>\n> $ git describe 975bf9cf5ad5d440f98f464ae8124609a4835ce1\n> v1.3.2-216-g975bf9c\n> $ git describe 975b31dc6e12fba8f7b067ddbe32230995e05400\n> v1.0.0-21-g975b31d\n>\n> Next time somebody adds a new object whose name happens to begin with\n> 975b3 you would need to update the example output.\n\nYeah, I know, but I don't think that's a big deal.  So do you want an\nupdated patch for that?  We could either simply remove this example or\nmake it use --abbrev=10 or something like that.\n\n--Gisle\n\n\n>\n>> Signed-off-by: Gisle Aas <gisle@aas.no>\n>> ---\n>>  Documentation/git-describe.txt |   12 +++++++-----\n>>  1 files changed, 7 insertions(+), 5 deletions(-)\n>>\n>> diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt\n>> index b231dbb..743eb95 100644\n>> --- a/Documentation/git-describe.txt\n>> +++ b/Documentation/git-describe.txt\n>> @@ -44,7 +44,9 @@ OPTIONS\n>>\n>>  --abbrev=<n>::\n>>       Instead of using the default 7 hexadecimal digits as the\n>> -     abbreviated object name, use <n> digits.\n>> +     abbreviated object name, use <n> digits or as many digits\n>> +     are needed to form a unique object name.  An <n> of 0\n>> +     will suppress long format, only showing the closest tag.\n>>\n>>  --candidates=<n>::\n>>       Instead of considering only the 10 most recent tags as\n>> @@ -68,8 +70,8 @@ OPTIONS\n>>       This is useful when you want to see parts of the commit object name\n>>       in \"describe\" output, even when the commit in question happens to be\n>>       a tagged version.  Instead of just emitting the tag name, it will\n>> -     describe such a commit as v1.2-0-deadbeef (0th commit since tag v1.2\n>> -     that points at object deadbeef....).\n>> +     describe such a commit as v1.2-0-gdeadbee (0th commit since tag v1.2\n>> +     that points at object deadbee....).\n>>\n>>  --match <pattern>::\n>>       Only consider tags matching the given pattern (can be used to avoid\n>> @@ -106,10 +108,10 @@ With --all, the command can use branch heads as\n>> references, so\n>>  the output shows the reference path as well:\n>>\n>>       [torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2\n>> -     tags/v1.0.0-21-g975b\n>> +     tags/v1.0.0-21-g975b3\n>>\n>>       [torvalds@g5 git]$ git describe --all HEAD^\n>> -     heads/lt/describe-7-g975b\n>> +     heads/lt/describe-7-g975b31d\n>>\n>>  With --abbrev set to 0, the command can be used to find the\n>>  closest tagname without any suffix:\n>> --\n>> 1.6.2.95.g934f7\n>\n"},{"id":"126408","messageId":"7viqdwlnam.fsf@alter.siamese.dyndns.org","threadId":"21428","inReplyTo":"b48ea8a00910300101i38f2e4a8q2c2e014d2df1a150@mail.gmail.com","subject":"Re: [PATCH] More precise description of 'git describe --abbrev'","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-10-30T19:00:33Z","receivedAt":"2009-10-30T19:00:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Gisle Aas <gisle@aas.no> writes:\n\n> On Thu, Oct 29, 2009 at 23:47, Junio C Hamano <gitster@pobox.com> wrote:\n>> Gisle Aas <gisle@aas.no> writes:\n>>\n>>> Also make the examples show what 'git describe' actually outputs\n>>> currently.  I guess the default --abbrev value has been changed from 4\n>>> to 7 at some point.\n>>\n>> Some are good changes, but I do not think the example with --abbrev=4 is.\n>>\n>> $ git describe 975bf9cf5ad5d440f98f464ae8124609a4835ce1\n>> v1.3.2-216-g975bf9c\n>> $ git describe 975b31dc6e12fba8f7b067ddbe32230995e05400\n>> v1.0.0-21-g975b31d\n>>\n>> Next time somebody adds a new object whose name happens to begin with\n>> 975b3 you would need to update the example output.\n>\n> Yeah, I know, but I don't think that's a big deal.  So do you want an\n> updated patch for that?  We could either simply remove this example or\n> make it use --abbrev=10 or something like that.\n\nNot touching the example would be the simplest.\n\nAdding an explanation like this so that nobody will be tempted to \"fix\"\nthe example would be the best, I think.\n\n     [torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2\n     tags/v1.0.0-21-g975b\n\n     Note that the suffix you get if you type this command today may be\n     longer than what Linus saw above when he ran this command, as your\n     git repository may have new commits whose object names begin with\n     975b that did not exist back then, and \"-g975b\" suffix alone is not\n     sufficient to disambiguate these commits.\n"},{"id":"126412","messageId":"b48ea8a00910301227l4714eca9l767afd036938f494@mail.gmail.com","threadId":"21428","inReplyTo":"7viqdwlnam.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] More precise description of 'git describe --abbrev'","fromName":"Gisle Aas","fromEmail":"gisle@aas.no","sentAt":"2009-10-30T19:27:02Z","receivedAt":"2009-10-30T19:27:02Z","isPatch":true,"sender":{"key":"gisle@aas.no","avatar":"https://avatars.githubusercontent.com/u/4326?v=4"},"body":"On Fri, Oct 30, 2009 at 20:00, Junio C Hamano <gitster@pobox.com> wrote:\n> Adding an explanation like this so that nobody will be tempted to \"fix\"\n> the example would be the best, I think.\n\nUpdated patch attached.\n\n>\n>     [torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2\n>     tags/v1.0.0-21-g975b\n>\n>     Note that the suffix you get if you type this command today may be\n>     longer than what Linus saw above when he ran this command, as your\n>     git repository may have new commits whose object names begin with\n>     975b that did not exist back then, and \"-g975b\" suffix alone is not\n>     sufficient to disambiguate these commits.\n>\n>\n\n\nFrom 5f6b405fa24861ae89207d334ea2e11f383a7e4e Mon Sep 17 00:00:00 2001\nFrom: Gisle Aas <gisle@aas.no>\nDate: Thu, 29 Oct 2009 22:29:35 +0100\nSubject: [PATCH] More precise description of 'git describe --abbrev'\n\nAlso adds a note about why the output in the examples might give\ndifferent output today.\n\nSigned-off-by: Gisle Aas <gisle@aas.no>\n---\n Documentation/git-describe.txt |   17 +++++++++++++----\n 1 files changed, 13 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt\nindex b231dbb..f8d91b1 100644\n--- a/Documentation/git-describe.txt\n+++ b/Documentation/git-describe.txt\n@@ -44,7 +44,9 @@ OPTIONS\n \n --abbrev=<n>::\n \tInstead of using the default 7 hexadecimal digits as the\n-\tabbreviated object name, use <n> digits.\n+\tabbreviated object name, use <n> digits or as many digits\n+\tare needed to form a unique object name.  An <n> of 0\n+\twill suppress long format, only showing the closest tag.\n \n --candidates=<n>::\n \tInstead of considering only the 10 most recent tags as\n@@ -68,8 +70,8 @@ OPTIONS\n \tThis is useful when you want to see parts of the commit object name\n \tin \"describe\" output, even when the commit in question happens to be\n \ta tagged version.  Instead of just emitting the tag name, it will\n-\tdescribe such a commit as v1.2-0-deadbeef (0th commit since tag v1.2\n-\tthat points at object deadbeef....).\n+\tdescribe such a commit as v1.2-0-gdeadbee (0th commit since tag v1.2\n+\tthat points at object deadbee....).\n \n --match <pattern>::\n \tOnly consider tags matching the given pattern (can be used to avoid\n@@ -108,7 +110,7 @@ the output shows the reference path as well:\n \t[torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2\n \ttags/v1.0.0-21-g975b\n \n-\t[torvalds@g5 git]$ git describe --all HEAD^\n+\t[torvalds@g5 git]$ git describe --all --abbrev=4 HEAD^\n \theads/lt/describe-7-g975b\n \n With --abbrev set to 0, the command can be used to find the\n@@ -117,6 +119,13 @@ closest tagname without any suffix:\n \t[torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2\n \ttags/v1.0.0\n \n+Note that the suffix you get if you type these commands today may be\n+longer than what Linus saw above when he ran this command, as your\n+git repository may have new commits whose object names begin with\n+975b that did not exist back then, and \"-g975b\" suffix alone is not\n+sufficient to disambiguate these commits.\n+\n+\n SEARCH STRATEGY\n ---------------\n \n-- \n1.6.2.95.g934f7\n\n"},{"id":"126427","messageId":"m2my38fxeo.fsf@igel.home","threadId":"21428","inReplyTo":"b48ea8a00910291438r8b66a0fq9e821393ecfff0bf@mail.gmail.com","subject":"Re: [PATCH] More precise description of 'git describe --abbrev'","fromName":"Andreas Schwab","fromEmail":"schwab@linux-m68k.org","sentAt":"2009-10-30T20:18:39Z","receivedAt":"2009-10-30T20:18:39Z","isPatch":true,"sender":{"key":"schwab@linux-m68k.org","avatar":"https://avatars.githubusercontent.com/u/2175493?v=4"},"body":"Gisle Aas <gisle@aas.no> writes:\n\n> diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt\n> index b231dbb..743eb95 100644\n> --- a/Documentation/git-describe.txt\n> +++ b/Documentation/git-describe.txt\n> @@ -44,7 +44,9 @@ OPTIONS\n>\n>  --abbrev=<n>::\n>  \tInstead of using the default 7 hexadecimal digits as the\n> -\tabbreviated object name, use <n> digits.\n> +\tabbreviated object name, use <n> digits or as many digits\n> +\tare needed to form a unique object name.  An <n> of 0\n\n\"as many digits as needed\"?\n\nAndreas.\n\n-- \nAndreas Schwab, schwab@linux-m68k.org\nGPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5\n\"And now for something completely different.\"\n"},{"id":"126439","messageId":"7vmy38im51.fsf@alter.siamese.dyndns.org","threadId":"21428","inReplyTo":"m2my38fxeo.fsf@igel.home","subject":"Re: [PATCH] More precise description of 'git describe --abbrev'","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-10-30T21:53:46Z","receivedAt":"2009-10-30T21:53:46Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Andreas Schwab <schwab@linux-m68k.org> writes:\n\n> Gisle Aas <gisle@aas.no> writes:\n>\n>> diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt\n>> index b231dbb..743eb95 100644\n>> --- a/Documentation/git-describe.txt\n>> +++ b/Documentation/git-describe.txt\n>> @@ -44,7 +44,9 @@ OPTIONS\n>>\n>>  --abbrev=<n>::\n>>  \tInstead of using the default 7 hexadecimal digits as the\n>> -\tabbreviated object name, use <n> digits.\n>> +\tabbreviated object name, use <n> digits or as many digits\n>> +\tare needed to form a unique object name.  An <n> of 0\n>\n> \"as many digits as needed\"?\n\nThanks; queued with this fix-up.\n"},{"id":"126838","messageId":"b48ea8a00911041404p2f176763kcc022249deab23a9@mail.gmail.com","threadId":"21428","inReplyTo":"7vmy38im51.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] More precise description of 'git describe --abbrev'","fromName":"Gisle Aas","fromEmail":"gisle@aas.no","sentAt":"2009-11-04T22:04:56Z","receivedAt":"2009-11-04T22:04:56Z","isPatch":true,"sender":{"key":"gisle@aas.no","avatar":"https://avatars.githubusercontent.com/u/4326?v=4"},"body":"Unfortunately there was still a grammar typo in that patch:\n\n--- a/Documentation/git-describe.txt\n+++ b/Documentation/git-describe.txt\n@@ -120,7 +120,7 @@ closest tagname without any suffix:\n        tags/v1.0.0\n\n Note that the suffix you get if you type these commands today may be\n-longer than what Linus saw above when he ran this command, as your\n+longer than what Linus saw above when he ran these commands, as your\n git repository may have new commits whose object names begin with\n 975b that did not exist back then, and \"-g975b\" suffix alone may not\n be sufficient to disambiguate these commits.\n\n\nFrom 8910eed48f0c4c53af1b74d0016ef772bdce5689 Mon Sep 17 00:00:00 2001\nFrom: Gisle Aas <gisle@aas.no>\nDate: Wed, 4 Nov 2009 22:57:46 +0100\nSubject: [PATCH] Fix documentation grammar typo\n\nIntroduced in commit 492cf3f72f9d8...\n\nSigned-off-by: Gisle Aas <gisle@aas.no>\n---\n Documentation/git-describe.txt |    2 +-\n 1 files changed, 1 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt\nindex e9dbca7..2f97916 100644\n--- a/Documentation/git-describe.txt\n+++ b/Documentation/git-describe.txt\n@@ -120,7 +120,7 @@ closest tagname without any suffix:\n \ttags/v1.0.0\n \n Note that the suffix you get if you type these commands today may be\n-longer than what Linus saw above when he ran this command, as your\n+longer than what Linus saw above when he ran these commands, as your\n git repository may have new commits whose object names begin with\n 975b that did not exist back then, and \"-g975b\" suffix alone may not\n be sufficient to disambiguate these commits.\n-- \n1.6.2.95.g934f7\n\n"}]}