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

Commit Message

John Cai June 22, 2023, 12:46 a.m. UTC

From: John Cai <[e-mail]>

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.

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.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1533%2Fjohn-cai%2Fjc%2Fhash-object-documentation-update-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1533/john-cai/jc/hash-object-documentation-update-v1
Pull-Request: https://github.com/git/git/pull/1533

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


base-commit: 6640c2d06d112675426cf436f0594f0e8c614848

Comments

brian m. carlson June 22, 2023, 12:59 a.m. UTC | #1

On 2023-06-22 at 00:46:34, John Cai via GitGitGadget wrote:
> From: John Cai <[e-mail]>
> 
> 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.

Sure, I think this is a good change.  I'm of the opinion we should tell
people explicitly what the valid values are whenever there are a
reasonable number.

Taylor Blau June 22, 2023, 12:38 p.m. UTC | #2

On Thu, Jun 22, 2023 at 12:46:34AM +0000, John Cai via GitGitGadget wrote:
> From: John Cai <[e-mail]>
>
> 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.

In the above, these days we would say "git hash-object" instead of
"git-hash-object" (but "git-hash-object(1)" is correct to refer to the
manual page).

Not worth a reroll on its own, of course, but something to keep in mind
for the future.

Otherwise, this patch looks good to me.

Thanks,
Taylor

Junio C Hamano June 22, 2023, 11:04 p.m. UTC | #3

"brian m. carlson" <[e-mail]> writes:

> On 2023-06-22 at 00:46:34, John Cai via GitGitGadget wrote:
>> From: John Cai <[e-mail]>
>> 
>> 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.
>
> Sure, I think this is a good change.  I'm of the opinion we should tell
> people explicitly what the valid values are whenever there are a
> reasonable number.

Strictly speaking, the valid values become unbounded under
--literally, but it is just for those who build and experiment with
Git, not for end-users or toolsmiths, so I am OK with listing the
four object types here.

Thanks.

Junio C Hamano June 22, 2023, 11:13 p.m. UTC | #4

Taylor Blau <[e-mail]> writes:

> On Thu, Jun 22, 2023 at 12:46:34AM +0000, John Cai via GitGitGadget wrote:
>> From: John Cai <[e-mail]>
>>
>> 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.

While I do not oppose to the patch text that lists four object types
explicitly, I am not sure if the above is a reasonable justification
to do so.

I think the phrase "default:" in front of explicit singling out of
"blob" in the description is sufficient to hint that "blob" is
merely one of the types it can create.  Also why do we expect that
newer users of Git would be playing with hash-object before even
learning there are other three types (or only after reading the
one-line summary without description)?  It almost smells like asking
for trouble.

Verbiage refers to uses of too many words or excessively technical
expressions.  I do not think a single-line summary of the command
qualifies for one.

So, I like the patch text, but not the way it is sold with its
proposed log message.

Thanks.

John Cai June 23, 2023, 6:08 p.m. UTC | #5

Hi Junio,

On 22 Jun 2023, at 19:13, Junio C Hamano wrote:

> Taylor Blau <[e-mail]> writes:
>
>> On Thu, Jun 22, 2023 at 12:46:34AM +0000, John Cai via GitGitGadget wrote:
>>> From: John Cai <[e-mail]>
>>>
>>> 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.
>
> While I do not oppose to the patch text that lists four object types
> explicitly, I am not sure if the above is a reasonable justification
> to do so.
>
> I think the phrase "default:" in front of explicit singling out of
> "blob" in the description is sufficient to hint that "blob" is
> merely one of the types it can create.

I think the default does indicate that there are other types, but at least for
myself it created a bit of uncertainty as to what other types the command
accepted. Of course, a quick test on the command line is sufficient to confirm
the support for commit, tree, and tag--but I still think the current verbiage
leaves enough room for ambiguity, even for users of Git who are aware of all the
object types.

> Also why do we expect thatnewer users of Git would be playing with hash-object
> before even learning there are other three types (or only after reading the
> one-line summary without description)?  It almost smells like asking for
> trouble.

I do agree with this reasoning. "newer users of Git" does not sound like the
right phrase to use.

>
> Verbiage refers to uses of too many words or excessively technical
> expressions.  I do not think a single-line summary of the command
> qualifies for one.
>
> So, I like the patch text, but not the way it is sold with its
> proposed log message.

Will re-roll with updated text. Also, based on Taylor's feedback of
git-hash-object vs git hash-object.

>
> Thanks.

thanks!
John

Patch

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
 
 
 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`.
 
 -w::
 	Actually write the object into the object database.