docs: add git-hash-object -t option's possible values
PATCH 1/1 docs: add git-hash-object -t option's possible values
From: John Cai <[email protected]>
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.
---
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(-)
Documentation/git-hash-object.txt +3 -2
@@ -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.
base-commit: 6640c2d06d112675426cf436f0594f0e8c614848
Signature · 1 line
gitgitgadget
Quoted 9 lines · John Cai via GitGitGadget
From: John Cai <[email protected]>
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.
Signature · 2 lines
brian m. carlson (he/him or they/them) Toronto, Ontario, CA
Quoted 8 lines · brian m. carlson
Quoted 7 lines · John Cai via GitGitGadget
From: John Cai <[email protected]>
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.
Quoted 6 lines
Quoted 2 lines
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.
Re: [PATCH] docs: add git-hash-object -t option's possible valuesync-mailbox>
In reply to John Cai via GitGitGadgetQuoted 6 lines · John Cai via GitGitGadget
From: John Cai <[email protected]>
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
Quoted 7 lines · Taylor Blau
Quoted 6 lines · John Cai via GitGitGadget
From: John Cai <[email protected]>
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.
Hi Junio,
Quoted 10 lines · Junio C Hamano
Quoted 7 lines · Taylor Blau
Quoted 6 lines · John Cai via GitGitGadget
From: John Cai <[email protected]>
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.
Quoted 7 lines
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.
Quoted 4 lines
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.
Quoted 7 lines
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.
Quoted 2 lines
Thanks.
thanks!
John
PATCH v2 1/1 docs: add git hash-object -t option's possible values
In reply to John Cai via GitGitGadgetFrom: John Cai <[email protected]>
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.
---
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 <[email protected]>
## 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.
Documentation/git-hash-object.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-)
Documentation/git-hash-object.txt +3 -2
@@ -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.
base-commit: 6640c2d06d112675426cf436f0594f0e8c614848
Signature · 1 line
gitgitgadget
Re: [PATCH v2] docs: add git hash-object -t option's possible values
Quoted 3 lines · John Cai via GitGitGadget
From: John Cai <[email protected]>
The verbiage under the NAME section for git hash-object could
Stil a verbiage?
Quoted 3 lines
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.
Quoted 5 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 <[email protected]>
Nice.
Quoted 8 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?
Quoted 45 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/1533Range-diff vs v1:
1:
38515c660fb! 1:2483375ecb8docs: add git-hash-object -t option's possible values
@@ Metadata
Author: John Cai <[email protected]>## 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 <[email protected]>Documentation/git-hash-object.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-)Documentation/git-hash-object.txt +0
-0
Documentation/git-hash-object.txt git-hash-object(1) · line 6
Quoted 5 lines
Documentation/git-hash-object.txt +1
-1@@ -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".
Documentation/git-hash-object.txt OPTIONS · line 29
Quoted 9 lines
Documentation/git-hash-object.txt +2
-1SYNOPSIS@@ -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.
PATCH v3 1/1 docs: add git hash-object -t option's possible values
In reply to John Cai via GitGitGadgetFrom: John Cai <[email protected]>
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.
---
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.
@@ 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(-)
Documentation/git-hash-object.txt +3 -2
@@ -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.
base-commit: 6640c2d06d112675426cf436f0594f0e8c614848
Signature · 1 line
gitgitgadget
Re: [PATCH v3] docs: add git hash-object -t option's possible values
Quoted 7 lines · John Cai via GitGitGadget
From: John Cai <[email protected]>
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.
Quoted 6 lines
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 <[email protected]>---
Looks good. Queued. Let's merge it down to 'next' and below.
Thanks.