git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
From: Junio C Hamano <gitster@pobox.com>
To: git@vger.kernel.org
Subject: [PATCH] doc: clarify that most --abbrev[=<n>] are about minimum length
Date: Tue, 03 Nov 2020 17:44:15 -0800	[thread overview]
Message-ID: <xmqqblgdq4k0.fsf_-_@gitster.c.googlers.com> (raw)
In-Reply-To: <xmqqk0v1q60l.fsf@gitster.c.googlers.com> (Junio C. Hamano's message of "Tue, 03 Nov 2020 17:12:42 -0800")

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".

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 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 | 3 ++-
 6 files changed, 17 insertions(+), 9 deletions(-)

diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index 573fb9bb71..d73fdb8567 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 <n> hexadecimal digits, or as many digits
+	as needed to form a unique object name.
 	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..89611c3959 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,
+	use <n>, or as many hexdigits as needed to form a unique
+	object name.
 	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..60e3063fed 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 <n>, or as many hexadecimal digits
+	as needed, to form a unique object name.
 	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..480c668d0f 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 <n>, or as many hexadecimal digits
+	as needed, to form a unique object name.
 	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..da6ab0de0c 100644
--- a/Documentation/pretty-options.txt
+++ b/Documentation/pretty-options.txt
@@ -16,7 +16,8 @@ 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).
 +
-- 
2.29.2-287-gba574db674


  reply	other threads:[~2020-11-04  1:44 UTC|newest]

Thread overview: 7+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-11-04  0:55 Bug with --abbrev option in git log? Mário Guimarães
2020-11-04  1:12 ` Junio C Hamano
2020-11-04  1:44   ` Junio C Hamano [this message]
2020-11-04 13:24     ` [PATCH] doc: clarify that most --abbrev[=<n>] are about minimum length Derrick Stolee
2020-11-04 22:01       ` [PATCH v2] doc: clarify that --abbrev=<n> is about the " Junio C Hamano
2020-11-07 15:09         ` Derrick Stolee
2020-11-04  2:11   ` Bug with --abbrev option in git log? Mário Guimarães

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=xmqqblgdq4k0.fsf_-_@gitster.c.googlers.com \
    --to=gitster@pobox.com \
    --cc=git@vger.kernel.org \
    --subject='Re: [PATCH] doc: clarify that most --abbrev[=<n>] are about minimum length' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Code repositories for project(s) associated with this inbox:

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).