Re: [PATCH] docs: add git-hash-object -t option's possible values

From: John Cai <johncai86@gmail.com>
Date: Jun 23, 2023, 18:08 UTC
Message-ID: <62B7F5FF-F85D-47C0-B553-F57B991D0BCC@gmail.com>
In-Reply-To: <xmqqfs6jccqb.fsf_-_@gitster.g>

Hi Junio,

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

Show 17 quoted lines

> Taylor Blau <me@ttaylorr.com> writes:
>
>> On Thu, Jun 22, 2023 at 12:46:34AM +0000, John Cai via GitGitGadget wrote:
>>> From: John Cai <johncai86@gmail.com>
>>>
>>> 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.

Show 7 quoted 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.

>
> Thanks.

thanks! John