[v2] doc: clarify that --abbrev=<n> is about the minimum length

Commit Message

Junio C Hamano Nov. 4, 2020, 10:01 p.m. UTC

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 <[e-mail]>
Signed-off-by: Junio C Hamano <[e-mail]>
---

 * Thanks for your suggestion.  I decided to use "the shortest
   prefix that is at least <n> hexdigits long".


Range-diff:
1:  01c62c8d6f ! 1:  4f8524079c doc: clarify that most --abbrev[=<n>] are about minimum length
    @@ Metadata
     Author: Junio C Hamano <[e-mail]>
     
      ## Commit message ##
    -    doc: clarify that most --abbrev[=<n>] are about minimum length
    +    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.
     
    -    Luckily, the text written for "git describe" in 2011 explains that
    -    the output is made to name the object uniquely using at least <n>
    -    hexdigits much clearly.
    -
    -    Model the explanation and update documentation for the diff family
    -    of commands, "blame", "branch --verbose", "ls-files" and "ls-tree".
    +    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 <[e-mail]>
         Signed-off-by: Junio C Hamano <[e-mail]>
     
      ## Documentation/diff-options.txt ##
    @@ Documentation/diff-options.txt: endif::git-format-patch[]
      	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 <n> hexadecimal digits, or as many digits
    -+	as needed to form a unique object name.
    ++	lines, show the shortest prefix that is at least '<n>'
    ++	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`.
    @@ Documentation/git-branch.txt: This option is only applicable in non-verbose mode
     -	Alter the sha1's minimum display length in the output listing.
     +--abbrev=<n>::
     +	In the verbose listing that show the commit object name,
    -+	use <n>, or as many hexdigits as needed to form a unique
    -+	object name.
    ++	show the shortest prefix that is at least '<n>' hexdigits
    ++	long that uniquely refers the object.
      	The default value is 7 and can be overridden by the `core.abbrev`
      	config option.
      
    @@ Documentation/git-ls-files.txt: a space) at the start of each line:
      --abbrev[=<n>]::
      	Instead of showing the full 40-byte hexadecimal object
     -	lines, show only a partial prefix.
    -+	lines, show <n>, or as many hexadecimal digits
    -+	as needed, to form a unique object name.
    ++	lines, show the shortest prefix that is at least '<n>'
    ++	hexdigits long that uniquely refers the object.
      	Non default number of digits can be specified with --abbrev=<n>.
      
      --debug::
    @@ Documentation/git-ls-tree.txt: OPTIONS
      --abbrev[=<n>]::
      	Instead of showing the full 40-byte hexadecimal object
     -	lines, show only a partial prefix.
    -+	lines, show <n>, or as many hexadecimal digits
    -+	as needed, to form a unique object name.
    ++	lines, show the shortest prefix that is at least '<n>'
    ++	hexdigits long that uniquely refers the object.
      	Non default number of digits can be specified with --abbrev=<n>.
      
      --full-name::
    @@ Documentation/pretty-options.txt: 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
    -+	name, show only a partial prefix that names the object uniquely.
    -+	Non default number of
    - 	digits can be specified with "--abbrev=<n>" (which also modifies
    - 	diff output, if it is displayed).
    +-	digits can be specified with "--abbrev=<n>" (which also modifies
    +-	diff output, if it is displayed).
    ++	name, show a prefix that names the object uniquely.
    ++	"--abbrev=<n>" (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.

 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(-)

Comments

Derrick Stolee Nov. 7, 2020, 3:09 p.m. UTC | #1

On 11/4/20 5:01 PM, Junio C Hamano wrote:
> 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 <[e-mail]>
> Signed-off-by: Junio C Hamano <[e-mail]>
> ---
> 
>  * Thanks for your suggestion.  I decided to use "the shortest
>    prefix that is at least <n> hexdigits long".

I like this version. Thanks!

-Stolee

Patch

diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index 573fb9bb71..706c69bc82 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -446,7 +446,8 @@  endif::git-format-patch[]
 --abbrev[=<n>]::
 	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 '<n>'
+	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 7e81541996..34b496d485 100644
--- a/Documentation/git-blame.txt
+++ b/Documentation/git-blame.txt
@@ -87,7 +87,9 @@  include::blame-options.txt[]
 
 --abbrev=<n>::
 	Instead of using the default 7+1 hexadecimal digits as the
-	abbreviated object name, use <n>+1 digits. Note that 1 column
+	abbreviated object name, use <m>+1 digits, where <m> is at
+	least <n> 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 ace4ad3da8..adaa1782a8 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -9,7 +9,7 @@  SYNOPSIS
 --------
 [verse]
 'git branch' [--color[=<when>] | --no-color] [--show-current]
-	[-v [--abbrev=<length> | --no-abbrev]]
+	[-v [--abbrev=<n> | --no-abbrev]]
 	[--column[=<options>] | --no-column] [--sort=<key>]
 	[--merged [<commit>]] [--no-merged [<commit>]]
 	[--contains [<commit>]] [--no-contains [<commit>]]
@@ -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=<length>::
-	Alter the sha1's minimum display length in the output listing.
+--abbrev=<n>::
+	In the verbose listing that show the commit object name,
+	show the shortest prefix that is at least '<n>' 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 3cb2ebb438..cbcf5263dd 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -19,7 +19,7 @@  SYNOPSIS
 		[--exclude-standard]
 		[--error-unmatch] [--with-tree=<tree-ish>]
 		[--full-name] [--recurse-submodules]
-		[--abbrev] [--] [<file>...]
+		[--abbrev[=<n>]] [--] [<file>...]
 
 DESCRIPTION
 -----------
@@ -153,7 +153,8 @@  a space) at the start of each line:
 
 --abbrev[=<n>]::
 	Instead of showing the full 40-byte hexadecimal object
-	lines, show only a partial prefix.
+	lines, show the shortest prefix that is at least '<n>'
+	hexdigits long that uniquely refers the object.
 	Non default number of digits can be specified with --abbrev=<n>.
 
 --debug::
diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
index a7515714da..db02d6d79a 100644
--- a/Documentation/git-ls-tree.txt
+++ b/Documentation/git-ls-tree.txt
@@ -62,7 +62,8 @@  OPTIONS
 
 --abbrev[=<n>]::
 	Instead of showing the full 40-byte hexadecimal object
-	lines, show only a partial prefix.
+	lines, show the shortest prefix that is at least '<n>'
+	hexdigits long that uniquely refers the object.
 	Non default number of digits can be specified with --abbrev=<n>.
 
 --full-name::
diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt
index 17c5aac4b7..27ddaf84a1 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=<n>" (which also modifies
-	diff output, if it is displayed).
+	name, show a prefix that names the object uniquely.
+	"--abbrev=<n>" (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.