Christian Couder <christian.couder@xxxxxxxxx> 于2021年4月10日周六 上午3:02写道： > > On Fri, Apr 9, 2021 at 3:37 PM ZheNing Hu via GitGitGadget > <gitgitgadget@xxxxxxxxx> wrote: > > > > From: ZheNing Hu <adlternative@xxxxxxxxx> > > > > In the original documentation of `trailer.<token>.command`, > > some descriptions are easily misunderstood. So let's modify > > it to increase its readability. > > > > In addition, clarify that `$ARG` in command can only be > > replaced once since `$ARG` is text replacement. > > I think you can remove the "since `$ARG` is text replacement" part. > Otherwise this looks fine. > Ok. > > Signed-off-by: ZheNing Hu <adlternative@xxxxxxxxx> > > --- > > Documentation/git-interpret-trailers.txt | 22 +++++++++++----------- > > 1 file changed, 11 insertions(+), 11 deletions(-) > > > > diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt > > index 96ec6499f001..3e5aa3a65ae9 100644 > > --- a/Documentation/git-interpret-trailers.txt > > +++ b/Documentation/git-interpret-trailers.txt > > @@ -237,20 +237,20 @@ trailer.<token>.command:: > > specified <token>. > > The beginning of the doc for trailer.<token>.command could already be > improved. It is: > > This option can be used to specify a shell command that will > be called to automatically add or modify a trailer with the > specified <token>. > > Instead we could say for example: > > This option can be used to specify a shell command that will > be called: > - once to automatically add a trailer with the specified > <token>, and then > - each time a '--trailer <token>=<value>' argument to modify > the <value> of the trailer that this option would produce > > > When this option is specified, the behavior is as if a special > > I would rather say: > > When the specified command is first called to add a trailer with the > specified <token>, the behavior is as if a special > > > -'<token>=<value>' argument were added at the beginning of the command > > -line, where <value> is taken to be the standard output of the > > -specified command with any leading and trailing whitespace trimmed > > -off. > > +'--trailer <token>=<value>' argument was added at the beginning of > > +the "git interpret-trailers" command, where <value> is taken to be the > > +standard output of the specified command with any leading and trailing > > Here we can remove "specified" as we now use it at the beginning of > the sentence. > > > +whitespace trimmed off. > > + > > -If the command contains the `$ARG` string, this string will be > > -replaced with the <value> part of an existing trailer with the same > > -<token>, if any, before the command is launched. > > +The first occurrence of substring `$ARG` will be replaced with the > > +<value> part of an existing trailer with the same <token>, if any, > > +before the command is launched. > > I think we should not talk about `$ARG` at this point, let's remove > this and see what we can do below in the next paragraph or after it. > Here I may want to keep the content similar to the original paragraph. But if you say so, it will be fine. > > If some '<token>=<value>' arguments are also passed on the command > > s/'<token>=<value>'/'--trailer <token>=<value>'/ > > > -line, when a 'trailer.<token>.command' is configured, the command will > > -also be executed for each of these arguments. And the <value> part of > > -these arguments, if any, will be used to replace the `$ARG` string in > > -the command. > > +line, when a 'trailer.<token>.command' is configured, the command is run > > s/when a 'trailer.<token>.command' is configured, // > s/the command is run/the command is called again/ > > > +once for each these arguments with the same <token>. > > s/each these/each of these/ > > > And the <value> > > +part of these arguments, if any, will be used to replace the first `$ARG` > > +string in the command. > > s/first `$ARG` string/first occurrence of substring `$ARG`/ > > Let's also add something to explain the purpose of this, for example > we could add: > > "This way the command can produce a <value> computed from the <value> > passed in the '--trailer <token>=<value>' argument." > > And then let's also explain what happens when the command is called > the first time, with for example: > > "For consistency, the first occurrence of substring `$ARG` is also > replaced, this time with the empty string, in the command when the > command is first called to add a trailer with the specified <token>." > > To sum up this would give the following (not properly formatted) description: > > ------------------- > trailer.<token>.command:: > This option can be used to specify a shell command that will be called: > - once to automatically add a trailer with the specified > <token>, and then > - each time a '--trailer <token>=<value>' argument to modify > the <value> of the trailer that this option would produce > Maybe I am a little confused: this two "-" meaning? Shouldn't it be the same paragraph? - This option can be used to specify a shell command that will - be called to automatically add or modify a trailer with the - specified <token>. + This option can be used to specify a shell command that will be called: + - once to automatically add a trailer with the specified <token>, and then + - each time a '--trailer <token>=<value>' argument to modify the <value> of + the trailer that this option would produce. Wouldn't it be weird? > When the specified command is first called to add a trailer > with the specified <token>, the behavior is as if a special > '--trailer <token>=<value>' argument was added at the beginning > of the "git interpret-trailers" command, where <value> > is taken to be the standard output of the command with any > leading and trailing whitespace trimmed off. > > If some '--trailer <token>=<value>' arguments are also passed > on the command > line, the command is called again once for each of these > arguments with the same <token>. > And the <value> part of these arguments, if any, will be used > to replace the first occurrence > of substring `$ARG` in the command. This way the command can > produce a <value> > computed from the <value> passed in the '--trailer > <token>=<value>' argument. > > For consistency, the first occurrence of substring `$ARG` is > also replaced, this time with the > empty string, in the command when the command is first called > to add a trailer with the > specified <token>. > ------------------- > > Thanks! Thanks a lot! It looks more professional than what I wrote. -- ZheNing Hu
