{"thread":{"id":"46061","subject":"[PATCH] doc: Improve description for rev-parse --short","startedAt":"2017-05-28T14:33:38Z","lastAt":"2017-05-31T21:39:44Z","messageCount":5,"participants":["Andreas Heiduk","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"320890","messageId":"20170528143322.8580-1-asheiduk@gmail.com","threadId":"46061","inReplyTo":null,"subject":"[PATCH] doc: Improve description for rev-parse --short","fromName":"Andreas Heiduk","fromEmail":"asheiduk@gmail.com","sentAt":"2017-05-28T14:33:22Z","receivedAt":"2017-05-28T14:33:38Z","isPatch":true,"sender":{"key":"asheiduk@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9371344?v=4"},"body":"First: `git rev-parse --short` without a number does use a fixed default but\n`core.abbrev` which in turn uses `find_unique_abbrev` internally.\n\nSecond: `--short` implies `--verify` since the beginning (d50125085a), so\nit cannot be used for bulk-shortening ids unfortunately.\n\nSigned-off-by: Andreas Heiduk <asheiduk@gmail.com>\n---\n Documentation/config.txt        | 1 +\n Documentation/git-rev-parse.txt | 4 +++-\n 2 files changed, 4 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex e0b9fd0bc..158cb588b 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -862,6 +862,7 @@ core.abbrev::\n \tcomputed based on the approximate number of packed objects\n \tin your repository, which hopefully is enough for\n \tabbreviated object names to stay unique for some time.\n+\tThe minimum length is 4.\n \n add.ignoreErrors::\n add.ignore-errors (deprecated)::\ndiff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt\nindex c40c47044..7a7421c8e 100644\n--- a/Documentation/git-rev-parse.txt\n+++ b/Documentation/git-rev-parse.txt\n@@ -140,7 +140,9 @@ can be used.\n --short=number::\n \tInstead of outputting the full SHA-1 values of object names try to\n \tabbreviate them to a shorter unique name. When no length is specified\n-\t7 is used. The minimum length is 4.\n+\tthe effective value of the configuration variable `core.abbrev` (see\n+\tlinkgit:git-config[1]) is used.  The minimum length is 4.  The length\n+\tmay be exceeded to ensure unique object names.\tImplies `--verify`.\n \n --symbolic::\n \tUsually the object names are output in SHA-1 form (with\n-- \n2.13.0\n\n"},{"id":"320985","messageId":"xmqq1sr7dly4.fsf@gitster.mtv.corp.google.com","threadId":"46061","inReplyTo":"20170528143322.8580-1-asheiduk@gmail.com","subject":"Re: [PATCH] doc: Improve description for rev-parse --short","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-05-30T04:10:11Z","receivedAt":"2017-05-30T04:10:26Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Andreas Heiduk <asheiduk@gmail.com> writes:\n\n> First: `git rev-parse --short` without a number does use a fixed default but\n> `core.abbrev` which in turn uses `find_unique_abbrev` internally.\n\n... hence the value gives mere minumum.  I like your updated text that\nclarifies this point.\n\n> Second: `--short` implies `--verify` since the beginning (d50125085a), so\n> it cannot be used for bulk-shortening ids unfortunately.\n\nThe fact you have to say \"Nth:\" hints that this is better done as\ntwo patch series.  Then you can avoid saying a vague \"Improve\" on\nthe subject, that leaves the \"git shortlog\" readers wondering what\nexactly you improved.\n\n> Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>\n> ---\n>  Documentation/config.txt        | 1 +\n>  Documentation/git-rev-parse.txt | 4 +++-\n>  2 files changed, 4 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/config.txt b/Documentation/config.txt\n> index e0b9fd0bc..158cb588b 100644\n> --- a/Documentation/config.txt\n> +++ b/Documentation/config.txt\n> @@ -862,6 +862,7 @@ core.abbrev::\n>  \tcomputed based on the approximate number of packed objects\n>  \tin your repository, which hopefully is enough for\n>  \tabbreviated object names to stay unique for some time.\n> +\tThe minimum length is 4.\n>  \n>  add.ignoreErrors::\n>  add.ignore-errors (deprecated)::\n> diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt\n> index c40c47044..7a7421c8e 100644\n> --- a/Documentation/git-rev-parse.txt\n> +++ b/Documentation/git-rev-parse.txt\n> @@ -140,7 +140,9 @@ can be used.\n>  --short=number::\n>  \tInstead of outputting the full SHA-1 values of object names try to\n>  \tabbreviate them to a shorter unique name. When no length is specified\n> -\t7 is used. The minimum length is 4.\n> +\tthe effective value of the configuration variable `core.abbrev` (see\n> +\tlinkgit:git-config[1]) is used.  The minimum length is 4.  The length\n> +\tmay be exceeded to ensure unique object names.\tImplies `--verify`.\n\n\"Implies --verify\" is less important than the fact that multiple\nobject names cannot be given from the end-users' (and readers')\npoint of view, no?  The sentence in the pre-context still hints\n(incorrectly) that we might take multiple names---that would want to\nbe corrected, no?\n\nLet me try.\n\n    --short[=length]::\n\tTake a single object name, and output a prefix of the object\n\tname whose length is at least the specified length and\n\tsufficient to ensure uniqueness of the name.  The minimum\n\tlength is 4.  When no length is given, the effective value\n\tof the `core.abbrev` configuration variable is used.\n\nThanks.\n\n>  \n>  --symbolic::\n>  \tUsually the object names are output in SHA-1 form (with\n"},{"id":"321079","messageId":"787ad1fe-9923-d47d-79b0-8b0aebd8eb9b@gmail.com","threadId":"46061","inReplyTo":"xmqq1sr7dly4.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] doc: Improve description for rev-parse --short","fromName":"Andreas Heiduk","fromEmail":"asheiduk@gmail.com","sentAt":"2017-05-30T20:40:47Z","receivedAt":"2017-05-30T20:40:59Z","isPatch":true,"sender":{"key":"asheiduk@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9371344?v=4"},"body":"Am 30.05.2017 um 06:10 schrieb Junio C Hamano:\n>>  --short=number::\n>>  \tInstead of outputting the full SHA-1 values of object names try to\n>>  \tabbreviate them to a shorter unique name. When no length is specified\n>> -\t7 is used. The minimum length is 4.\n>> +\tthe effective value of the configuration variable `core.abbrev` (see\n>> +\tlinkgit:git-config[1]) is used.  The minimum length is 4.  The length\n>> +\tmay be exceeded to ensure unique object names.\tImplies `--verify`.\n> \n> \"Implies --verify\" is less important than the fact that multiple\n> object names cannot be given from the end-users' (and readers')\n> point of view, no?  The sentence in the pre-context still hints\n> (incorrectly) that we might take multiple names---that would want to\n> be corrected, no?\n> \n> Let me try.\n> \n>     --short[=length]::\n> \tTake a single object name, and output a prefix of the object\n> \tname whose length is at least the specified length and\n> \tsufficient to ensure uniqueness of the name.  The minimum\n> \tlength is 4.  When no length is given, the effective value\n> \tof the `core.abbrev` configuration variable is used.\n> \n> Thanks.\n\nYour are right about s/names/name/ in the pretext.\n\nBut I think that the link to the `--verify` option is still important.\nThe text there talks about when something is output, exit codes and\nabout `^{type}` peeling. Also `--quiet` is linked to\n`--verify` and hence relevant here.\n\nSo I'd like to patch your text to this:\n\n  --short[=length]::\n\tSame as `--verify` but output only a prefix of the object\n\tname whose length is at least the specified length and\n\tsufficient to ensure uniqueness of the name.  The minimum\n\tlength is 4.  When no length is given, the effective value\n\tof the `core.abbrev` configuration variable is used.\n\nAnd I'd like to move the section up right to `--verify` and `--quiet`.\nThe options in this section are not sorted alphabetically anyways and\nthe relevant parts would be adjacent. Is that OK?\n\nALso: Did you remove the `linkgit` by intention or just by accident?\n"},{"id":"321096","messageId":"xmqqfufm9bnb.fsf@gitster.mtv.corp.google.com","threadId":"46061","inReplyTo":"787ad1fe-9923-d47d-79b0-8b0aebd8eb9b@gmail.com","subject":"Re: [PATCH] doc: Improve description for rev-parse --short","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-05-30T23:18:32Z","receivedAt":"2017-05-30T23:18:38Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Andreas Heiduk <asheiduk@gmail.com> writes:\n\n> ALso: Did you remove the `linkgit` by intention or just by accident?\n\nBy accident.  I agree that \"Same as `--verify`\" is a good way to do\nthis.\n"},{"id":"321169","messageId":"20170531213929.19060-1-asheiduk@gmail.com","threadId":"46061","inReplyTo":"20170528143322.8580-1-asheiduk@gmail.com","subject":"[PATCH v1] doc: rewrite description for rev-parse --short","fromName":"Andreas Heiduk","fromEmail":"asheiduk@gmail.com","sentAt":"2017-05-31T21:39:29Z","receivedAt":"2017-05-31T21:39:44Z","isPatch":true,"sender":{"key":"asheiduk@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9371344?v=4"},"body":"`git rev-parse --short` is not a generic modifier but just a variant\nof `--verify` and considers the given length only as a suggestion to\nensure uniqueness.\n\nSigned-off-by: Andreas Heiduk <asheiduk@gmail.com>\n---\n Documentation/config.txt        |  1 +\n Documentation/git-rev-parse.txt | 12 ++++++------\n 2 files changed, 7 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex 43d830ee3..3256a3344 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -883,6 +883,7 @@ core.abbrev::\n \tcomputed based on the approximate number of packed objects\n \tin your repository, which hopefully is enough for\n \tabbreviated object names to stay unique for some time.\n+\tThe minimum length is 4.\n \n add.ignoreErrors::\n add.ignore-errors (deprecated)::\ndiff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt\nindex c40c47044..b1293f24b 100644\n--- a/Documentation/git-rev-parse.txt\n+++ b/Documentation/git-rev-parse.txt\n@@ -126,6 +126,12 @@ can be used.\n \t'git diff-{asterisk}'). In contrast to the `--sq-quote` option,\n \tthe command input is still interpreted as usual.\n \n+--short[=length]::\n+\tSame as `--verify` but shortens the object name to a unique\n+\tprefix with at least `length` characters. The minimum length\n+\tis 4, the default is the effective value of the `core.abbrev`\n+\tconfiguration variable (see linkgit:git-config[1]).\n+\n --not::\n \tWhen showing object names, prefix them with '{caret}' and\n \tstrip '{caret}' prefix from the object names that already have\n@@ -136,12 +142,6 @@ can be used.\n \tThe option core.warnAmbiguousRefs is used to select the strict\n \tabbreviation mode.\n \n---short::\n---short=number::\n-\tInstead of outputting the full SHA-1 values of object names try to\n-\tabbreviate them to a shorter unique name. When no length is specified\n-\t7 is used. The minimum length is 4.\n-\n --symbolic::\n \tUsually the object names are output in SHA-1 form (with\n \tpossible '{caret}' prefix); this option makes them output in a\n-- \n2.13.0\n\n"}]}