From: Christian Couder <christian.couder@gmail.com> To: ZheNing Hu via GitGitGadget <gitgitgadget@gmail.com> Cc: git <git@vger.kernel.org>, Junio C Hamano <gitster@pobox.com>, ZheNing Hu <adlternative@gmail.com> Subject: Re: [PATCH v8 1/2] [GSOC] docs: correct descript of trailer.<token>.command Date: Fri, 9 Apr 2021 21:02:14 +0200 [thread overview] Message-ID: <CAP8UFD0q=7JT1Wsbr6wj9_LEh41ZKbvKsgnE+_3hSM3aMnjwzw@mail.gmail.com> (raw) In-Reply-To: <505903811df83cf26f4dd70c5b811dde169896a2.1617975462.git.gitgitgadget@gmail.com> On Fri, Apr 9, 2021 at 3:37 PM ZheNing Hu via GitGitGadget <gitgitgadget@gmail.com> wrote: > > From: ZheNing Hu <adlternative@gmail.com> > > 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. > Signed-off-by: ZheNing Hu <adlternative@gmail.com> > --- > 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. > 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 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!
next prev parent reply other threads:[~2021-04-09 19:02 UTC|newest] Thread overview: 101+ messages / expand[flat|nested] mbox.gz Atom feed top 2021-03-23 14:53 [PATCH] [GSOC]trailer: change $ARG to environment variable ZheNing Hu via GitGitGadget 2021-03-24 15:42 ` [PATCH v2] [GSOC]trailer: pass arg as positional parameter ZheNing Hu via GitGitGadget 2021-03-24 20:18 ` Junio C Hamano 2021-03-25 1:43 ` ZheNing Hu 2021-03-25 11:53 ` [PATCH v3] " ZheNing Hu via GitGitGadget 2021-03-25 22:28 ` Junio C Hamano 2021-03-26 13:29 ` ZheNing Hu 2021-03-26 16:13 ` [PATCH v4] " ZheNing Hu via GitGitGadget 2021-03-27 18:04 ` Junio C Hamano 2021-03-27 19:53 ` Christian Couder 2021-03-28 10:46 ` ZheNing Hu 2021-03-29 9:04 ` Christian Couder 2021-03-29 13:43 ` ZheNing Hu 2021-03-30 8:45 ` Christian Couder 2021-03-30 11:22 ` ZheNing Hu 2021-03-30 15:07 ` ZheNing Hu 2021-03-30 17:14 ` Junio C Hamano 2021-03-31 5:14 ` ZheNing Hu 2021-03-31 18:19 ` Junio C Hamano 2021-03-31 18:29 ` Junio C Hamano 2021-04-01 3:56 ` ZheNing Hu 2021-04-01 19:49 ` Junio C Hamano 2021-04-02 2:08 ` ZheNing Hu 2021-04-01 3:39 ` ZheNing Hu 2021-03-31 10:05 ` [PATCH v5 0/2] " ZheNing Hu via GitGitGadget 2021-03-31 10:05 ` [PATCH v5 1/2] [GSOC] run-command: add shell_no_implicit_args option ZheNing Hu via GitGitGadget 2021-04-01 7:22 ` Christian Couder 2021-04-01 9:58 ` ZheNing Hu 2021-03-31 10:05 ` [PATCH v5 2/2] [GSOC]trailer: pass arg as positional parameter ZheNing Hu via GitGitGadget 2021-04-01 7:28 ` [PATCH v5 0/2] " Christian Couder 2021-04-01 10:02 ` ZheNing Hu 2021-04-02 13:26 ` [PATCH v6] [GSOC] trailer: add new trailer.<token>.cmd config option ZheNing Hu via GitGitGadget 2021-04-02 20:48 ` Junio C Hamano 2021-04-03 5:08 ` ZheNing Hu 2021-04-04 5:34 ` Junio C Hamano 2021-04-03 5:51 ` Christian Couder 2021-04-04 23:26 ` Junio C Hamano 2021-04-06 3:47 ` Christian Couder 2021-04-06 3:52 ` Christian Couder 2021-04-06 5:16 ` ZheNing Hu 2021-04-06 5:34 ` Junio C Hamano 2021-04-06 5:37 ` Junio C Hamano 2021-04-04 5:43 ` ZheNing Hu 2021-04-04 8:52 ` Christian Couder 2021-04-04 9:53 ` ZheNing Hu 2021-04-02 23:44 ` Junio C Hamano 2021-04-03 3:22 ` ZheNing Hu 2021-04-03 4:31 ` Junio C Hamano 2021-04-03 5:15 ` ZheNing Hu 2021-04-04 13:11 ` [PATCH v7] " ZheNing Hu via GitGitGadget 2021-04-06 16:23 ` Christian Couder 2021-04-07 4:51 ` ZheNing Hu 2021-04-09 13:37 ` [PATCH v8 0/2] [GSOC] trailer: add new .cmd " ZheNing Hu via GitGitGadget 2021-04-09 13:37 ` [PATCH v8 1/2] [GSOC] docs: correct descript of trailer.<token>.command ZheNing Hu via GitGitGadget 2021-04-09 19:02 ` Christian Couder [this message] 2021-04-10 13:40 ` ZheNing Hu 2021-04-09 13:37 ` [PATCH v8 2/2] [GSOC] trailer: add new .cmd config option ZheNing Hu via GitGitGadget 2021-04-09 20:18 ` Christian Couder 2021-04-10 14:09 ` ZheNing Hu 2021-04-09 19:59 ` [PATCH v8 0/2] " Christian Couder 2021-04-12 16:39 ` [PATCH v9 " ZheNing Hu via GitGitGadget 2021-04-12 16:39 ` [PATCH v9 1/2] [GSOC] docs: correct descript of trailer.<token>.command ZheNing Hu via GitGitGadget 2021-04-12 20:42 ` Junio C Hamano 2021-04-16 12:03 ` Christian Couder 2021-04-17 1:54 ` Junio C Hamano 2021-04-12 16:39 ` [PATCH v9 2/2] [GSOC] trailer: add new .cmd config option ZheNing Hu via GitGitGadget 2021-04-12 20:51 ` Junio C Hamano 2021-04-13 7:33 ` Christian Couder 2021-04-13 12:02 ` ZheNing Hu 2021-04-13 19:18 ` Junio C Hamano 2021-04-14 13:27 ` ZheNing Hu 2021-04-14 20:33 ` Junio C Hamano 2021-04-15 15:32 ` ZheNing Hu 2021-04-15 17:41 ` Junio C Hamano 2021-04-16 12:54 ` Christian Couder 2021-04-13 18:14 ` Junio C Hamano 2021-04-16 8:47 ` [PATCH v10 0/2] " ZheNing Hu via GitGitGadget 2021-04-16 8:47 ` [PATCH v10 1/2] [GSOC] docs: correct descript of trailer.<token>.command ZheNing Hu via GitGitGadget 2021-04-16 19:11 ` Junio C Hamano 2021-04-16 8:47 ` [PATCH v10 2/2] [GSOC] trailer: add new .cmd config option ZheNing Hu via GitGitGadget 2021-04-16 19:13 ` Junio C Hamano 2021-04-16 19:21 ` Junio C Hamano 2021-04-16 19:25 ` Junio C Hamano 2021-04-17 2:58 ` Junio C Hamano 2021-04-17 3:36 ` Junio C Hamano 2021-04-17 7:41 ` ZheNing Hu 2021-04-17 8:11 ` Junio C Hamano 2021-04-17 15:13 ` [PATCH v11 0/2] " ZheNing Hu via GitGitGadget 2021-04-17 15:13 ` [PATCH v11 1/2] [GSOC] docs: correct description of .command ZheNing Hu via GitGitGadget 2021-04-17 15:13 ` [PATCH v11 2/2] [GSOC] trailer: add new .cmd config option ZheNing Hu via GitGitGadget 2021-04-17 22:26 ` [PATCH v11 0/2] " Junio C Hamano 2021-04-18 7:47 ` ZheNing Hu 2021-04-21 0:09 ` Junio C Hamano 2021-04-21 5:47 ` ZheNing Hu 2021-04-21 23:40 ` Junio C Hamano 2021-04-22 9:20 ` ZheNing Hu 2021-04-27 6:49 ` Junio C Hamano 2021-04-27 12:24 ` ZheNing Hu 2021-05-03 15:41 ` [PATCH v12 " ZheNing Hu via GitGitGadget 2021-05-03 15:41 ` [PATCH v12 1/2] [GSOC] docs: correct descript of trailer.<token>.command ZheNing Hu via GitGitGadget 2021-05-03 15:41 ` [PATCH v12 2/2] [GSOC] trailer: add new .cmd config option ZheNing Hu via GitGitGadget
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style List information: http://vger.kernel.org/majordomo-info.html * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to='CAP8UFD0q=7JT1Wsbr6wj9_LEh41ZKbvKsgnE+_3hSM3aMnjwzw@mail.gmail.com' \ --to=christian.couder@gmail.com \ --cc=adlternative@gmail.com \ --cc=git@vger.kernel.org \ --cc=gitgitgadget@gmail.com \ --cc=gitster@pobox.com \ --subject='Re: [PATCH v8 1/2] [GSOC] docs: correct descript of trailer.<token>.command' \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: link
Code repositories for project(s) associated with this inbox: https://80x24.org/mirrors/git.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).