# [PATCH] docs: add git-hash-object -t option's possible values 10 messages from 2023-06-22 to 2023-06-29. Participants: John Cai via GitGitGadget, brian m. carlson, Taylor Blau, Junio C Hamano, John Cai. Thread: https://gitlist.dev/t/59895 ## John Cai via GitGitGadget, 2023-06-22 00:46 Subject: [PATCH] docs: add git-hash-object -t option's possible values Message-ID: URL: https://gitlist.dev/e/pull.1533.git.git.1687394795009.gitgitgadget%40gmail.com ``` From: John Cai 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 --- 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(-) 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 :: - 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. base-commit: 6640c2d06d112675426cf436f0594f0e8c614848 -- gitgitgadget ``` ## brian m. carlson, 2023-06-22 00:59 Subject: Re: [PATCH] docs: add git-hash-object -t option's possible values Message-ID: URL: https://gitlist.dev/e/ZJOc3Kd0vEEO6bUr%40tapette.crustytoothpaste.net In-Reply-To: ``` On 2023-06-22 at 00:46:34, John Cai via GitGitGadget wrote: > From: John Cai > > 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. -- brian m. carlson (he/him or they/them) Toronto, Ontario, CA ``` ## Taylor Blau, 2023-06-22 12:38 Subject: Re: [PATCH] docs: add git-hash-object -t option's possible valuesync-mailbox> Message-ID: URL: https://gitlist.dev/e/ZJRAsU6LfSwFIdbw%40nand.local In-Reply-To: ``` On Thu, Jun 22, 2023 at 12:46:34AM +0000, John Cai via GitGitGadget wrote: > From: John Cai > > 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, 2023-06-22 23:04 Subject: Re: [PATCH] docs: add git-hash-object -t option's possible values Message-ID: URL: https://gitlist.dev/e/xmqqv8ffcd4w.fsf%40gitster.g In-Reply-To: ``` "brian m. carlson" writes: > On 2023-06-22 at 00:46:34, John Cai via GitGitGadget wrote: >> From: John Cai >> >> 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, 2023-06-22 23:13 Subject: Re: [PATCH] docs: add git-hash-object -t option's possible values Message-ID: URL: https://gitlist.dev/e/xmqqfs6jccqb.fsf_-_%40gitster.g In-Reply-To: ``` Taylor Blau writes: > On Thu, Jun 22, 2023 at 12:46:34AM +0000, John Cai via GitGitGadget wrote: >> From: John Cai >> >> 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, 2023-06-23 18:08 Subject: Re: [PATCH] docs: add git-hash-object -t option's possible values Message-ID: <62B7F5FF-F85D-47C0-B553-F57B991D0BCC@gmail.com> URL: https://gitlist.dev/e/62B7F5FF-F85D-47C0-B553-F57B991D0BCC%40gmail.com In-Reply-To: ``` Hi Junio, On 22 Jun 2023, at 19:13, Junio C Hamano wrote: > Taylor Blau writes: > >> On Thu, Jun 22, 2023 at 12:46:34AM +0000, John Cai via GitGitGadget wrote: >>> From: John Cai >>> >>> 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 ``` ## John Cai via GitGitGadget, 2023-06-23 21:25 Subject: [PATCH v2] docs: add git hash-object -t option's possible values Message-ID: URL: https://gitlist.dev/e/pull.1533.v2.git.git.1687555504551.gitgitgadget%40gmail.com In-Reply-To: ``` From: John Cai 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. 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 --- 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 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 ## 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 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 SYNOPSIS @@ -25,7 +25,8 @@ OPTIONS ------- -t :: - 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. base-commit: 6640c2d06d112675426cf436f0594f0e8c614848 -- gitgitgadget ``` ## Junio C Hamano, 2023-06-23 21:43 Subject: Re: [PATCH v2] docs: add git hash-object -t option's possible values Message-ID: URL: https://gitlist.dev/e/xmqq7crtam89.fsf%40gitster.g In-Reply-To: ``` "John Cai via GitGitGadget" writes: > From: John Cai > > 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 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? > 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 > > ## 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 > > > > 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". > > SYNOPSIS > @@ -25,7 +25,8 @@ OPTIONS > ------- > > -t :: > - Specify the type (default: "blob"). > + Specify the type (default: "blob"). Possible values are `commit`, > + `tree`, `blob`, and `tag`. Not a new problem, but "-t " 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. ``` ## John Cai via GitGitGadget, 2023-06-29 02:07 Subject: [PATCH v3] docs: add git hash-object -t option's possible values Message-ID: URL: https://gitlist.dev/e/pull.1533.v3.git.git.1688004473941.gitgitgadget%40gmail.com In-Reply-To: ``` From: John Cai 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 --- 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 @@ 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 :: - 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(-) 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 :: - 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. base-commit: 6640c2d06d112675426cf436f0594f0e8c614848 -- gitgitgadget ``` ## Junio C Hamano, 2023-06-29 18:15 Subject: Re: [PATCH v3] docs: add git hash-object -t option's possible values Message-ID: URL: https://gitlist.dev/e/xmqqilb69lto.fsf%40gitster.g In-Reply-To: ``` "John Cai via GitGitGadget" writes: > From: John Cai > > 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 > --- Looks good. Queued. Let's merge it down to 'next' and below. Thanks. ```