Hi Junio, On 22 Jun 2023, at 19:13, Junio C Hamano wrote: > Taylor Blau <me@xxxxxxxxxxxx> writes: > >> On Thu, Jun 22, 2023 at 12:46:34AM +0000, John Cai via GitGitGadget wrote: >>> From: John Cai <johncai86@xxxxxxxxx> >>> >>> 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
