| Message ID | 5980432179352054955e602cf97b57e97694a28c.1683566870.git.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | docs: interpret-trailers: reword and add examples | expand |
"Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes: > From: Linus Arver <linusa@google.com> > > Signed-off-by: Linus Arver <linusa@google.com> > --- > Documentation/git-interpret-trailers.txt | 9 +++++---- > 1 file changed, 5 insertions(+), 4 deletions(-) This patch has more annoying "just rewrapping the text in a strange way without changing anything" than the real change which is to enclose <value> inside the angle brackets (which is good) and adding a new sentence. We are discouraging the use of .command and recommending folks to use .cmd instead, by the way. At some point we may drop the example, and adding a reference to the example would mean somebody needs to remember removing this when it happens. > diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt > index ac448fd732e..5ca758e363f 100644 > --- a/Documentation/git-interpret-trailers.txt > +++ b/Documentation/git-interpret-trailers.txt > @@ -234,10 +234,11 @@ trailer.<token>.ifmissing:: > that option for trailers with the specified <token>. > > trailer.<token>.command:: > - This option behaves in the same way as 'trailer.<token>.cmd', except > - that it doesn't pass anything as argument to the specified command. > - Instead the first occurrence of substring $ARG is replaced by the > - value that would be passed as argument. > + This option behaves in the > + same way as 'trailer.<token>.cmd', except that it doesn't pass anything as > + argument to the specified command. Instead the first occurrence of substring > + $ARG is replaced by the <value> from the trailer. See the > + 'trailer.see.command' trailer example in the "EXAMPLES" section below. > + > The 'trailer.<token>.command' option has been deprecated in favor of > 'trailer.<token>.cmd' due to the fact that $ARG in the user's command is
Junio C Hamano <gitster@pobox.com> writes: > "Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes: >> From: Linus Arver <linusa@google.com> >> Signed-off-by: Linus Arver <linusa@google.com> >> --- >> Documentation/git-interpret-trailers.txt | 9 +++++---- >> 1 file changed, 5 insertions(+), 4 deletions(-) > This patch has more annoying "just rewrapping the text in a strange > way without changing anything" Noted. I will remove the whitespace churn in v2. > than the real change which is to > enclose <value> inside the angle brackets (which is good) and adding > a new sentence. I should probably move the angle bracket changes into 07. > We are discouraging the use of .command and recommending folks to > use .cmd instead, by the way. I was motivated to add the reference to the example because I could not understand what Instead the first occurrence of substring $ARG is replaced by the value that would be passed as argument. meant in the existing language. In hindsight maybe it's not worth adding the reference, because of the deprecation. > At some point we may drop the > example, and adding a reference to the example would mean somebody > needs to remember removing this when it happens. Wouldn't we also delete the entire `trailer.<token>.command::` section (and therefore the reference to the example) also at the same time? >> diff --git a/Documentation/git-interpret-trailers.txt >> b/Documentation/git-interpret-trailers.txt >> index ac448fd732e..5ca758e363f 100644 >> --- a/Documentation/git-interpret-trailers.txt >> +++ b/Documentation/git-interpret-trailers.txt >> @@ -234,10 +234,11 @@ trailer.<token>.ifmissing:: >> that option for trailers with the specified <token>. >> trailer.<token>.command:: >> - This option behaves in the same way as 'trailer.<token>.cmd', except >> - that it doesn't pass anything as argument to the specified command. >> - Instead the first occurrence of substring $ARG is replaced by the >> - value that would be passed as argument. >> + This option behaves in the >> + same way as 'trailer.<token>.cmd', except that it doesn't pass >> anything as >> + argument to the specified command. Instead the first occurrence of >> substring >> + $ARG is replaced by the <value> from the trailer. See the >> + 'trailer.see.command' trailer example in the "EXAMPLES" section below. >> + >> The 'trailer.<token>.command' option has been deprecated in favor of >> 'trailer.<token>.cmd' due to the fact that $ARG in the user's command is
Linus Arver <linusa@google.com> writes: >> At some point we may drop the >> example, and adding a reference to the example would mean somebody >> needs to remember removing this when it happens. > > Wouldn't we also delete the entire `trailer.<token>.command::` section > (and therefore the reference to the example) also at the same time? We could go that way. It is likely that we'd remove text that helps for those who newly use the deprecated construct while keeping what helps for those who have to read and understand the construct that was written in random scripts they find on the Internet. So removing the example can come before the section itself, though. In a far enough future, we would be without the example and the section so it would not be too big a deal, either way. Thanks.
diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt index ac448fd732e..5ca758e363f 100644 --- a/Documentation/git-interpret-trailers.txt +++ b/Documentation/git-interpret-trailers.txt @@ -234,10 +234,11 @@ trailer.<token>.ifmissing:: that option for trailers with the specified <token>. trailer.<token>.command:: - This option behaves in the same way as 'trailer.<token>.cmd', except - that it doesn't pass anything as argument to the specified command. - Instead the first occurrence of substring $ARG is replaced by the - value that would be passed as argument. + This option behaves in the + same way as 'trailer.<token>.cmd', except that it doesn't pass anything as + argument to the specified command. Instead the first occurrence of substring + $ARG is replaced by the <value> from the trailer. See the + 'trailer.see.command' trailer example in the "EXAMPLES" section below. + The 'trailer.<token>.command' option has been deprecated in favor of 'trailer.<token>.cmd' due to the fact that $ARG in the user's command is