* [PATCH] diff-options.txt: correct command syntax @ 2020-02-02 19:22 Adam Dinwoodie 2020-02-02 19:45 ` Martin Ågren 0 siblings, 1 reply; 7+ messages in thread From: Adam Dinwoodie @ 2020-02-02 19:22 UTC (permalink / raw) To: git; +Cc: Ramkumar Ramachandra, Phil Hord, Junio C Hamano Change the example arguments in the description of the -G diff argument to be consistent throughout the description. Signed-off-by: Adam Dinwoodie <adam@dinwoodie.org> --- Documentation/diff-options.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 09faee3b44..84a74cb2da 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -561,19 +561,19 @@ Binary files are searched as well. -G<regex>:: Look for differences whose patch text contains added/removed lines that match <regex>. + To illustrate the difference between `-S<regex> --pickaxe-regex` and `-G<regex>`, consider a commit with the following diff in the same file: + ---- + return !regexec(regexp, two->ptr, 1, ®match, 0); ... - hit = !regexec(regexp, mf2.ptr, 1, ®match, 0); ---- + -While `git log -G"regexec\(regexp"` will show this commit, `git log --S"regexec\(regexp" --pickaxe-regex` will not (because the number of +While `git log -G<regex>` will show this commit, `git log +-S<regex> --pickaxe-regex` will not (because the number of occurrences of that string did not change). + Unless `--text` is supplied patches of binary files without a textconv -- 2.25.0 ^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: [PATCH] diff-options.txt: correct command syntax 2020-02-02 19:22 [PATCH] diff-options.txt: correct command syntax Adam Dinwoodie @ 2020-02-02 19:45 ` Martin Ågren 2020-02-02 20:47 ` Adam Dinwoodie 0 siblings, 1 reply; 7+ messages in thread From: Martin Ågren @ 2020-02-02 19:45 UTC (permalink / raw) To: Adam Dinwoodie Cc: Git Mailing List, Ramkumar Ramachandra, Phil Hord, Junio C Hamano Hi Adam, On Sun, 2 Feb 2020 at 20:24, Adam Dinwoodie <adam@dinwoodie.org> wrote: > > Change the example arguments in the description of the -G diff argument > to be consistent throughout the description. > > Signed-off-by: Adam Dinwoodie <adam@dinwoodie.org> > --- > Documentation/diff-options.txt | 4 ++-- > 1 file changed, 2 insertions(+), 2 deletions(-) > > diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt > index 09faee3b44..84a74cb2da 100644 > --- a/Documentation/diff-options.txt > +++ b/Documentation/diff-options.txt > @@ -561,19 +561,19 @@ Binary files are searched as well. > -G<regex>:: > Look for differences whose patch text contains added/removed > lines that match <regex>. > + > To illustrate the difference between `-S<regex> --pickaxe-regex` and > `-G<regex>`, consider a commit with the following diff in the same > file: > + > ---- > + return !regexec(regexp, two->ptr, 1, ®match, 0); > ... > - hit = !regexec(regexp, mf2.ptr, 1, ®match, 0); > ---- > + > -While `git log -G"regexec\(regexp"` will show this commit, `git log > --S"regexec\(regexp" --pickaxe-regex` will not (because the number of > +While `git log -G<regex>` will show this commit, `git log > +-S<regex> --pickaxe-regex` will not (because the number of > occurrences of that string did not change). I don't think this is correct. "<regex>" is a placeholder and this example wants to use a real-world regex instead of the placeholder. Maybe this could be made clearer by having an example that does not try to grep in regex-code using the regex "regexec\(regexp". Maybe instead of "regexec", "regexp" and "regmatch", this example could use words from some other domain? Would something like this be clearer? To illustrate the difference between `-S<regex> --pickaxe-regex` and `-G<regex>`, consider a commit with the following diff in the same file: + ---- + return !frotz(nitfol, two->ptr, 1, 0); ... - hit = !frotz(nitfol, mf2.ptr, 1, 0); ---- + While `git log -G"frotz\(nitfol"` will show this commit, `git log -S"frotz\(nitfol" --pickaxe-regex` will not (because the number of occurrences of that string did not change). BTW, I wonder what "in the same file" tries to say -- my hunch is we could drop those words without any loss of correctness or readability. Would you agree? Martin ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH] diff-options.txt: correct command syntax 2020-02-02 19:45 ` Martin Ågren @ 2020-02-02 20:47 ` Adam Dinwoodie 2020-02-03 6:24 ` Martin Ågren 2020-02-06 20:53 ` [PATCH] diff-options.txt: avoid "regex" overload in example Martin Ågren 0 siblings, 2 replies; 7+ messages in thread From: Adam Dinwoodie @ 2020-02-02 20:47 UTC (permalink / raw) To: Martin Ågren Cc: Git Mailing List, Ramkumar Ramachandra, Phil Hord, Junio C Hamano On Sunday 02 February 2020 at 08:45 pm +0100, Martin Ågren wrote: > Hi Adam, > > On Sun, 2 Feb 2020 at 20:24, Adam Dinwoodie <adam@dinwoodie.org> wrote: > > > > Change the example arguments in the description of the -G diff argument > > to be consistent throughout the description. > > > > Signed-off-by: Adam Dinwoodie <adam@dinwoodie.org> > > --- > > Documentation/diff-options.txt | 4 ++-- > > 1 file changed, 2 insertions(+), 2 deletions(-) > > > > diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt > > index 09faee3b44..84a74cb2da 100644 > > --- a/Documentation/diff-options.txt > > +++ b/Documentation/diff-options.txt > > @@ -561,19 +561,19 @@ Binary files are searched as well. > > -G<regex>:: > > Look for differences whose patch text contains added/removed > > lines that match <regex>. > > + > > To illustrate the difference between `-S<regex> --pickaxe-regex` and > > `-G<regex>`, consider a commit with the following diff in the same > > file: > > + > > ---- > > + return !regexec(regexp, two->ptr, 1, ®match, 0); > > ... > > - hit = !regexec(regexp, mf2.ptr, 1, ®match, 0); > > ---- > > + > > -While `git log -G"regexec\(regexp"` will show this commit, `git log > > --S"regexec\(regexp" --pickaxe-regex` will not (because the number of > > +While `git log -G<regex>` will show this commit, `git log > > +-S<regex> --pickaxe-regex` will not (because the number of > > occurrences of that string did not change). > > I don't think this is correct. "<regex>" is a placeholder and this > example wants to use a real-world regex instead of the placeholder. > Maybe this could be made clearer by having an example that does not try > to grep in regex-code using the regex "regexec\(regexp". > > Maybe instead of "regexec", "regexp" and "regmatch", this example could > use words from some other domain? Would something like this be clearer? > > To illustrate the difference between `-S<regex> --pickaxe-regex` and > `-G<regex>`, consider a commit with the following diff in the same > file: > + > ---- > + return !frotz(nitfol, two->ptr, 1, 0); > ... > - hit = !frotz(nitfol, mf2.ptr, 1, 0); > ---- > + > While `git log -G"frotz\(nitfol"` will show this commit, `git log > -S"frotz\(nitfol" --pickaxe-regex` will not (because the number of > occurrences of that string did not change). Ah, thank you! I had completely misread what these examples were trying to achieve. I think your example (or indeed anything from a different domain) would have avoided me getting confused in the first place. Although I'm much less fussed now I realise the problem here was entirely my understanding rather than an error in the docs. > BTW, I wonder what "in the same file" tries to say -- my hunch is we > could drop those words without any loss of correctness or readability. > Would you agree? I think "in the same file" is meaningful here: as I understand it both forms would find a commit that removed a line from one file and added it back to a _different_ file, but only the -G form would pick it when removed and added lines are in the same file. Adam ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH] diff-options.txt: correct command syntax 2020-02-02 20:47 ` Adam Dinwoodie @ 2020-02-03 6:24 ` Martin Ågren 2020-02-06 20:53 ` [PATCH] diff-options.txt: avoid "regex" overload in example Martin Ågren 1 sibling, 0 replies; 7+ messages in thread From: Martin Ågren @ 2020-02-03 6:24 UTC (permalink / raw) To: Adam Dinwoodie Cc: Git Mailing List, Ramkumar Ramachandra, Phil Hord, Junio C Hamano On Sun, 2 Feb 2020 at 21:47, Adam Dinwoodie <adam@dinwoodie.org> wrote: > On Sunday 02 February 2020 at 08:45 pm +0100, Martin Ågren wrote: > > On Sun, 2 Feb 2020 at 20:24, Adam Dinwoodie <adam@dinwoodie.org> wrote: > > Ah, thank you! I had completely misread what these examples were trying > to achieve. I think your example (or indeed anything from a different > domain) would have avoided me getting confused in the first place. > Although I'm much less fussed now I realise the problem here was > entirely my understanding rather than an error in the docs. > > > BTW, I wonder what "in the same file" tries to say -- my hunch is we > > could drop those words without any loss of correctness or readability. > > Would you agree? > > I think "in the same file" is meaningful here: as I understand it both > forms would find a commit that removed a line from one file and added it > back to a _different_ file, but only the -G form would pick it when > removed and added lines are in the same file. You're right, it is needed. At least the way the example is given now, where there's some arbitrary amount of left-out context between the "+" and the "-" line, it's necessary to limit that by saying that it's in the same file. Because this is an example, we're allowed to make it as concrete as we see fit. For example: To illustrate the difference between `-S<regex> --pickaxe-regex` and `-G<regex>`, consider a commit with the following diff: + ---- - hit = !frotz(nitfol, mf2.ptr, 1, 0); + return !frotz(nitfol, two->ptr, 1, 0); ---- + While `git log -G"frotz\(nitfol"` will show this commit, `git log -S"frotz\(nitfol" --pickaxe-regex` will not (because the number of occurrences of that string did not change). Or does that make it too specific, i.e., could this give readers the wrong impression that -G and/or -S and/or the difference explained here only apply to such "trivial" cases? Martin ^ permalink raw reply [flat|nested] 7+ messages in thread
* [PATCH] diff-options.txt: avoid "regex" overload in example 2020-02-02 20:47 ` Adam Dinwoodie 2020-02-03 6:24 ` Martin Ågren @ 2020-02-06 20:53 ` Martin Ågren 2020-02-08 23:24 ` Taylor Blau 1 sibling, 1 reply; 7+ messages in thread From: Martin Ågren @ 2020-02-06 20:53 UTC (permalink / raw) To: git; +Cc: Adam Dinwoodie When we exemplify the difference between `-G` and `-S` (using `--pickaxe-regex`), we do so using an example diff and git-diff invocation involving "regexec", "regexp", "regmatch", ... The example is correct, but we can make it easier to untangle by avoiding writing "regex.*" unless it's really needed to make our point. Use some made-up, non-regexy words instead. Reported-by: Adam Dinwoodie <adam@dinwoodie.org> Signed-off-by: Martin Ågren <martin.agren@gmail.com> --- Documentation/diff-options.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 09faee3b44..bb31f0c42b 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -567,13 +567,13 @@ To illustrate the difference between `-S<regex> --pickaxe-regex` and file: + ---- -+ return !regexec(regexp, two->ptr, 1, ®match, 0); ++ return frotz(nitfol, two->ptr, 1, 0); ... -- hit = !regexec(regexp, mf2.ptr, 1, ®match, 0); +- hit = frotz(nitfol, mf2.ptr, 1, 0); ---- + -While `git log -G"regexec\(regexp"` will show this commit, `git log --S"regexec\(regexp" --pickaxe-regex` will not (because the number of +While `git log -G"frotz\(nitfol"` will show this commit, `git log +-S"frotz\(nitfol" --pickaxe-regex` will not (because the number of occurrences of that string did not change). + Unless `--text` is supplied patches of binary files without a textconv -- 2.25.0 ^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: [PATCH] diff-options.txt: avoid "regex" overload in example 2020-02-06 20:53 ` [PATCH] diff-options.txt: avoid "regex" overload in example Martin Ågren @ 2020-02-08 23:24 ` Taylor Blau 2020-02-09 17:25 ` Junio C Hamano 0 siblings, 1 reply; 7+ messages in thread From: Taylor Blau @ 2020-02-08 23:24 UTC (permalink / raw) To: Martin Ågren; +Cc: git, Adam Dinwoodie Hi Martin, On Thu, Feb 06, 2020 at 09:53:01PM +0100, Martin Ågren wrote: > When we exemplify the difference between `-G` and `-S` (using > `--pickaxe-regex`), we do so using an example diff and git-diff > invocation involving "regexec", "regexp", "regmatch", ... > > The example is correct, but we can make it easier to untangle by > avoiding writing "regex.*" unless it's really needed to make our point. > > Use some made-up, non-regexy words instead. This is a good idea, and I think that it removes additional, unnecessary confusion from the documentation here. > Reported-by: Adam Dinwoodie <adam@dinwoodie.org> > Signed-off-by: Martin Ågren <martin.agren@gmail.com> > --- > Documentation/diff-options.txt | 8 ++++---- > 1 file changed, 4 insertions(+), 4 deletions(-) > > diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt > index 09faee3b44..bb31f0c42b 100644 > --- a/Documentation/diff-options.txt > +++ b/Documentation/diff-options.txt > @@ -567,13 +567,13 @@ To illustrate the difference between `-S<regex> --pickaxe-regex` and > file: > + > ---- > -+ return !regexec(regexp, two->ptr, 1, ®match, 0); > ++ return frotz(nitfol, two->ptr, 1, 0); > ... > -- hit = !regexec(regexp, mf2.ptr, 1, ®match, 0); > +- hit = frotz(nitfol, mf2.ptr, 1, 0); > ---- > + > -While `git log -G"regexec\(regexp"` will show this commit, `git log > --S"regexec\(regexp" --pickaxe-regex` will not (because the number of > +While `git log -G"frotz\(nitfol"` will show this commit, `git log > +-S"frotz\(nitfol" --pickaxe-regex` will not (because the number of > occurrences of that string did not change). > + > Unless `--text` is supplied patches of binary files without a textconv > -- > 2.25.0 Thanks for doing it. Reviewed-by: Taylor Blau <me@ttaylorr.com> Thanks, Taylor ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH] diff-options.txt: avoid "regex" overload in example 2020-02-08 23:24 ` Taylor Blau @ 2020-02-09 17:25 ` Junio C Hamano 0 siblings, 0 replies; 7+ messages in thread From: Junio C Hamano @ 2020-02-09 17:25 UTC (permalink / raw) To: Taylor Blau; +Cc: Martin Ågren, git, Adam Dinwoodie Taylor Blau <me@ttaylorr.com> writes: > This is a good idea, and I think that it removes additional, unnecessary > confusion from the documentation here. > > Reviewed-by: Taylor Blau <me@ttaylorr.com> Thanks, both. ^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2020-02-09 17:26 UTC | newest] Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2020-02-02 19:22 [PATCH] diff-options.txt: correct command syntax Adam Dinwoodie 2020-02-02 19:45 ` Martin Ågren 2020-02-02 20:47 ` Adam Dinwoodie 2020-02-03 6:24 ` Martin Ågren 2020-02-06 20:53 ` [PATCH] diff-options.txt: avoid "regex" overload in example Martin Ågren 2020-02-08 23:24 ` Taylor Blau 2020-02-09 17:25 ` Junio C Hamano
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.