On Thu, Mar 07, 2024 at 01:57:41AM -0500, Eric Sunshine wrote: > On Wed, Mar 6, 2024 at 6:32 AM Patrick Steinhardt <ps@xxxxxx> wrote: > > Update our documentation of git-config(1) to stop mentioning the old > > syntax while starting to mention the new syntax. Remove the help > > mismatch in t0450 so that we start to ensure that the manpage and > > builtin synopsis match. > > [...] > > Signed-off-by: Patrick Steinhardt <ps@xxxxxx> > > I'd like to push back on the part of this patch which completely > eradicates mention of the old syntax. Doing so makes it difficult for > people to figure out the meaning of git-config commands which they run > across in blogs and existing tooling. For instance, the following > recommendation is commonly encountered in the wild: > > git config --global user.name "Your Name" > git config --global user.email "youremail@xxxxxxxxxxxxxx" > > Typically, we instead retain the old syntax (or options or whatever) > in the documentation so that people who want to learn can learn, but > we rewrite it to make it clear that it is deprecated, and explicitly > point the reader at the modern replacement command or option (or > whatever). > > So, perhaps you can have a SYNOPSIS section for the deprecated usage, > as well as a "DEPRECATED OPTIONS" section (or such), so that we don't > leave readers entirely in the dark. Fair point indeed. I will update this patch accordingly, thanks! Patrick
Attachment:
signature.asc
Description: PGP signature
