Re: [PATCH 2/3] Improve description of SHA1 related topics in glossary-content.txt

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 2, 2013, 16:05 UTC
Message-ID: <7v38v8hqa4.fsf@alter.siamese.dyndns.org>
In-Reply-To: <638015718.727691.1364894866964.JavaMail.ngmail@webmail14.arcor-online.net>

Thomas Ackermann <th.acker@arcor.de> writes:

Show 15 quoted lines

> Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
> ---
>  Documentation/glossary-content.txt | 12 ++++++------
>  1 file changed, 6 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
> index ab02238..05bfebc 100644
> --- a/Documentation/glossary-content.txt
> +++ b/Documentation/glossary-content.txt
> @@ -146,7 +146,7 @@ to point at the new commit.
>  	created. Configured via the `.git/info/grafts` file.
>  
>  [[def_hash]]hash::
> -	In Git's context, synonym to <<def_object_name,object name>>.
> +	In Git's context, synonym for <<def_object_name,object name>>.

OK.

Show 8 quoted lines

>  [[def_object_name]]object name::
> -	The unique identifier of an <<def_object,object>>. The <<def_hash,hash>>
> -	of the object's contents using the Secure Hash Algorithm
> -	1 and usually represented by the 40 character hexadecimal encoding of
> -	the <<def_hash,hash>> of the object.
> +	The unique identifier of an <<def_object,object>>: The <<def_SHA1,SHA1>> hash
> +	of the object's contents. The object name is usually represented by the 
> +	40 character hexadecimal encoding of the hash value.

I am torn on this one. When you have a file A on the filesystem, the object name of the blob that records the contents of that file is *not* the same as output from "sha1sum A".

I doubt we should spell out _how_ it is computed. In the glossary, it is better to say what it is and what it is used for; the tutorial and Documentation/technical/ give better details that the readers who refer to the glossary do not need.

	The unique identifier of an <<def_object,object>>.  The
	object name is usually represented by a 40 character
	hexadecimal string.  Also colloquially called
	<<def_SHA1,SHA-1>>.

might be sufficient.

Show 7 quoted lines

> @@ -426,7 +425,8 @@ should not be combined with other pathspec.
>  	Source code management (tool).
>  
>  [[def_SHA1]]SHA1::
> -	Synonym for <<def_object_name,object name>>.
> +	"Secure Hash Algorithm 1"; a cryptographic hash function. 
> +	In the context of Git used as a synonym for <<def_object_name,object name>>.

We should spell it as "SHA-1" with a dash.