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

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 22, 2023, 23:13 UTC
Message-ID: <xmqqfs6jccqb.fsf_-_@gitster.g>
In-Reply-To: <ZJRAsU6LfSwFIdbw@nand.local>

Taylor Blau <me@ttaylorr.com> writes:

Show 7 quoted lines

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