From: Junio C Hamano Date: Wed, 20 Sep 2023 15:01:28 GMT Subject: Re: [PATCH v3 13/13] trailer doc: is a or , not both Message-ID: In-Reply-To: <20230919225926.2189091-1-jonathantanmy@google.com> Jonathan Tan writes: > "Linus Arver via GitGitGadget" writes: >> @@ -248,34 +258,40 @@ With `add`, a new trailer will be added. >> + >> With `doNothing`, nothing will be done. >> >> -trailer..key:: >> - This `key` will be used instead of in the trailer. At >> - the end of this key, a separator can appear and then some >> - space characters. By default the only valid separator is ':', >> - but this can be changed using the `trailer.separators` config >> - variable. >> +trailer..key:: >> + Defines a for the . The must be a >> + prefix (case does not matter) of the . For example, in `git >> + config trailer.ack.key "Acked-by"` the "Acked-by" is the and >> + the "ack" is the . This configuration allows the shorter >> + `--trailer "ack:..."` invocation on the command line using the "ack" >> + instead of the longer `--trailer "Acked-by:..."`. >> ++ >> +At the end of the , a separator can appear and then some >> +space characters. By default the only valid separator is ':', >> +but this can be changed using the `trailer.separators` config >> +variable. > > I think all the other patches will be a great help to the user, but I'm > on the fence about this one. Someone who knows these trailer components > by their old names might be confused upon seeing tne new ones, so I'm > inclined to minimize such changes. I do think that the new names make > more sense, though. As long as the new names describe the world order better than the old description, I do not mind rephrasing the documentation, and you seem to find the more descriptive easier to understand compared to the non-descriptive . Adding a concrete example (ack vs acked-by) is also a good change.