doc: Improve description for rev-parse --short
PATCH 1/1 doc: Improve description for rev-parse --short
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.
--- Documentation/config.txt | 1 + Documentation/git-rev-parse.txt | 4 +++- 2 files changed, 4 insertions(+), 1 deletion(-)
Documentation/config.txt +1 -0
@@ -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)::
Documentation/git-rev-parse.txt +3 -1
@@ -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
Signature · 1 line
2.13.0
Quoted 2 lines · Andreas Heiduk
First:
git rev-parse --shortwithout a number does use a fixed default butcore.abbrevwhich in turn usesfind_unique_abbrevinternally.
... hence the value gives mere minumum. I like your updated text that clarifies this point.
Quoted 2 lines
Second:
--shortimplies--verifysince 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.
Quoted 23 lines
Signed-off-by Andreas Heiduk <[email protected]>--- Documentation/config.txt | 1 + Documentation/git-rev-parse.txt | 4 +++- 2 files changed, 4 insertions(+), 1 deletion(-)Documentation/config.txt +1
-0@@ -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)::Documentation/git-rev-parse.txt +0
-0
Documentation/git-rev-parse.txt can be used. · line 145
Quoted 7 lines
Documentation/git-rev-parse.txt +3
-1@@ -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.
Quoted 3 lines
Documentation/git-rev-parse.txt +0
-0--symbolic:: Usually the object names are output in SHA-1 form (with
Am 30.05.2017 um 06:10 schrieb Junio C Hamano:
Quoted 16 lines
Documentation/git-rev-parse.txt can be used. · line 145
Quoted 7 lines
--short=number::
Documentation/git-rev-parse.txt +3
-1Instead 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.
Quoted 8 lines
--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 thecore.abbrevconfiguration 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?
Quoted 1 line · Andreas Heiduk
ALso: Did you remove the
linkgitby intention or just by accident?
By accident. I agree that "Same as --verify" is a good way to do this.
PATCH 1/1 doc: rewrite description for rev-parse --short
In reply to Andreas Heidukgit 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.
--- Documentation/config.txt | 1 + Documentation/git-rev-parse.txt | 12 ++++++------ 2 files changed, 7 insertions(+), 6 deletions(-)
Documentation/config.txt +1 -0
@@ -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)::
Documentation/git-rev-parse.txt +6 -6
@@ -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
Signature · 1 line
2.13.0