Re: [PATCH v2] docs: add git hash-object -t option's possible values
From: Junio C Hamano <hidden>
Date: 2023-06-23 21:43:33
"John Cai via GitGitGadget" [off-list ref] writes:
From: John Cai <redacted> 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.
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 <redacted>
Nice.
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?
quoted hunk
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 [off-list ref] ## 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 [off-list ref] 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".
quoted hunk
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.