{"thread":{"id":"54566","subject":"Bug with --abbrev option in git log?","startedAt":"2020-11-04T00:55:49Z","lastAt":"2020-11-07T15:09:09Z","messageCount":7,"participants":["Mário Guimarães","Junio C Hamano","Derrick Stolee"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"409057","messageId":"CAF7CYk51BC0KcsBb0KjKWAj17AMU2c9Y6Y81ddwX6oOAFYhT8w@mail.gmail.com","threadId":"54566","inReplyTo":null,"subject":"Bug with --abbrev option in git log?","fromName":"Mário Guimarães","fromEmail":"mario.luis.guimaraes@gmail.com","sentAt":"2020-11-04T00:55:36Z","receivedAt":"2020-11-04T00:55:49Z","isPatch":false,"sender":{"key":"mario.luis.guimaraes@gmail.com","avatar":"https://gravatar.com/avatar/8e173e2e6a2c6632ccc7553f6528a149c83142191584c6edb1d6f34f91ff8a2b?d=mp&s=160"},"body":"Hello Git community,\n\nplease see next what I believe to be a bug with the  --abbrev option in git log.\nIf this is not a bug, can someone explain why Git is giving this output?\n\nThanks\nMário Guimarães\n\n======================================================\nThank you for filling out a Git bug report!\nPlease answer the following questions to help us understand your issue.\n\nWhat did you do before the bug happened? (Steps to reproduce your issue)\n\nIn the Git repository run this command:\n\ngit log --raw -r -c --abbrev=6 --pretty=oneline -n1\na7144d4bc5ab58f306a1e5c73b27196fb999a63d\n\nWhat did you expect to happen? (Expected behavior)\n\nI was expecting to get this line in the output\n\n::100644 100644 100644 639a41 111378 05ba1d MM Documentation/git-rebase.txt\n\nWhat happened instead? (Actual behavior)\n\nI got the following line instead\n\n::100644 100644 100644 639a41 111378 05ba1d3 MM Documentation/git-rebase.txt\n\nWhat's different between what you expected and what actually happened?\n\nSince `--abbrev` is set to 6 the expected hash is `05ba1d` not `05ba1d3`.\n\nAnything else you want to add:\n\nIf --abbrev is set to N then the size of all hashes should be the\nfirst N hex digits.\n\nThe problem with `--abbrev` is more evident with values below 7. Try with 1, 2,\n3, 4, and 5, to see for yourself.\n\nPlease review the rest of the bug report below.\nYou can delete any lines you don't wish to share.\n\n\n[System Info]\ngit version:\ngit version 2.29.2\ncpu: x86_64\nno commit associated with this build\nsizeof-long: 8\nsizeof-size_t: 8\nshell-path: /bin/sh\nuname: Darwin 19.6.0 Darwin Kernel Version 19.6.0: Mon Aug 31 22:12:52\nPDT 2020; root:xnu-6153.141.2~1/RELEASE_X86_64 x86_64\ncompiler info: clang: 12.0.0 (clang-1200.0.32.21)\nlibc info: no libc information available\n$SHELL (typically, interactive shell): /bin/bash\n\n\n[Enabled Hooks]\n======================================================\n"},{"id":"409059","messageId":"xmqqk0v1q60l.fsf@gitster.c.googlers.com","threadId":"54566","inReplyTo":"CAF7CYk51BC0KcsBb0KjKWAj17AMU2c9Y6Y81ddwX6oOAFYhT8w@mail.gmail.com","subject":"Re: Bug with --abbrev option in git log?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-11-04T01:12:42Z","receivedAt":"2020-11-04T01:12:48Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Mário Guimarães  <mario.luis.guimaraes@gmail.com> writes:\n\n> In the Git repository run this command:\n>\n> git log --raw -r -c --abbrev=6 --pretty=oneline -n1\n> a7144d4bc5ab58f306a1e5c73b27196fb999a63d\n\nThis is not one of my object, so above won't be usable as\nreproduction recipe.  But that is OK.\n\n> What did you expect to happen? (Expected behavior)\n>\n> I was expecting to get this line in the output\n>\n> ::100644 100644 100644 639a41 111378 05ba1d MM Documentation/git-rebase.txt\n>\n> What happened instead? (Actual behavior)\n>\n> I got the following line instead\n>\n> ::100644 100644 100644 639a41 111378 05ba1d3 MM Documentation/git-rebase.txt\n\nThe above command tells us that you locally have an object whose\nname begins with 05ba1d3, which I do not have.  But my history\nshared with the entire world has an object whose name begins with\n05ba1d7, and I am reasonably sure that your repository has it, since\nit is a part of 17f26a9e (git-am: fix shell quoting, 2009-01-14).\n\nSo in my repository, 05ba1d is enough to uniquely identify 05ba1d7,\nbut in your repository 05ba1d is not enough to uniquely identify\n05ba1d3, because 05ba1d7 also exists in your repository.  And when\nthe object cannot be uniquely specified with the given abbreviation\nwidth, Git makes sure its output is usable to uniquely identify the\nobject it wants to name.\n\nIn short, I think what you observed is totally expected.\n\nThe documentation has some room for improvement, I also think.\n\nHow about saying something like this?\n\n\n\n Documentation/diff-options.txt | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git i/Documentation/diff-options.txt w/Documentation/diff-options.txt\nindex ee52b65e46..114e440c5b 100644\n--- i/Documentation/diff-options.txt\n+++ w/Documentation/diff-options.txt\n@@ -446,7 +446,8 @@ endif::git-format-patch[]\n --abbrev[=<n>]::\n \tInstead of showing the full 40-byte hexadecimal object\n \tname in diff-raw format output and diff-tree header\n-\tlines, show only a partial prefix.\n+\tlines, show only a partial prefix that uses at least '<n>'\n+\thexdigits.\n \tIn diff-patch output format, `--full-index` takes higher\n \tprecedence, i.e. if `--full-index` is specified, full blob\n \tnames will be shown regardless of `--abbrev`.\n"},{"id":"409061","messageId":"xmqqblgdq4k0.fsf_-_@gitster.c.googlers.com","threadId":"54566","inReplyTo":"xmqqk0v1q60l.fsf@gitster.c.googlers.com","subject":"[PATCH] doc: clarify that most --abbrev[=<n>] are about minimum length","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-11-04T01:44:15Z","receivedAt":"2020-11-04T01:44:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Early text written in 2006 explains the \"--abbrev=<n>\" option to\n\"show only a partial prefix\", without saying that the length of the\npartial prefix is not necessarily the number given to the option to\nensure that the output names the object uniquely.\n\nLuckily, the text written for \"git describe\" in 2011 explains that\nthe output is made to name the object uniquely using at least <n>\nhexdigits much clearly.\n\nModel the explanation and update documentation for the diff family\nof commands, \"blame\", \"branch --verbose\", \"ls-files\" and \"ls-tree\".\n\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n Documentation/diff-options.txt   | 3 ++-\n Documentation/git-blame.txt      | 4 +++-\n Documentation/git-branch.txt     | 8 +++++---\n Documentation/git-ls-files.txt   | 5 +++--\n Documentation/git-ls-tree.txt    | 3 ++-\n Documentation/pretty-options.txt | 3 ++-\n 6 files changed, 17 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex 573fb9bb71..d73fdb8567 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -446,7 +446,8 @@ endif::git-format-patch[]\n --abbrev[=<n>]::\n \tInstead of showing the full 40-byte hexadecimal object\n \tname in diff-raw format output and diff-tree header\n-\tlines, show only a partial prefix.\n+\tlines, show <n> hexadecimal digits, or as many digits\n+\tas needed to form a unique object name.\n \tIn diff-patch output format, `--full-index` takes higher\n \tprecedence, i.e. if `--full-index` is specified, full blob\n \tnames will be shown regardless of `--abbrev`.\ndiff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt\nindex 7e81541996..34b496d485 100644\n--- a/Documentation/git-blame.txt\n+++ b/Documentation/git-blame.txt\n@@ -87,7 +87,9 @@ include::blame-options.txt[]\n \n --abbrev=<n>::\n \tInstead of using the default 7+1 hexadecimal digits as the\n-\tabbreviated object name, use <n>+1 digits. Note that 1 column\n+\tabbreviated object name, use <m>+1 digits, where <m> is at\n+\tleast <n> but ensures the commit object names are unique.\n+\tNote that 1 column\n \tis used for a caret to mark the boundary commit.\n \n \ndiff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\nindex ace4ad3da8..89611c3959 100644\n--- a/Documentation/git-branch.txt\n+++ b/Documentation/git-branch.txt\n@@ -9,7 +9,7 @@ SYNOPSIS\n --------\n [verse]\n 'git branch' [--color[=<when>] | --no-color] [--show-current]\n-\t[-v [--abbrev=<length> | --no-abbrev]]\n+\t[-v [--abbrev=<n> | --no-abbrev]]\n \t[--column[=<options>] | --no-column] [--sort=<key>]\n \t[--merged [<commit>]] [--no-merged [<commit>]]\n \t[--contains [<commit>]] [--no-contains [<commit>]]\n@@ -194,8 +194,10 @@ This option is only applicable in non-verbose mode.\n \tBe more quiet when creating or deleting a branch, suppressing\n \tnon-error messages.\n \n---abbrev=<length>::\n-\tAlter the sha1's minimum display length in the output listing.\n+--abbrev=<n>::\n+\tIn the verbose listing that show the commit object name,\n+\tuse <n>, or as many hexdigits as needed to form a unique\n+\tobject name.\n \tThe default value is 7 and can be overridden by the `core.abbrev`\n \tconfig option.\n \ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex 3cb2ebb438..60e3063fed 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -19,7 +19,7 @@ SYNOPSIS\n \t\t[--exclude-standard]\n \t\t[--error-unmatch] [--with-tree=<tree-ish>]\n \t\t[--full-name] [--recurse-submodules]\n-\t\t[--abbrev] [--] [<file>...]\n+\t\t[--abbrev[=<n>]] [--] [<file>...]\n \n DESCRIPTION\n -----------\n@@ -153,7 +153,8 @@ a space) at the start of each line:\n \n --abbrev[=<n>]::\n \tInstead of showing the full 40-byte hexadecimal object\n-\tlines, show only a partial prefix.\n+\tlines, show <n>, or as many hexadecimal digits\n+\tas needed, to form a unique object name.\n \tNon default number of digits can be specified with --abbrev=<n>.\n \n --debug::\ndiff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt\nindex a7515714da..480c668d0f 100644\n--- a/Documentation/git-ls-tree.txt\n+++ b/Documentation/git-ls-tree.txt\n@@ -62,7 +62,8 @@ OPTIONS\n \n --abbrev[=<n>]::\n \tInstead of showing the full 40-byte hexadecimal object\n-\tlines, show only a partial prefix.\n+\tlines, show <n>, or as many hexadecimal digits\n+\tas needed, to form a unique object name.\n \tNon default number of digits can be specified with --abbrev=<n>.\n \n --full-name::\ndiff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt\nindex 17c5aac4b7..da6ab0de0c 100644\n--- a/Documentation/pretty-options.txt\n+++ b/Documentation/pretty-options.txt\n@@ -16,7 +16,8 @@ configuration (see linkgit:git-config[1]).\n \n --abbrev-commit::\n \tInstead of showing the full 40-byte hexadecimal commit object\n-\tname, show only a partial prefix.  Non default number of\n+\tname, show only a partial prefix that names the object uniquely.\n+\tNon default number of\n \tdigits can be specified with \"--abbrev=<n>\" (which also modifies\n \tdiff output, if it is displayed).\n +\n-- \n2.29.2-287-gba574db674\n\n"},{"id":"409062","messageId":"CAF7CYk6SVx396=fLZ2yMVTaS2XK58M_=kT7J+th_T8VqM+HmaQ@mail.gmail.com","threadId":"54566","inReplyTo":"xmqqk0v1q60l.fsf@gitster.c.googlers.com","subject":"Re: Bug with --abbrev option in git log?","fromName":"Mário Guimarães","fromEmail":"mario.luis.guimaraes@gmail.com","sentAt":"2020-11-04T02:11:13Z","receivedAt":"2020-11-04T02:11:27Z","isPatch":false,"sender":{"key":"mario.luis.guimaraes@gmail.com","avatar":"https://gravatar.com/avatar/8e173e2e6a2c6632ccc7553f6528a149c83142191584c6edb1d6f34f91ff8a2b?d=mp&s=160"},"body":"Hello\n\nJunio C Hamano <gitster@pobox.com> escreveu no dia quarta, 4/11/2020 à(s) 01:12:\n>\n> Mário Guimarães  <mario.luis.guimaraes@gmail.com> writes:\n>\n> > In the Git repository run this command:\n> >\n> > git log --raw -r -c --abbrev=6 --pretty=oneline -n1\n> > a7144d4bc5ab58f306a1e5c73b27196fb999a63d\n>\n> This is not one of my object, so above won't be usable as\n> reproduction recipe.  But that is OK.\n>\n> > What did you expect to happen? (Expected behavior)\n> >\n> > I was expecting to get this line in the output\n> >\n> > ::100644 100644 100644 639a41 111378 05ba1d MM Documentation/git-rebase.txt\n> >\n> > What happened instead? (Actual behavior)\n> >\n> > I got the following line instead\n> >\n> > ::100644 100644 100644 639a41 111378 05ba1d3 MM Documentation/git-rebase.txt\n>\n> The above command tells us that you locally have an object whose\n> name begins with 05ba1d3, which I do not have.  But my history\n> shared with the entire world has an object whose name begins with\n> 05ba1d7, and I am reasonably sure that your repository has it, since\n> it is a part of 17f26a9e (git-am: fix shell quoting, 2009-01-14).\n>\n> So in my repository, 05ba1d is enough to uniquely identify 05ba1d7,\n> but in your repository 05ba1d is not enough to uniquely identify\n> 05ba1d3, because 05ba1d7 also exists in your repository.  And when\n> the object cannot be uniquely specified with the given abbreviation\n> width, Git makes sure its output is usable to uniquely identify the\n> object it wants to name.\n>\n> In short, I think what you observed is totally expected.\n>\n> The documentation has some room for improvement, I also think.\n>\n> How about saying something like this?\n>\n>\n>\n>  Documentation/diff-options.txt | 3 ++-\n>  1 file changed, 2 insertions(+), 1 deletion(-)\n>\n> diff --git i/Documentation/diff-options.txt w/Documentation/diff-options.txt\n> index ee52b65e46..114e440c5b 100644\n> --- i/Documentation/diff-options.txt\n> +++ w/Documentation/diff-options.txt\n> @@ -446,7 +446,8 @@ endif::git-format-patch[]\n>  --abbrev[=<n>]::\n>         Instead of showing the full 40-byte hexadecimal object\n>         name in diff-raw format output and diff-tree header\n> -       lines, show only a partial prefix.\n> +       lines, show only a partial prefix that uses at least '<n>'\n> +       hexdigits.\n>         In diff-patch output format, `--full-index` takes higher\n>         precedence, i.e. if `--full-index` is specified, full blob\n>         names will be shown regardless of `--abbrev`.\n\nWhat about this? It makes clear that the prefix is still one that can\nbe used to identify the object in the repository.\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex ee52b65e46..c15b4adb28 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -446,8 +446,9 @@ endif::git-format-patch[]\n --abbrev[=<n>]::\n        Instead of showing the full 40-byte hexadecimal object\n        name in diff-raw format output and diff-tree header\n-       lines, show only a partial prefix.\n-       In diff-patch output format, `--full-index` takes higher\n+       lines, show only the minimal prefix that identifies\n+       the object using at least `<n>` hexdigits.\n        In diff-patch output format, `--full-index` takes higher\n        precedence, i.e. if `--full-index` is specified, full blob\n        names will be shown regardless of `--abbrev`.\n        Non default number of digits can be specified with `--abbrev=<n>`.\n"},{"id":"409072","messageId":"b7d6ea51-6aaa-bf74-2e19-1d1283001489@gmail.com","threadId":"54566","inReplyTo":"xmqqblgdq4k0.fsf_-_@gitster.c.googlers.com","subject":"Re: [PATCH] doc: clarify that most --abbrev[=<n>] are about minimum length","fromName":"Derrick Stolee","fromEmail":"stolee@gmail.com","sentAt":"2020-11-04T13:24:35Z","receivedAt":"2020-11-04T13:24:40Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"On 11/3/2020 8:44 PM, Junio C Hamano wrote:\n> Early text written in 2006 explains the \"--abbrev=<n>\" option to\n> \"show only a partial prefix\", without saying that the length of the\n> partial prefix is not necessarily the number given to the option to\n> ensure that the output names the object uniquely.\n> \n> Luckily, the text written for \"git describe\" in 2011 explains that\n> the output is made to name the object uniquely using at least <n>\n> hexdigits much clearly.\n> \n> Model the explanation and update documentation for the diff family\n> of commands, \"blame\", \"branch --verbose\", \"ls-files\" and \"ls-tree\".\n\nThanks for being thorough here! Your patch is already an\nimprovement on what we have. I hope that my suggestions\nbelow help to improve it further.\n\n> --- a/Documentation/diff-options.txt\n> +++ b/Documentation/diff-options.txt\n> @@ -446,7 +446,8 @@ endif::git-format-patch[]\n>  --abbrev[=<n>]::\n>  \tInstead of showing the full 40-byte hexadecimal object\n>  \tname in diff-raw format output and diff-tree header\n> -\tlines, show only a partial prefix.\n> +\tlines, show <n> hexadecimal digits, or as many digits\n> +\tas needed to form a unique object name.\n\nA reoccurring theme in this patch is that the --abbrev option\nprovides a lower bound, even if fewer digits are needed for a\nunique object name. Using these two phrases with an \"or\" has\nsome ambiguity about which is chosen.\n\nPerhaps we should try to describe it as \"<n> is the default,\nbut can grow as needed\". Here is an attempt:\n\n-\tlines, show only a partial prefix.\n+\tlines, show at least <n> hexadecimal digits, increasing the\n+\tprefix length as needed to uniquely identify an object.\n\nIf you prefer wording like this, then there are a few very\nsimilar snippets later in git-branch.txt and git-ls-files.txt.\n\n> --- a/Documentation/git-blame.txt\n> +++ b/Documentation/git-blame.txt\n> @@ -87,7 +87,9 @@ include::blame-options.txt[]\n>  \n>  --abbrev=<n>::\n>  \tInstead of using the default 7+1 hexadecimal digits as the\n> -\tabbreviated object name, use <n>+1 digits. Note that 1 column\n> +\tabbreviated object name, use <m>+1 digits, where <m> is at\n> +\tleast <n> but ensures the commit object names are unique.\n> +\tNote that 1 column\n>  \tis used for a caret to mark the boundary commit.\n\nThis captures the \"at least <n>\" pretty well, especially considering\nthe complications around \"+1\".\n\n> ---abbrev=<length>::\n> -\tAlter the sha1's minimum display length in the output listing.\n> +--abbrev=<n>::\n> +\tIn the verbose listing that show the commit object name,\n> +\tuse <n>, or as many hexdigits as needed to form a unique\n> +\tobject name.\n\nAdapting from your wording here made me think that this might\nbe a simpler way to phrase it:\n\n+--abbrev=<n>::\n+\tIn the verbose listing that show the commit object name,\n+\tuse at least <n> hexdigits to form a unique object name.\n\n> diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt\n> index 17c5aac4b7..da6ab0de0c 100644\n> --- a/Documentation/pretty-options.txt\n> +++ b/Documentation/pretty-options.txt\n> @@ -16,7 +16,8 @@ configuration (see linkgit:git-config[1]).\n>  \n>  --abbrev-commit::\n>  \tInstead of showing the full 40-byte hexadecimal commit object\n> -\tname, show only a partial prefix.  Non default number of\n> +\tname, show only a partial prefix that names the object uniquely.\n\nPerhaps \"show a prefix that uniquely identifies the object\" ?\n\n> +\tNon default number of\n>  \tdigits can be specified with \"--abbrev=<n>\" (which also modifies\n>  \tdiff output, if it is displayed).\n\nI know this is in the existing docs, but this last sentence should\nprobably start with \"A non-default number of digits...\" Alternatively,\nwe could rephrase the entire thing to use more active voice:\n\n+ The `--abbrev=<n>` option modifies the minimum number of digits\n+ for these prefixes, including objects reported in displayed diff\n+ output.\n\nThanks,\n-Stolee\n"},{"id":"409171","messageId":"xmqq8sbglr26.fsf_-_@gitster.c.googlers.com","threadId":"54566","inReplyTo":"b7d6ea51-6aaa-bf74-2e19-1d1283001489@gmail.com","subject":"[PATCH v2] doc: clarify that --abbrev=<n> is about the minimum length","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-11-04T22:01:37Z","receivedAt":"2020-11-04T22:02:56Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Early text written in 2006 explains the \"--abbrev=<n>\" option to\n\"show only a partial prefix\", without saying that the length of the\npartial prefix is not necessarily the number given to the option to\nensure that the output names the object uniquely.\n\nUpdate documentation for the diff family of commands, \"blame\",\n\"branch --verbose\", \"ls-files\" and \"ls-tree\" to stress that the\nshort prefix must uniquely refer to an object, and <n> is merely\nthe mininum number of hexdigits used in the prefix.\n\nHelped-by: Derrick Stolee <dstolee@microsoft.com>\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n\n * Thanks for your suggestion.  I decided to use \"the shortest\n   prefix that is at least <n> hexdigits long\".\n\n\nRange-diff:\n1:  01c62c8d6f ! 1:  4f8524079c doc: clarify that most --abbrev[=<n>] are about minimum length\n    @@ Metadata\n     Author: Junio C Hamano <gitster@pobox.com>\n     \n      ## Commit message ##\n    -    doc: clarify that most --abbrev[=<n>] are about minimum length\n    +    doc: clarify that --abbrev=<n> is about the minimum length\n     \n         Early text written in 2006 explains the \"--abbrev=<n>\" option to\n         \"show only a partial prefix\", without saying that the length of the\n         partial prefix is not necessarily the number given to the option to\n         ensure that the output names the object uniquely.\n     \n    -    Luckily, the text written for \"git describe\" in 2011 explains that\n    -    the output is made to name the object uniquely using at least <n>\n    -    hexdigits much clearly.\n    -\n    -    Model the explanation and update documentation for the diff family\n    -    of commands, \"blame\", \"branch --verbose\", \"ls-files\" and \"ls-tree\".\n    +    Update documentation for the diff family of commands, \"blame\",\n    +    \"branch --verbose\", \"ls-files\" and \"ls-tree\" to stress that the\n    +    short prefix must uniquely refer to an object, and <n> is merely\n    +    the mininum number of hexdigits used in the prefix.\n     \n    +    Helped-by: Derrick Stolee <dstolee@microsoft.com>\n         Signed-off-by: Junio C Hamano <gitster@pobox.com>\n     \n      ## Documentation/diff-options.txt ##\n    @@ Documentation/diff-options.txt: endif::git-format-patch[]\n      \tInstead of showing the full 40-byte hexadecimal object\n      \tname in diff-raw format output and diff-tree header\n     -\tlines, show only a partial prefix.\n    -+\tlines, show <n> hexadecimal digits, or as many digits\n    -+\tas needed to form a unique object name.\n    ++\tlines, show the shortest prefix that is at least '<n>'\n    ++\thexdigits long that uniquely refers the object.\n      \tIn diff-patch output format, `--full-index` takes higher\n      \tprecedence, i.e. if `--full-index` is specified, full blob\n      \tnames will be shown regardless of `--abbrev`.\n    @@ Documentation/git-branch.txt: This option is only applicable in non-verbose mode\n     -\tAlter the sha1's minimum display length in the output listing.\n     +--abbrev=<n>::\n     +\tIn the verbose listing that show the commit object name,\n    -+\tuse <n>, or as many hexdigits as needed to form a unique\n    -+\tobject name.\n    ++\tshow the shortest prefix that is at least '<n>' hexdigits\n    ++\tlong that uniquely refers the object.\n      \tThe default value is 7 and can be overridden by the `core.abbrev`\n      \tconfig option.\n      \n    @@ Documentation/git-ls-files.txt: a space) at the start of each line:\n      --abbrev[=<n>]::\n      \tInstead of showing the full 40-byte hexadecimal object\n     -\tlines, show only a partial prefix.\n    -+\tlines, show <n>, or as many hexadecimal digits\n    -+\tas needed, to form a unique object name.\n    ++\tlines, show the shortest prefix that is at least '<n>'\n    ++\thexdigits long that uniquely refers the object.\n      \tNon default number of digits can be specified with --abbrev=<n>.\n      \n      --debug::\n    @@ Documentation/git-ls-tree.txt: OPTIONS\n      --abbrev[=<n>]::\n      \tInstead of showing the full 40-byte hexadecimal object\n     -\tlines, show only a partial prefix.\n    -+\tlines, show <n>, or as many hexadecimal digits\n    -+\tas needed, to form a unique object name.\n    ++\tlines, show the shortest prefix that is at least '<n>'\n    ++\thexdigits long that uniquely refers the object.\n      \tNon default number of digits can be specified with --abbrev=<n>.\n      \n      --full-name::\n    @@ Documentation/pretty-options.txt: configuration (see linkgit:git-config[1]).\n      --abbrev-commit::\n      \tInstead of showing the full 40-byte hexadecimal commit object\n     -\tname, show only a partial prefix.  Non default number of\n    -+\tname, show only a partial prefix that names the object uniquely.\n    -+\tNon default number of\n    - \tdigits can be specified with \"--abbrev=<n>\" (which also modifies\n    - \tdiff output, if it is displayed).\n    +-\tdigits can be specified with \"--abbrev=<n>\" (which also modifies\n    +-\tdiff output, if it is displayed).\n    ++\tname, show a prefix that names the object uniquely.\n    ++\t\"--abbrev=<n>\" (which also modifies diff output, if it is displayed)\n    ++\toption can be used to specify the minimum length of the prefix.\n      +\n    + This should make \"--pretty=oneline\" a whole lot more readable for\n    + people using 80-column terminals.\n\n Documentation/diff-options.txt   | 3 ++-\n Documentation/git-blame.txt      | 4 +++-\n Documentation/git-branch.txt     | 8 +++++---\n Documentation/git-ls-files.txt   | 5 +++--\n Documentation/git-ls-tree.txt    | 3 ++-\n Documentation/pretty-options.txt | 6 +++---\n 6 files changed, 18 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex 573fb9bb71..706c69bc82 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -446,7 +446,8 @@ endif::git-format-patch[]\n --abbrev[=<n>]::\n \tInstead of showing the full 40-byte hexadecimal object\n \tname in diff-raw format output and diff-tree header\n-\tlines, show only a partial prefix.\n+\tlines, show the shortest prefix that is at least '<n>'\n+\thexdigits long that uniquely refers the object.\n \tIn diff-patch output format, `--full-index` takes higher\n \tprecedence, i.e. if `--full-index` is specified, full blob\n \tnames will be shown regardless of `--abbrev`.\ndiff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt\nindex 7e81541996..34b496d485 100644\n--- a/Documentation/git-blame.txt\n+++ b/Documentation/git-blame.txt\n@@ -87,7 +87,9 @@ include::blame-options.txt[]\n \n --abbrev=<n>::\n \tInstead of using the default 7+1 hexadecimal digits as the\n-\tabbreviated object name, use <n>+1 digits. Note that 1 column\n+\tabbreviated object name, use <m>+1 digits, where <m> is at\n+\tleast <n> but ensures the commit object names are unique.\n+\tNote that 1 column\n \tis used for a caret to mark the boundary commit.\n \n \ndiff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\nindex ace4ad3da8..adaa1782a8 100644\n--- a/Documentation/git-branch.txt\n+++ b/Documentation/git-branch.txt\n@@ -9,7 +9,7 @@ SYNOPSIS\n --------\n [verse]\n 'git branch' [--color[=<when>] | --no-color] [--show-current]\n-\t[-v [--abbrev=<length> | --no-abbrev]]\n+\t[-v [--abbrev=<n> | --no-abbrev]]\n \t[--column[=<options>] | --no-column] [--sort=<key>]\n \t[--merged [<commit>]] [--no-merged [<commit>]]\n \t[--contains [<commit>]] [--no-contains [<commit>]]\n@@ -194,8 +194,10 @@ This option is only applicable in non-verbose mode.\n \tBe more quiet when creating or deleting a branch, suppressing\n \tnon-error messages.\n \n---abbrev=<length>::\n-\tAlter the sha1's minimum display length in the output listing.\n+--abbrev=<n>::\n+\tIn the verbose listing that show the commit object name,\n+\tshow the shortest prefix that is at least '<n>' hexdigits\n+\tlong that uniquely refers the object.\n \tThe default value is 7 and can be overridden by the `core.abbrev`\n \tconfig option.\n \ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex 3cb2ebb438..cbcf5263dd 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -19,7 +19,7 @@ SYNOPSIS\n \t\t[--exclude-standard]\n \t\t[--error-unmatch] [--with-tree=<tree-ish>]\n \t\t[--full-name] [--recurse-submodules]\n-\t\t[--abbrev] [--] [<file>...]\n+\t\t[--abbrev[=<n>]] [--] [<file>...]\n \n DESCRIPTION\n -----------\n@@ -153,7 +153,8 @@ a space) at the start of each line:\n \n --abbrev[=<n>]::\n \tInstead of showing the full 40-byte hexadecimal object\n-\tlines, show only a partial prefix.\n+\tlines, show the shortest prefix that is at least '<n>'\n+\thexdigits long that uniquely refers the object.\n \tNon default number of digits can be specified with --abbrev=<n>.\n \n --debug::\ndiff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt\nindex a7515714da..db02d6d79a 100644\n--- a/Documentation/git-ls-tree.txt\n+++ b/Documentation/git-ls-tree.txt\n@@ -62,7 +62,8 @@ OPTIONS\n \n --abbrev[=<n>]::\n \tInstead of showing the full 40-byte hexadecimal object\n-\tlines, show only a partial prefix.\n+\tlines, show the shortest prefix that is at least '<n>'\n+\thexdigits long that uniquely refers the object.\n \tNon default number of digits can be specified with --abbrev=<n>.\n \n --full-name::\ndiff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt\nindex 17c5aac4b7..27ddaf84a1 100644\n--- a/Documentation/pretty-options.txt\n+++ b/Documentation/pretty-options.txt\n@@ -16,9 +16,9 @@ configuration (see linkgit:git-config[1]).\n \n --abbrev-commit::\n \tInstead of showing the full 40-byte hexadecimal commit object\n-\tname, show only a partial prefix.  Non default number of\n-\tdigits can be specified with \"--abbrev=<n>\" (which also modifies\n-\tdiff output, if it is displayed).\n+\tname, show a prefix that names the object uniquely.\n+\t\"--abbrev=<n>\" (which also modifies diff output, if it is displayed)\n+\toption can be used to specify the minimum length of the prefix.\n +\n This should make \"--pretty=oneline\" a whole lot more readable for\n people using 80-column terminals.\n-- \n2.29.2-287-gba574db674\n\n"},{"id":"409323","messageId":"98710644-c060-c64e-8c0c-a27bfa0e58fb@gmail.com","threadId":"54566","inReplyTo":"xmqq8sbglr26.fsf_-_@gitster.c.googlers.com","subject":"Re: [PATCH v2] doc: clarify that --abbrev=<n> is about the minimum length","fromName":"Derrick Stolee","fromEmail":"stolee@gmail.com","sentAt":"2020-11-07T15:09:04Z","receivedAt":"2020-11-07T15:09:09Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"On 11/4/20 5:01 PM, Junio C Hamano wrote:\n> Early text written in 2006 explains the \"--abbrev=<n>\" option to\n> \"show only a partial prefix\", without saying that the length of the\n> partial prefix is not necessarily the number given to the option to\n> ensure that the output names the object uniquely.\n> \n> Update documentation for the diff family of commands, \"blame\",\n> \"branch --verbose\", \"ls-files\" and \"ls-tree\" to stress that the\n> short prefix must uniquely refer to an object, and <n> is merely\n> the mininum number of hexdigits used in the prefix.\n> \n> Helped-by: Derrick Stolee <dstolee@microsoft.com>\n> Signed-off-by: Junio C Hamano <gitster@pobox.com>\n> ---\n> \n>  * Thanks for your suggestion.  I decided to use \"the shortest\n>    prefix that is at least <n> hexdigits long\".\n\nI like this version. Thanks!\n\n-Stolee\n\n"}]}