Jonathan Tan <jonathantanmy@xxxxxxxxxx> writes: > "Linus Arver via GitGitGadget" <gitgitgadget@xxxxxxxxx> writes: >> @@ -248,34 +258,40 @@ With `add`, a new trailer will be added. >> + >> With `doNothing`, nothing will be done. >> >> -trailer.<token>.key:: >> - This `key` will be used instead of <token> 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.<keyAlias>.key:: >> + Defines a <keyAlias> for the <key>. The <keyAlias> must be a >> + prefix (case does not matter) of the <key>. For example, in `git >> + config trailer.ack.key "Acked-by"` the "Acked-by" is the <key> and >> + the "ack" is the <keyAlias>. This configuration allows the shorter >> + `--trailer "ack:..."` invocation on the command line using the "ack" >> + <keyAlias> instead of the longer `--trailer "Acked-by:..."`. >> ++ >> +At the end of the <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. > > 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 <keyAlias> easier to understand compared to the non-descriptive <token>. Adding a concrete example (ack vs acked-by) is also a good change.
