{"thread":{"id":"52737","subject":"[PATCH] diff-options.txt: correct command syntax","startedAt":"2020-02-02T19:22:39Z","lastAt":"2020-02-09T17:26:04Z","messageCount":7,"participants":["Adam Dinwoodie","Martin Ågren","Taylor Blau","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"391007","messageId":"20200202192226.29176-1-adam@dinwoodie.org","threadId":"52737","inReplyTo":null,"subject":"[PATCH] diff-options.txt: correct command syntax","fromName":"Adam Dinwoodie","fromEmail":"adam@dinwoodie.org","sentAt":"2020-02-02T19:22:26Z","receivedAt":"2020-02-02T19:22:39Z","isPatch":true,"sender":{"key":"adam@dinwoodie.org","avatar":"https://avatars.githubusercontent.com/u/1397507?v=4"},"body":"Change the example arguments in the description of the -G diff argument\nto be consistent throughout the description.\n\nSigned-off-by: Adam Dinwoodie <adam@dinwoodie.org>\n---\n Documentation/diff-options.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex 09faee3b44..84a74cb2da 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -561,19 +561,19 @@ Binary files are searched as well.\n -G<regex>::\n \tLook for differences whose patch text contains added/removed\n \tlines that match <regex>.\n +\n To illustrate the difference between `-S<regex> --pickaxe-regex` and\n `-G<regex>`, consider a commit with the following diff in the same\n file:\n +\n ----\n +    return !regexec(regexp, two->ptr, 1, &regmatch, 0);\n ...\n -    hit = !regexec(regexp, mf2.ptr, 1, &regmatch, 0);\n ----\n +\n-While `git log -G\"regexec\\(regexp\"` will show this commit, `git log\n--S\"regexec\\(regexp\" --pickaxe-regex` will not (because the number of\n+While `git log -G<regex>` will show this commit, `git log\n+-S<regex> --pickaxe-regex` will not (because the number of\n occurrences of that string did not change).\n +\n Unless `--text` is supplied patches of binary files without a textconv\n-- \n2.25.0\n\n"},{"id":"391009","messageId":"CAN0heSoxgsNDbi_tbxEoSSaGOxoJYArqYa-cLu1sPWVvH6wkFg@mail.gmail.com","threadId":"52737","inReplyTo":"20200202192226.29176-1-adam@dinwoodie.org","subject":"Re: [PATCH] diff-options.txt: correct command syntax","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2020-02-02T19:45:41Z","receivedAt":"2020-02-02T19:45:54Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"Hi Adam,\n\nOn Sun, 2 Feb 2020 at 20:24, Adam Dinwoodie <adam@dinwoodie.org> wrote:\n>\n> Change the example arguments in the description of the -G diff argument\n> to be consistent throughout the description.\n>\n> Signed-off-by: Adam Dinwoodie <adam@dinwoodie.org>\n> ---\n>  Documentation/diff-options.txt | 4 ++--\n>  1 file changed, 2 insertions(+), 2 deletions(-)\n>\n> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\n> index 09faee3b44..84a74cb2da 100644\n> --- a/Documentation/diff-options.txt\n> +++ b/Documentation/diff-options.txt\n> @@ -561,19 +561,19 @@ Binary files are searched as well.\n>  -G<regex>::\n>         Look for differences whose patch text contains added/removed\n>         lines that match <regex>.\n>  +\n>  To illustrate the difference between `-S<regex> --pickaxe-regex` and\n>  `-G<regex>`, consider a commit with the following diff in the same\n>  file:\n>  +\n>  ----\n>  +    return !regexec(regexp, two->ptr, 1, &regmatch, 0);\n>  ...\n>  -    hit = !regexec(regexp, mf2.ptr, 1, &regmatch, 0);\n>  ----\n>  +\n> -While `git log -G\"regexec\\(regexp\"` will show this commit, `git log\n> --S\"regexec\\(regexp\" --pickaxe-regex` will not (because the number of\n> +While `git log -G<regex>` will show this commit, `git log\n> +-S<regex> --pickaxe-regex` will not (because the number of\n>  occurrences of that string did not change).\n\nI don't think this is correct. \"<regex>\" is a placeholder and this\nexample wants to use a real-world regex instead of the placeholder.\nMaybe this could be made clearer by having an example that does not try\nto grep in regex-code using the regex \"regexec\\(regexp\".\n\nMaybe instead of \"regexec\", \"regexp\" and \"regmatch\", this example could\nuse words from some other domain? Would something like this be clearer?\n\n To illustrate the difference between `-S<regex> --pickaxe-regex` and\n `-G<regex>`, consider a commit with the following diff in the same\n file:\n +\n ----\n +    return !frotz(nitfol, two->ptr, 1, 0);\n ...\n -    hit = !frotz(nitfol, mf2.ptr, 1, 0);\n ----\n +\n While `git log -G\"frotz\\(nitfol\"` will show this commit, `git log\n -S\"frotz\\(nitfol\" --pickaxe-regex` will not (because the number of\n occurrences of that string did not change).\n\nBTW, I wonder what \"in the same file\" tries to say -- my hunch is we\ncould drop those words without any loss of correctness or readability.\nWould you agree?\n\nMartin\n"},{"id":"391010","messageId":"20200202204739.GA24686@dinwoodie.org","threadId":"52737","inReplyTo":"CAN0heSoxgsNDbi_tbxEoSSaGOxoJYArqYa-cLu1sPWVvH6wkFg@mail.gmail.com","subject":"Re: [PATCH] diff-options.txt: correct command syntax","fromName":"Adam Dinwoodie","fromEmail":"adam@dinwoodie.org","sentAt":"2020-02-02T20:47:39Z","receivedAt":"2020-02-02T20:47:50Z","isPatch":true,"sender":{"key":"adam@dinwoodie.org","avatar":"https://avatars.githubusercontent.com/u/1397507?v=4"},"body":"On Sunday 02 February 2020 at 08:45 pm +0100, Martin Ågren wrote:\n> Hi Adam,\n> \n> On Sun, 2 Feb 2020 at 20:24, Adam Dinwoodie <adam@dinwoodie.org> wrote:\n> >\n> > Change the example arguments in the description of the -G diff argument\n> > to be consistent throughout the description.\n> >\n> > Signed-off-by: Adam Dinwoodie <adam@dinwoodie.org>\n> > ---\n> >  Documentation/diff-options.txt | 4 ++--\n> >  1 file changed, 2 insertions(+), 2 deletions(-)\n> >\n> > diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\n> > index 09faee3b44..84a74cb2da 100644\n> > --- a/Documentation/diff-options.txt\n> > +++ b/Documentation/diff-options.txt\n> > @@ -561,19 +561,19 @@ Binary files are searched as well.\n> >  -G<regex>::\n> >         Look for differences whose patch text contains added/removed\n> >         lines that match <regex>.\n> >  +\n> >  To illustrate the difference between `-S<regex> --pickaxe-regex` and\n> >  `-G<regex>`, consider a commit with the following diff in the same\n> >  file:\n> >  +\n> >  ----\n> >  +    return !regexec(regexp, two->ptr, 1, &regmatch, 0);\n> >  ...\n> >  -    hit = !regexec(regexp, mf2.ptr, 1, &regmatch, 0);\n> >  ----\n> >  +\n> > -While `git log -G\"regexec\\(regexp\"` will show this commit, `git log\n> > --S\"regexec\\(regexp\" --pickaxe-regex` will not (because the number of\n> > +While `git log -G<regex>` will show this commit, `git log\n> > +-S<regex> --pickaxe-regex` will not (because the number of\n> >  occurrences of that string did not change).\n> \n> I don't think this is correct. \"<regex>\" is a placeholder and this\n> example wants to use a real-world regex instead of the placeholder.\n> Maybe this could be made clearer by having an example that does not try\n> to grep in regex-code using the regex \"regexec\\(regexp\".\n> \n> Maybe instead of \"regexec\", \"regexp\" and \"regmatch\", this example could\n> use words from some other domain? Would something like this be clearer?\n> \n>  To illustrate the difference between `-S<regex> --pickaxe-regex` and\n>  `-G<regex>`, consider a commit with the following diff in the same\n>  file:\n>  +\n>  ----\n>  +    return !frotz(nitfol, two->ptr, 1, 0);\n>  ...\n>  -    hit = !frotz(nitfol, mf2.ptr, 1, 0);\n>  ----\n>  +\n>  While `git log -G\"frotz\\(nitfol\"` will show this commit, `git log\n>  -S\"frotz\\(nitfol\" --pickaxe-regex` will not (because the number of\n>  occurrences of that string did not change).\n\nAh, thank you!  I had completely misread what these examples were trying\nto achieve.  I think your example (or indeed anything from a different\ndomain) would have avoided me getting confused in the first place.\nAlthough I'm much less fussed now I realise the problem here was\nentirely my understanding rather than an error in the docs.\n\n> BTW, I wonder what \"in the same file\" tries to say -- my hunch is we\n> could drop those words without any loss of correctness or readability.\n> Would you agree?\n\nI think \"in the same file\" is meaningful here: as I understand it both\nforms would find a commit that removed a line from one file and added it\nback to a _different_ file, but only the -G form would pick it when\nremoved and added lines are in the same file.\n\nAdam\n"},{"id":"391023","messageId":"CAN0heSpDV2N2L4ukgdWxWJYJC1Hg9KYYkMC9MrqMGkuiv34AmQ@mail.gmail.com","threadId":"52737","inReplyTo":"20200202204739.GA24686@dinwoodie.org","subject":"Re: [PATCH] diff-options.txt: correct command syntax","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2020-02-03T06:24:00Z","receivedAt":"2020-02-03T06:24:15Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Sun, 2 Feb 2020 at 21:47, Adam Dinwoodie <adam@dinwoodie.org> wrote:\n> On Sunday 02 February 2020 at 08:45 pm +0100, Martin Ågren wrote:\n> > On Sun, 2 Feb 2020 at 20:24, Adam Dinwoodie <adam@dinwoodie.org> wrote:\n>\n> Ah, thank you!  I had completely misread what these examples were trying\n> to achieve.  I think your example (or indeed anything from a different\n> domain) would have avoided me getting confused in the first place.\n> Although I'm much less fussed now I realise the problem here was\n> entirely my understanding rather than an error in the docs.\n>\n> > BTW, I wonder what \"in the same file\" tries to say -- my hunch is we\n> > could drop those words without any loss of correctness or readability.\n> > Would you agree?\n>\n> I think \"in the same file\" is meaningful here: as I understand it both\n> forms would find a commit that removed a line from one file and added it\n> back to a _different_ file, but only the -G form would pick it when\n> removed and added lines are in the same file.\n\nYou're right, it is needed. At least the way the example is given now,\nwhere there's some arbitrary amount of left-out context between the \"+\"\nand the \"-\" line, it's necessary to limit that by saying that it's in\nthe same file. Because this is an example, we're allowed to make it as\nconcrete as we see fit. For example:\n\n To illustrate the difference between `-S<regex> --pickaxe-regex` and\n `-G<regex>`, consider a commit with the following diff:\n +\n ----\n -    hit = !frotz(nitfol, mf2.ptr, 1, 0);\n +    return !frotz(nitfol, two->ptr, 1, 0);\n ----\n +\n While `git log -G\"frotz\\(nitfol\"` will show this commit, `git log\n -S\"frotz\\(nitfol\" --pickaxe-regex` will not (because the number of\n occurrences of that string did not change).\n\nOr does that make it too specific, i.e., could this give readers the\nwrong impression that -G and/or -S and/or the difference explained here\nonly apply to such \"trivial\" cases?\n\nMartin\n"},{"id":"391272","messageId":"20200206205301.27367-1-martin.agren@gmail.com","threadId":"52737","inReplyTo":"20200202204739.GA24686@dinwoodie.org","subject":"[PATCH] diff-options.txt: avoid \"regex\" overload in example","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2020-02-06T20:53:01Z","receivedAt":"2020-02-06T20:53:29Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"When we exemplify the difference between `-G` and `-S` (using\n`--pickaxe-regex`), we do so using an example diff and git-diff\ninvocation involving \"regexec\", \"regexp\", \"regmatch\", ...\n\nThe example is correct, but we can make it easier to untangle by\navoiding writing \"regex.*\" unless it's really needed to make our point.\n\nUse some made-up, non-regexy words instead.\n\nReported-by: Adam Dinwoodie <adam@dinwoodie.org>\nSigned-off-by: Martin Ågren <martin.agren@gmail.com>\n---\n Documentation/diff-options.txt | 8 ++++----\n 1 file changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex 09faee3b44..bb31f0c42b 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -567,13 +567,13 @@ To illustrate the difference between `-S<regex> --pickaxe-regex` and\n file:\n +\n ----\n-+    return !regexec(regexp, two->ptr, 1, &regmatch, 0);\n++    return frotz(nitfol, two->ptr, 1, 0);\n ...\n--    hit = !regexec(regexp, mf2.ptr, 1, &regmatch, 0);\n+-    hit = frotz(nitfol, mf2.ptr, 1, 0);\n ----\n +\n-While `git log -G\"regexec\\(regexp\"` will show this commit, `git log\n--S\"regexec\\(regexp\" --pickaxe-regex` will not (because the number of\n+While `git log -G\"frotz\\(nitfol\"` will show this commit, `git log\n+-S\"frotz\\(nitfol\" --pickaxe-regex` will not (because the number of\n occurrences of that string did not change).\n +\n Unless `--text` is supplied patches of binary files without a textconv\n-- \n2.25.0\n\n"},{"id":"391382","messageId":"20200208232405.GC33529@syl.local","threadId":"52737","inReplyTo":"20200206205301.27367-1-martin.agren@gmail.com","subject":"Re: [PATCH] diff-options.txt: avoid \"regex\" overload in example","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2020-02-08T23:24:05Z","receivedAt":"2020-02-08T23:26:14Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"Hi Martin,\n\nOn Thu, Feb 06, 2020 at 09:53:01PM +0100, Martin Ågren wrote:\n> When we exemplify the difference between `-G` and `-S` (using\n> `--pickaxe-regex`), we do so using an example diff and git-diff\n> invocation involving \"regexec\", \"regexp\", \"regmatch\", ...\n>\n> The example is correct, but we can make it easier to untangle by\n> avoiding writing \"regex.*\" unless it's really needed to make our point.\n>\n> Use some made-up, non-regexy words instead.\n\nThis is a good idea, and I think that it removes additional, unnecessary\nconfusion from the documentation here.\n\n> Reported-by: Adam Dinwoodie <adam@dinwoodie.org>\n> Signed-off-by: Martin Ågren <martin.agren@gmail.com>\n> ---\n>  Documentation/diff-options.txt | 8 ++++----\n>  1 file changed, 4 insertions(+), 4 deletions(-)\n>\n> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\n> index 09faee3b44..bb31f0c42b 100644\n> --- a/Documentation/diff-options.txt\n> +++ b/Documentation/diff-options.txt\n> @@ -567,13 +567,13 @@ To illustrate the difference between `-S<regex> --pickaxe-regex` and\n>  file:\n>  +\n>  ----\n> -+    return !regexec(regexp, two->ptr, 1, &regmatch, 0);\n> ++    return frotz(nitfol, two->ptr, 1, 0);\n>  ...\n> --    hit = !regexec(regexp, mf2.ptr, 1, &regmatch, 0);\n> +-    hit = frotz(nitfol, mf2.ptr, 1, 0);\n>  ----\n>  +\n> -While `git log -G\"regexec\\(regexp\"` will show this commit, `git log\n> --S\"regexec\\(regexp\" --pickaxe-regex` will not (because the number of\n> +While `git log -G\"frotz\\(nitfol\"` will show this commit, `git log\n> +-S\"frotz\\(nitfol\" --pickaxe-regex` will not (because the number of\n>  occurrences of that string did not change).\n>  +\n>  Unless `--text` is supplied patches of binary files without a textconv\n> --\n> 2.25.0\n\nThanks for doing it.\n\n  Reviewed-by: Taylor Blau <me@ttaylorr.com>\n\nThanks,\nTaylor\n"},{"id":"391407","messageId":"xmqq5zgf3c60.fsf@gitster-ct.c.googlers.com","threadId":"52737","inReplyTo":"20200208232405.GC33529@syl.local","subject":"Re: [PATCH] diff-options.txt: avoid \"regex\" overload in example","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-02-09T17:25:59Z","receivedAt":"2020-02-09T17:26:04Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Taylor Blau <me@ttaylorr.com> writes:\n\n> This is a good idea, and I think that it removes additional, unnecessary\n> confusion from the documentation here.\n>\n>   Reviewed-by: Taylor Blau <me@ttaylorr.com>\n\nThanks, both.\n"}]}