[v3] docs: add git hash-object -t option's possible values

Commit Message

John Cai June 29, 2023, 2:07 a.m. UTC

From: John Cai <[e-mail]>

The summary under the NAME section for git hash-object can mislead
readers to conclude that the command can only be used to create blobs,
whereas the description makes it clear that it can be used to create
objects, not just blobs. Let's clarify the one-line summary.

Further, the description for the option -t does not list out other types
that can be used when creating objects. Let's make this explicit by
listing out the different object types.

Signed-off-by: John Cai <[e-mail]>
---
    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.
    
    Changes since v2:
    
     * grammatical corrections in command documentation.
     * clarify -t text by specifying what "type" is.
    
    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-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1533/john-cai/jc/hash-object-documentation-update-v3
Pull-Request: https://github.com/git/git/pull/1533

Range-diff vs v2:

 1:  2483375ecb8 ! 1:  9e0bec41285 docs: add git hash-object -t option's possible values
     @@ Metadata
       ## Commit message ##
          docs: add git hash-object -t option's possible values
      
     -    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.
     +    The summary under the NAME section for git hash-object can mislead
     +    readers to conclude that the command can only be used to create blobs,
     +    whereas the description makes it clear that it can be used to create
     +    objects, not just blobs. Let's clarify the one-line summary.
      
          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.
     +    that can be used when creating objects. Let's make this explicit by
     +    listing out the different object types.
      
          Signed-off-by: John Cai <[e-mail]>
      
     @@ Documentation/git-hash-object.txt: 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
     ++git-hash-object - Compute object ID and optionally create an object from a file
       
       
       SYNOPSIS
     @@ Documentation/git-hash-object.txt: OPTIONS
       
       -t <type>::
      -	Specify the type (default: "blob").
     -+	Specify the type (default: "blob"). Possible values are `commit`,
     -+	`tree`, `blob`, and `tag`.
     ++	Specify the type of object to be created (default: "blob"). Possible
     ++	values are `commit`, `tree`, `blob`, and `tag`.
       
       -w::
       	Actually write the object into the object database.


 Documentation/git-hash-object.txt | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)


base-commit: 6640c2d06d112675426cf436f0594f0e8c614848

Comments

Junio C Hamano June 29, 2023, 6:15 p.m. UTC | #1

"John Cai via GitGitGadget" <[e-mail]> writes:

> From: John Cai <[e-mail]>
>
> The summary under the NAME section for git hash-object can mislead
> readers to conclude that the command can only be used to create blobs,
> whereas the description makes it clear that it can be used to create
> objects, not just blobs. Let's clarify the one-line summary.
>
> Further, the description for the option -t does not list out other types
> that can be used when creating objects. Let's make this explicit by
> listing out the different object types.
>
> Signed-off-by: John Cai <[e-mail]>
> ---

Looks good.  Queued.  Let's merge it down to 'next' and below.

Thanks.

Patch

diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt
index 472b5bb995b..8577f7a7d40 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 create an object from a file
 
 
 SYNOPSIS
@@ -25,7 +25,8 @@  OPTIONS
 -------
 
 -t <type>::
-	Specify the type (default: "blob").
+	Specify the type of object to be created (default: "blob"). Possible
+	values are `commit`, `tree`, `blob`, and `tag`.
 
 -w::
 	Actually write the object into the object database.