Re: [PATCH v2] docs: add git hash-object -t option's possible values

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 23, 2023, 21:43 UTC
Message-ID: <xmqq7crtam89.fsf@gitster.g>
In-Reply-To: <pull.1533.v2.git.git.1687555504551.gitgitgadget@gmail.com>

"John Cai via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: John Cai <johncai86@gmail.com>
>
> The verbiage under the NAME section for git hash-object could

Stil a verbiage?

> lead one to conclude that git hash-object can only be used to create
> blobs when in fact the description makes it clear that it can be used to
> create objects, not just blobs. Lets clarify this in the NAME text.

"Lets" -> "Let's". "Let's clarify the one-line summary." Similarly,

    The one-line summary for 'git hash-object' can mislead hasty
    readers to think that the command can only be used to ...

or something, perhaps.

Show 5 quoted lines

> Further, the description for the option -t does not list out other types
> that can be used. Let's make this explicit by listing out the different
> object types.
>
> Signed-off-by: John Cai <johncai86@gmail.com>

Nice.

Show 8 quoted lines

>     docs: add git-hash-object -t option's possible values
>     
>     For newer users of Git, the possible values of -t in git-hash-object may
>     not be apparent. In fact the current verbiage under NAME could lead one
>     to conclude that git-hash-object(1) can only be used to create blobs.
>     
>     Update the verbiage to make it clear the command can be used to write
>     objects, not just blobs. Also add the possible values for -t.

What is this older version of the proposed log message?

Show 50 quoted lines

>     Changes since v1:
>     
>      * updated verbiage of commit message
>
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1533%2Fjohn-cai%2Fjc%2Fhash-object-documentation-update-v2
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1533/john-cai/jc/hash-object-documentation-update-v2
> Pull-Request: https://github.com/git/git/pull/1533
>
> Range-diff vs v1:
>
>  1:  38515c660fb ! 1:  2483375ecb8 docs: add git-hash-object -t option's possible values
>      @@ Metadata
>       Author: John Cai <johncai86@gmail.com>
>       
>        ## Commit message ##
>      -    docs: add git-hash-object -t option's possible values
>      +    docs: add git hash-object -t option's possible values
>       
>      -    For newer users of Git, the possible values of -t in git-hash-object may
>      -    not be apparent. In fact the current verbiage under NAME could
>      -    lead one to conclude that git-hash-object(1) can only be used to create
>      -    blobs.
>      +    The verbiage under the NAME section for git hash-object could
>      +    lead one to conclude that git hash-object can only be used to create
>      +    blobs when in fact the description makes it clear that it can be used to
>      +    create objects, not just blobs. Lets clarify this in the NAME text.
>       
>      -    Update the verbiage to make it clear the command can be used to write
>      -    objects, not just blobs. Also add the possible values for -t.
>      +    Further, the description for the option -t does not list out other types
>      +    that can be used. Let's make this explicit by listing out the different
>      +    object types.
>       
>           Signed-off-by: John Cai <johncai86@gmail.com>
>       
>
>
>  Documentation/git-hash-object.txt | 5 +++--
>  1 file changed, 3 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt
> index 472b5bb995b..404e339e170 100644
> --- a/Documentation/git-hash-object.txt
> +++ b/Documentation/git-hash-object.txt
> @@ -3,7 +3,7 @@ git-hash-object(1)
>  
>  NAME
>  ----
> -git-hash-object - Compute object ID and optionally creates a blob from a file
> +git-hash-object - Compute object ID and optionally creates an object from a file

Not a new problem, but as we are updating the one-line summary, perhaps we should also do "creates" -> "create" to match "Compute".

Show 9 quoted lines

>  
>  SYNOPSIS
> @@ -25,7 +25,8 @@ OPTIONS
>  -------
>  
>  -t <type>::
> -	Specify the type (default: "blob").
> +	Specify the type (default: "blob"). Possible values are `commit`,
> +	`tree`, `blob`, and `tag`.

Not a new problem, but "-t <type>" alone is clear enough that it specifies something called "type" already. If we are to explain it further, we should at least say something about the significance of that "type" thing. Perhaps "Specify the type of the object to be created" or something?

Thanks.