threads / patch / 46061

patchdoc: Improve description for rev-parse --short

Subject: [PATCH] doc: Improve description for rev-parse --short

## tl;dr

5 messages between May 28, 2017 and May 31, 2017. Diffs are folded; open one to read it.

replies: 4people: 2as markdown or json

Andreas Heiduk· May 28, 2017, 14:33 UTC · lore
First: `git rev-parse --short` without a number does use a fixed default but
`core.abbrev` which in turn uses `find_unique_abbrev` internally.
Second: `--short` implies `--verify` since the beginning (d50125085a), so
it cannot be used for bulk-shortening ids unfortunately.
Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
---
 Documentation/config.txt        | 1 +
 Documentation/git-rev-parse.txt | 4 +++-
 2 files changed, 4 insertions(+), 1 deletion(-)
Show changes to 2 files +4 −1

Documentation/config.txt, Documentation/git-rev-parse.txt

diff --git a/Documentation/config.txt b/Documentation/config.txt
index e0b9fd0bc..158cb588b 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -862,6 +862,7 @@ core.abbrev::
 	computed based on the approximate number of packed objects
 	in your repository, which hopefully is enough for
 	abbreviated object names to stay unique for some time.
+	The minimum length is 4.
 
 add.ignoreErrors::
 add.ignore-errors (deprecated)::
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index c40c47044..7a7421c8e 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -140,7 +140,9 @@ can be used.
 --short=number::
 	Instead of outputting the full SHA-1 values of object names try to
 	abbreviate them to a shorter unique name. When no length is specified
-	7 is used. The minimum length is 4.
+	the effective value of the configuration variable `core.abbrev` (see
+	linkgit:git-config[1]) is used.  The minimum length is 4.  The length
+	may be exceeded to ensure unique object names.	Implies `--verify`.
 
 --symbolic::
 	Usually the object names are output in SHA-1 form (with

-- 
2.13.0
Junio C Hamano· May 30, 2017, 04:10 UTC · re: Andreas Heiduk · lore

Re: [PATCH] doc: Improve description for rev-parse --short

Andreas Heiduk <asheiduk@gmail.com> writes:
> First: `git rev-parse --short` without a number does use a fixed default but
> `core.abbrev` which in turn uses `find_unique_abbrev` internally.

... hence the value gives mere minumum. I like your updated text that clarifies this point.

> Second: `--short` implies `--verify` since the beginning (d50125085a), so
> it cannot be used for bulk-shortening ids unfortunately.

The fact you have to say "Nth:" hints that this is better done as two patch series. Then you can avoid saying a vague "Improve" on the subject, that leaves the "git shortlog" readers wondering what exactly you improved.

Show 30 quoted lines
> Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
> ---
>  Documentation/config.txt        | 1 +
>  Documentation/git-rev-parse.txt | 4 +++-
>  2 files changed, 4 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index e0b9fd0bc..158cb588b 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -862,6 +862,7 @@ core.abbrev::
>  	computed based on the approximate number of packed objects
>  	in your repository, which hopefully is enough for
>  	abbreviated object names to stay unique for some time.
> +	The minimum length is 4.
>  
>  add.ignoreErrors::
>  add.ignore-errors (deprecated)::
> diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
> index c40c47044..7a7421c8e 100644
> --- a/Documentation/git-rev-parse.txt
> +++ b/Documentation/git-rev-parse.txt
> @@ -140,7 +140,9 @@ can be used.
>  --short=number::
>  	Instead of outputting the full SHA-1 values of object names try to
>  	abbreviate them to a shorter unique name. When no length is specified
> -	7 is used. The minimum length is 4.
> +	the effective value of the configuration variable `core.abbrev` (see
> +	linkgit:git-config[1]) is used.  The minimum length is 4.  The length
> +	may be exceeded to ensure unique object names.	Implies `--verify`.

"Implies --verify" is less important than the fact that multiple object names cannot be given from the end-users' (and readers') point of view, no? The sentence in the pre-context still hints (incorrectly) that we might take multiple names---that would want to be corrected, no?

Let me try.
    --short[=length]::
	Take a single object name, and output a prefix of the object
	name whose length is at least the specified length and
	sufficient to ensure uniqueness of the name.  The minimum
	length is 4.  When no length is given, the effective value
	of the `core.abbrev` configuration variable is used.
