[DOC] name-rev: --annotate-stdin docs still describe SHA-1

[DOC] name-rev: --annotate-stdin docs still describe SHA-1

[jyotish kumar]

Hi,

I noticed that the documentation for `git name-rev --annotate-stdin`
still describes the input as 40-character SHA-1 hexes:

    Transform stdin by substituting all the 40-character SHA-1
    hexes (say $hex) with "$hex ($rev_name)".

The implementation of `name_rev_line()` uses the active hash
algorithm's hexadecimal size:

    const unsigned hexsz = the_hash_algo->hexsz;

and uses `hexsz` when determining the length of the hexadecimal
object ID rather than a hard-coded SHA-1 length.

This hash-size-independent parsing was introduced by commit
1c4675dc57 ("builtin/name-rev: make hash-size independent"), which
says:

    Use the_hash_algo when parsing instead of GIT_SHA1_HEXSZ so that
    this function works with any size hash.

There is also a related SHA-1-specific description under `--name-only`:

    Instead of printing both the SHA-1 and the name, print only
    the name.

Would it make sense to update these descriptions to refer to the
object ID length used by the selected hash algorithm, rather than
specifically referring to SHA-1?

If this is considered a documentation bug, I would be happy to prepare
a small patch.

Thanks,
Jyotish Kumar

Re: [DOC] name-rev: --annotate-stdin docs still describe SHA-1

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 466 bytes --]

On 2026-09-27 at 09:54:58, jyotish kumar wrote:
> Hi,

Hey,

> Would it make sense to update these descriptions to refer to the
> object ID length used by the selected hash algorithm, rather than
> specifically referring to SHA-1?
> 
> If this is considered a documentation bug, I would be happy to prepare
> a small patch.

Yes, I think this is a documentation bug and a patch would be welcome.
-- 
brian m. carlson (they/them)
Toronto, Ontario, CA

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 325 bytes --]

[PATCH] name-rev: update hash descriptions

[jyotish kumar]

The documentation for --annotate-stdin and --name-only refers to
SHA-1, although name-rev handles object IDs according to the active
hash algorithm.

Update the descriptions to refer to object IDs instead.

Signed-off-by: jyotish kumar <jyotishkumar725015@gmail.com>
---
 Documentation/git-name-rev.adoc | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-name-rev.adoc b/Documentation/git-name-rev.adoc
index d4f1c4d594..9837fe59b3 100644
--- a/Documentation/git-name-rev.adoc
+++ b/Documentation/git-name-rev.adoc
@@ -43,7 +43,7 @@ OPTIONS
 	List all commits reachable from all refs
 
 --annotate-stdin::
-	Transform stdin by substituting all the 40-character SHA-1
+	Transform stdin by substituting all the full-length object ID
 	hexes (say $hex) with "$hex ($rev_name)".  When used with
 	--name-only, substitute with "$rev_name", omitting $hex
 	altogether. This option was called `--stdin` in older versions
@@ -72,7 +72,7 @@ while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad
 -----------
 
 --name-only::
-	Instead of printing both the SHA-1 and the name, print only
+	Instead of printing both the object ID and the name, print only
 	the name.  If given with --tags the usual tag prefix of
 	"tags/" is also omitted from the name, matching the output
 	of `git-describe` more closely.
-- 
2.43.0

Re: [PATCH] name-rev: update hash descriptions

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 1680 bytes --]

On 2026-09-27 at 19:46:02, jyotish kumar wrote:
> The documentation for --annotate-stdin and --name-only refers to
> SHA-1, although name-rev handles object IDs according to the active
> hash algorithm.
> 
> Update the descriptions to refer to object IDs instead.
> 
> Signed-off-by: jyotish kumar <jyotishkumar725015@gmail.com>
> ---
>  Documentation/git-name-rev.adoc | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/git-name-rev.adoc b/Documentation/git-name-rev.adoc
> index d4f1c4d594..9837fe59b3 100644
> --- a/Documentation/git-name-rev.adoc
> +++ b/Documentation/git-name-rev.adoc
> @@ -43,7 +43,7 @@ OPTIONS
>  	List all commits reachable from all refs
>  
>  --annotate-stdin::
> -	Transform stdin by substituting all the 40-character SHA-1
> +	Transform stdin by substituting all the full-length object ID
>  	hexes (say $hex) with "$hex ($rev_name)".  When used with
>  	--name-only, substitute with "$rev_name", omitting $hex
>  	altogether. This option was called `--stdin` in older versions
> @@ -72,7 +72,7 @@ while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad
>  -----------
>  
>  --name-only::
> -	Instead of printing both the SHA-1 and the name, print only
> +	Instead of printing both the object ID and the name, print only
>  	the name.  If given with --tags the usual tag prefix of
>  	"tags/" is also omitted from the name, matching the output
>  	of `git-describe` more closely.

This looks much better.  I didn't see any other instances of "SHA-1" in
the documentation or "40", so this looks complete.
-- 
brian m. carlson (they/them)
Toronto, Ontario, CA

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 325 bytes --]

Re: [PATCH] name-rev: update hash descriptions

[Junio C Hamano]

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

>>  --name-only::
>> -	Instead of printing both the SHA-1 and the name, print only
>> +	Instead of printing both the object ID and the name, print only
>>  	the name.  If given with --tags the usual tag prefix of
>>  	"tags/" is also omitted from the name, matching the output
>>  	of `git-describe` more closely.
>
> This looks much better.  I didn't see any other instances of "SHA-1" in
> the documentation or "40", so this looks complete.

Great to know that somebody already did the grep for us so I do not
have to ;-)

"object ID" is the best one among a few synonyms to be used in the
description of "--name-only", as the "name" is about the textual
"name" name-rev mapped, and not about the "object identifier" that
was used as the input to the program.