doc: clarify that --abbrev=<n> is about the minimum length
Early text written in 2006 explains the "--abbrev=<n>" 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 <n> is merely the mininum number of hexdigits used in the prefix. Helped-by: Derrick Stolee <dstolee@microsoft.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano committed
Nov 4, 2020 at 14:01 UTC
cda34e0d0cc3e0b53e6c496c56e07e34c339263f
6 files changed
+18
-11
Documentation/diff-options.txt
+2
-1
@@ -446,7 +446,8 @@ endif::git-format-patch[]
446
--abbrev[=<n>]::
447
Instead of showing the full 40-byte hexadecimal object
448
name in diff-raw format output and diff-tree header
449
- lines, show only a partial prefix.
449
+ lines, show the shortest prefix that is at least '<n>'
450
+ hexdigits long that uniquely refers the object.
451
In diff-patch output format, `--full-index` takes higher
452
precedence, i.e. if `--full-index` is specified, full blob
453
names will be shown regardless of `--abbrev`.
Documentation/git-blame.txt
+3
-1
@@ -87,7 +87,9 @@ include::blame-options.txt[]
87
88
--abbrev=<n>::
89
Instead of using the default 7+1 hexadecimal digits as the
90
- abbreviated object name, use <n>+1 digits. Note that 1 column
90
+ abbreviated object name, use <m>+1 digits, where <m> is at
91
+ least <n> but ensures the commit object names are unique.
92
+ Note that 1 column
93
is used for a caret to mark the boundary commit.
94
95
Documentation/git-branch.txt
+5
-3
@@ -9,7 +9,7 @@ SYNOPSIS
9
--------
10
[verse]
11
'git branch' [--color[=<when>] | --no-color] [--show-current]
12
- [-v [--abbrev=<length> | --no-abbrev]]
12
+ [-v [--abbrev=<n> | --no-abbrev]]
13
[--column[=<options>] | --no-column] [--sort=<key>]
14
[--merged [<commit>]] [--no-merged [<commit>]]
15
[--contains [<commit>]] [--no-contains [<commit>]]
@@ -194,8 +194,10 @@ This option is only applicable in non-verbose mode.
194
Be more quiet when creating or deleting a branch, suppressing
195
non-error messages.
196
197
---abbrev=<length>::
198
- Alter the sha1's minimum display length in the output listing.
197
+--abbrev=<n>::
198
+ In the verbose listing that show the commit object name,
199
+ show the shortest prefix that is at least '<n>' hexdigits
200
+ long that uniquely refers the object.
201
The default value is 7 and can be overridden by the `core.abbrev`
202
config option.
203
Documentation/git-ls-files.txt
+3
-2
@@ -19,7 +19,7 @@ SYNOPSIS
19
[--exclude-standard]
20
[--error-unmatch] [--with-tree=<tree-ish>]
21
[--full-name] [--recurse-submodules]
22
- [--abbrev] [--] [<file>...]
22
+ [--abbrev[=<n>]] [--] [<file>...]
23
24
DESCRIPTION
25
-----------
@@ -153,7 +153,8 @@ a space) at the start of each line:
153
154
--abbrev[=<n>]::
155
Instead of showing the full 40-byte hexadecimal object
156
- lines, show only a partial prefix.
156
+ lines, show the shortest prefix that is at least '<n>'
157
+ hexdigits long that uniquely refers the object.
158
Non default number of digits can be specified with --abbrev=<n>.
159
160
--debug::
Documentation/git-ls-tree.txt
+2
-1
@@ -62,7 +62,8 @@ OPTIONS
62
63
--abbrev[=<n>]::
64
Instead of showing the full 40-byte hexadecimal object
65
- lines, show only a partial prefix.
65
+ lines, show the shortest prefix that is at least '<n>'
66
+ hexdigits long that uniquely refers the object.
67
Non default number of digits can be specified with --abbrev=<n>.
68
69
--full-name::
Documentation/pretty-options.txt
+3
-3
@@ -16,9 +16,9 @@ configuration (see linkgit:git-config[1]).
16
17
--abbrev-commit::
18
Instead of showing the full 40-byte hexadecimal commit object
19
- name, show only a partial prefix. Non default number of
20
- digits can be specified with "--abbrev=<n>" (which also modifies
21
- diff output, if it is displayed).
19
+ name, show a prefix that names the object uniquely.
20
+ "--abbrev=<n>" (which also modifies diff output, if it is displayed)
21
+ option can be used to specify the minimum length of the prefix.
22
+
23
This should make "--pretty=oneline" a whole lot more readable for
24
people using 80-column terminals.