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>

diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index 573fb9bb71e2b7df1062258289a0af308c50bf5b..706c69bc8267ba3dda85b10a60e56798bbd6863f 100644 (file)
--- 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 7e81541996359cf4b7a4abce35e8cae5c2ce29fb..34b496d4858134fb5c5e91bbd1537cd3ae076ccf 100644 (file)
--- 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 ace4ad3da8874d7c38173f4badbc51b6a1b7fec5..adaa1782a8b26d4c5fb498ff3a1d33abb8e6ac19 100644 (file)
--- 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 3cb2ebb4380e28e8e4b4e1bb5e3f4ae511960b7a..cbcf5263dd01b88537563a97bd1977bf52c3b88c 100644 (file)
--- 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 a7515714da1aaa77dddf31272f2fb62a174ba95b..db02d6d79a9c2e092f6c0755300eb2a4579887c0 100644 (file)
--- 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 17c5aac4b71d5af126a0bd85d3ffef2e94468e3c..27ddaf84a195f46edc7b3f102eb1caf1adf68765 100644 (file)
--- 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.