From cda34e0d0cc3e0b53e6c496c56e07e34c339263f Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Wed, 4 Nov 2020 14:01:37 -0800 Subject: [PATCH] doc: clarify that --abbrev= is about the minimum length Early text written in 2006 explains the "--abbrev=" option to "show only a partial prefix", without saying that the length of the partial prefix is not necessarily the number given to the option to ensure that the output names the object uniquely. Update documentation for the diff family of commands, "blame", "branch --verbose", "ls-files" and "ls-tree" to stress that the short prefix must uniquely refer to an object, and is merely the mininum number of hexdigits used in the prefix. Helped-by: Derrick Stolee Signed-off-by: Junio C Hamano --- Documentation/diff-options.txt | 3 ++- Documentation/git-blame.txt | 4 +++- Documentation/git-branch.txt | 8 +++++--- Documentation/git-ls-files.txt | 5 +++-- Documentation/git-ls-tree.txt | 3 ++- Documentation/pretty-options.txt | 6 +++--- 6 files changed, 18 insertions(+), 11 deletions(-) diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 573fb9bb71e..706c69bc826 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -446,7 +446,8 @@ endif::git-format-patch[] --abbrev[=]:: Instead of showing the full 40-byte hexadecimal object name in diff-raw format output and diff-tree header - lines, show only a partial prefix. + lines, show the shortest prefix that is at least '' + hexdigits long that uniquely refers the object. In diff-patch output format, `--full-index` takes higher precedence, i.e. if `--full-index` is specified, full blob names will be shown regardless of `--abbrev`. diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt index 7e815419963..34b496d4858 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -87,7 +87,9 @@ include::blame-options.txt[] --abbrev=:: Instead of using the default 7+1 hexadecimal digits as the - abbreviated object name, use +1 digits. Note that 1 column + abbreviated object name, use +1 digits, where is at + least but ensures the commit object names are unique. + Note that 1 column is used for a caret to mark the boundary commit. diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index ace4ad3da88..adaa1782a8b 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git branch' [--color[=] | --no-color] [--show-current] - [-v [--abbrev= | --no-abbrev]] + [-v [--abbrev= | --no-abbrev]] [--column[=] | --no-column] [--sort=] [--merged []] [--no-merged []] [--contains []] [--no-contains []] @@ -194,8 +194,10 @@ This option is only applicable in non-verbose mode. Be more quiet when creating or deleting a branch, suppressing non-error messages. ---abbrev=:: - Alter the sha1's minimum display length in the output listing. +--abbrev=:: + In the verbose listing that show the commit object name, + show the shortest prefix that is at least '' hexdigits + long that uniquely refers the object. The default value is 7 and can be overridden by the `core.abbrev` config option. diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 3cb2ebb4380..cbcf5263dd0 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -19,7 +19,7 @@ SYNOPSIS [--exclude-standard] [--error-unmatch] [--with-tree=] [--full-name] [--recurse-submodules] - [--abbrev] [--] [...] + [--abbrev[=]] [--] [...] DESCRIPTION ----------- @@ -153,7 +153,8 @@ a space) at the start of each line: --abbrev[=]:: Instead of showing the full 40-byte hexadecimal object - lines, show only a partial prefix. + lines, show the shortest prefix that is at least '' + hexdigits long that uniquely refers the object. Non default number of digits can be specified with --abbrev=. --debug:: diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt index a7515714da1..db02d6d79a9 100644 --- a/Documentation/git-ls-tree.txt +++ b/Documentation/git-ls-tree.txt @@ -62,7 +62,8 @@ OPTIONS --abbrev[=]:: Instead of showing the full 40-byte hexadecimal object - lines, show only a partial prefix. + lines, show the shortest prefix that is at least '' + hexdigits long that uniquely refers the object. Non default number of digits can be specified with --abbrev=. --full-name:: diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt index 17c5aac4b71..27ddaf84a19 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -16,9 +16,9 @@ configuration (see linkgit:git-config[1]). --abbrev-commit:: Instead of showing the full 40-byte hexadecimal commit object - name, show only a partial prefix. Non default number of - digits can be specified with "--abbrev=" (which also modifies - diff output, if it is displayed). + name, show a prefix that names the object uniquely. + "--abbrev=" (which also modifies diff output, if it is displayed) + option can be used to specify the minimum length of the prefix. + This should make "--pretty=oneline" a whole lot more readable for people using 80-column terminals.