Thanks.
>  
>  --symbolic::
>  	Usually the object names are output in SHA-1 form (with
Andreas Heiduk· May 30, 2017, 20:40 UTC · re: Junio C Hamano · lore

Re: [PATCH] doc: Improve description for rev-parse --short

Am 30.05.2017 um 06:10 schrieb Junio C Hamano:
Show 24 quoted lines
>>  --short=number::
>>  	Instead of outputting the full SHA-1 values of object names try to
>>  	abbreviate them to a shorter unique name. When no length is specified
>> -	7 is used. The minimum length is 4.
>> +	the effective value of the configuration variable `core.abbrev` (see
>> +	linkgit:git-config[1]) is used.  The minimum length is 4.  The length
>> +	may be exceeded to ensure unique object names.	Implies `--verify`.
> 
> "Implies --verify" is less important than the fact that multiple
> object names cannot be given from the end-users' (and readers')
> point of view, no?  The sentence in the pre-context still hints
> (incorrectly) that we might take multiple names---that would want to
> be corrected, no?
> 
> Let me try.
> 
>     --short[=length]::
> 	Take a single object name, and output a prefix of the object
> 	name whose length is at least the specified length and
> 	sufficient to ensure uniqueness of the name.  The minimum
> 	length is 4.  When no length is given, the effective value
> 	of the `core.abbrev` configuration variable is used.
> 
> Thanks.
Your are right about s/names/name/ in the pretext.

But I think that the link to the `--verify` option is still important. The text there talks about when something is output, exit codes and about `^{type}` peeling. Also `--quiet` is linked to `--verify` and hence relevant here.

So I'd like to patch your text to this:
  --short[=length]::
	Same as `--verify` but output only a prefix of the object
	name whose length is at least the specified length and
	sufficient to ensure uniqueness of the name.  The minimum
	length is 4.  When no length is given, the effective value
	of the `core.abbrev` configuration variable is used.

And I'd like to move the section up right to `--verify` and `--quiet`. The options in this section are not sorted alphabetically anyways and the relevant parts would be adjacent. Is that OK?

ALso: Did you remove the `linkgit` by intention or just by accident?
Junio C Hamano· May 30, 2017, 23:18 UTC · re: Andreas Heiduk · lore

Re: [PATCH] doc: Improve description for rev-parse --short

Andreas Heiduk <asheiduk@gmail.com> writes:
> ALso: Did you remove the `linkgit` by intention or just by accident?

By accident. I agree that "Same as `--verify`" is a good way to do this.

Andreas Heiduk· May 31, 2017, 21:39 UTC · re: Andreas Heiduk · lore

[PATCH v1] doc: rewrite description for rev-parse --short

`git rev-parse --short` is not a generic modifier but just a variant of `--verify` and considers the given length only as a suggestion to ensure uniqueness.

Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
---
 Documentation/config.txt        |  1 +
 Documentation/git-rev-parse.txt | 12 ++++++------
 2 files changed, 7 insertions(+), 6 deletions(-)
Show changes to 2 files +7 −4

Documentation/config.txt, Documentation/git-rev-parse.txt

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 43d830ee3..3256a3344 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -883,6 +883,7 @@ core.abbrev::
 	computed based on the approximate number of packed objects
 	in your repository, which hopefully is enough for
 	abbreviated object names to stay unique for some time.
+	The minimum length is 4.
 
 add.ignoreErrors::
 add.ignore-errors (deprecated)::
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index c40c47044..b1293f24b 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -126,6 +126,12 @@ can be used.
 	'git diff-{asterisk}'). In contrast to the `--sq-quote` option,
 	the command input is still interpreted as usual.
 
+--short[=length]::
+	Same as `--verify` but shortens the object name to a unique
+	prefix with at least `length` characters. The minimum length
+	is 4, the default is the effective value of the `core.abbrev`
+	configuration variable (see linkgit:git-config[1]).
+
 --not::
 	When showing object names, prefix them with '{caret}' and
 	strip '{caret}' prefix from the object names that already have
@@ -136,12 +142,6 @@ can be used.
 	The option core.warnAmbiguousRefs is used to select the strict
 	abbreviation mode.
 
---short::
---short=number::
-	Instead of outputting the full SHA-1 values of object names try to
-	abbreviate them to a shorter unique name. When no length is specified
-	7 is used. The minimum length is 4.
-
 --symbolic::
 	Usually the object names are output in SHA-1 form (with
 	possible '{caret}' prefix); this option makes them output in a

-- 
2.13.0

← back to recent threads