From: Junio C Hamano <gitster@pobox.com>
To: "John Cai via GitGitGadget" <gitgitgadget@gmail.com>
Cc: git@vger.kernel.org,
"brian m. carlson" <sandals@crustytoothpaste.net>,
Taylor Blau <me@ttaylorr.com>, John Cai <johncai86@gmail.com>
Subject: Re: [PATCH v2] docs: add git hash-object -t option's possible values
Date: Fri, 23 Jun 2023 14:43:18 -0700 [thread overview]
Message-ID: <xmqq7crtam89.fsf@gitster.g> (raw)
In-Reply-To: <pull.1533.v2.git.git.1687555504551.gitgitgadget@gmail.com> (John Cai via GitGitGadget's message of "Fri, 23 Jun 2023 21:25:04 +0000")
"John Cai via GitGitGadget" <gitgitgadget@gmail.com> writes:
> From: John Cai <johncai86@gmail.com>
>
> 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 <johncai86@gmail.com>
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 <johncai86@gmail.com>
>
> ## 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 <johncai86@gmail.com>
>
>
>
> 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 <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.
next prev parent reply other threads:[~2023-06-23 21:43 UTC|newest]
Thread overview: 10+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-06-22 0:46 [PATCH] docs: add git-hash-object -t option's possible values John Cai via GitGitGadget
2023-06-22 0:59 ` brian m. carlson
2023-06-22 23:04 ` Junio C Hamano
2023-06-22 12:38 ` [PATCH] docs: add git-hash-object -t option's possible valuesync-mailbox> Taylor Blau
2023-06-22 23:13 ` [PATCH] docs: add git-hash-object -t option's possible values Junio C Hamano
2023-06-23 18:08 ` John Cai
2023-06-23 21:25 ` [PATCH v2] docs: add git hash-object " John Cai via GitGitGadget
2023-06-23 21:43 ` Junio C Hamano [this message]
2023-06-29 2:07 ` [PATCH v3] " John Cai via GitGitGadget
2023-06-29 18:15 ` Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=xmqq7crtam89.fsf@gitster.g \
--to=gitster@pobox.com \
--cc=git@vger.kernel.org \
--cc=gitgitgadget@gmail.com \
--cc=johncai86@gmail.com \
--cc=me@ttaylorr.com \
--cc=sandals@crustytoothpaste.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).