{"thread":{"id":"34001","subject":"[PATCH v4 0/2] Improve diffcore-pickaxe documentation","startedAt":"2013-05-31T12:12:13Z","lastAt":"2013-06-03T17:54:43Z","messageCount":5,"participants":["Ramkumar Ramachandra","Junio C Hamano"],"isPatch":true,"patchVersion":4,"patchTotal":2},"messages":[{"id":"219098","messageId":"1370002335-6596-1-git-send-email-artagnon@gmail.com","threadId":"34001","inReplyTo":null,"subject":"[PATCH v4 0/2] Improve diffcore-pickaxe documentation","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-05-31T12:12:13Z","receivedAt":"2013-05-31T12:12:13Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Junio had some suggestions in the previous round. The inter-diff\nfollows.\n\nYeah, word-diff is a bit messy. Which brings me to: is it possible to\nturn on word-diff only where heuristically appropriate? word-diff\napplied on the rewrite of the first paragraph of gitdiffcore.txt is a\ndisaster, but okay everywhere else.\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex efb5dfe..a85288f 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -387,11 +387,11 @@ ifndef::git-format-patch[]\n\tthe specified string (i.e. addition/deletion) in a file.\n\tIntended for the scripter's use.\n+\nIt is[-especially-] useful when you're looking for an exact block of code (like a\nstruct), and want to know the history of that block since it first\ncame into being: use the feature iteratively to feed the interesting\nblock in the preimage back into `-S`, and keep going until you get the\nvery first version of the block.\n\n-G::\n\tLook for differences whose patch text contains added/removed\ndiff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt\nindex ef4c04a..c8b3e51 100644\n--- a/Documentation/gitdiffcore.txt\n+++ b/Documentation/gitdiffcore.txt\n@@ -222,25 +222,27 @@ version prefixed with '+'.\ndiffcore-pickaxe: For Detecting Addition/Deletion of Specified String\n---------------------------------------------------------------------\n\n[-There are two kinds of pickaxe:-]{+This transformation limits+} the [-S kind (corresponding-]{+set of filepairs+} to [-'git log-]\n[--S')-]{+those that change+}\n{+specified strings between the preimage+} and the [-G kind (mnemonic: grep; corresponding-]{+postimage in a certain+}\n{+way. -S and -G options are used+} to\n[-'git log -G').-]{+specify different ways these strings are sought.+}\n\n\"-S\" detects filepairs whose preimage and postimage\nhave different number of occurrences of the specified block of text.\nBy definition, it will not detect in-file moves. Also, when a\nchangeset moves a file wholesale without affecting the interesting\nstring, [-rename detection-]{+diffcore-rename+} kicks in as usual, and `-S` omits the filepair\n(since the number of occurrences of that string didn't change in that\nrename-detected filepair).[-The implementation essentially-]\n[-runs a count, and is significantly cheaper than the G kind.-] When used with `--pickaxe-regex`, treat\nthe as an extended POSIX regular expression to match,\ninstead of a literal string.\n\n\"-G\" {+(mnemonic: grep)+} detects filepairs whose\ntextual diff has an added or a deleted line that matches the given\nregular expression. This means that it [-can-]{+will+} detect in-file (or what\nrename-detection considers the same file) [-moves.-]{+moves, which is noise.+} The\nimplementation runs diff twice and greps, and this can be quite\nexpensive.\n\nWhen `-S` or `-G` are used without `--pickaxe-all`, only filepairs\nthat match their respective criterion are kept in the output. When\n\n\nRamkumar Ramachandra (2):\n diffcore-pickaxe: make error messages more consistent\n diffcore-pickaxe doc: document -S and -G properly\n\n Documentation/diff-options.txt | 38 +++++++++++++++++++++++++++--------\n Documentation/gitdiffcore.txt | 45 +++++++++++++++++++++++++-----------------\n diffcore-pickaxe.c | 4 ++--\n 3 files changed, 59 insertions(+), 28 deletions(-)\n\n-- \n1.8.3.114.gcd03571\n"},{"id":"219100","messageId":"1370002335-6596-2-git-send-email-artagnon@gmail.com","threadId":"34001","inReplyTo":"1370002335-6596-1-git-send-email-artagnon@gmail.com","subject":"[PATCH 1/2] diffcore-pickaxe: make error messages more consistent","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-05-31T12:12:14Z","receivedAt":"2013-05-31T12:12:14Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Currently, diffcore-pickaxe reports two distinct errors for the same\nuser error:\n\n $ git log --pickaxe-regex -S'\\1'\n fatal: invalid pickaxe regex: Invalid back reference\n\n $ git log -G'\\1' # --pickaxe-regex is implied\n fatal: invalid log-grep regex: Invalid back reference\n\nSince the error has nothing to do with \"log-grep\", change the -G and -S\nerror messages to say \"invalid regex\".\n\nSigned-off-by: Ramkumar Ramachandra \n---\n diffcore-pickaxe.c | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/diffcore-pickaxe.c b/diffcore-pickaxe.c\nindex 63722f8..c97ac9b 100644\n--- a/diffcore-pickaxe.c\n+++ b/diffcore-pickaxe.c\n@@ -122,7 +122,7 @@ static void diffcore_pickaxe_grep(struct diff_options *o)\n \t\tchar errbuf[1024];\n \t\tregerror(err, ®ex, errbuf, 1024);\n \t\tregfree(®ex);\n-\t\tdie(\"invalid log-grep regex: %s\", errbuf);\n+\t\tdie(\"invalid regex: %s\", errbuf);\n \t}\n \n \tpickaxe(&diff_queued_diff, o, ®ex, NULL, diff_grep);\n@@ -246,7 +246,7 @@ static void diffcore_pickaxe_count(struct diff_options *o)\n \t\t\tchar errbuf[1024];\n \t\t\tregerror(err, ®ex, errbuf, 1024);\n \t\t\tregfree(®ex);\n-\t\t\tdie(\"invalid pickaxe regex: %s\", errbuf);\n+\t\t\tdie(\"invalid regex: %s\", errbuf);\n \t\t}\n \t\tregexp = ®ex;\n \t} else {\n-- \n1.8.3.114.gcd03571\n"},{"id":"219099","messageId":"1370002335-6596-3-git-send-email-artagnon@gmail.com","threadId":"34001","inReplyTo":"1370002335-6596-1-git-send-email-artagnon@gmail.com","subject":"[PATCH 2/2] diffcore-pickaxe doc: document -S and -G properly","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-05-31T12:12:15Z","receivedAt":"2013-05-31T12:12:15Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"The documentation of -S and -G is very sketchy. Completely rewrite the\nsections in Documentation/diff-options.txt and\nDocumentation/gitdiffcore.txt.\n\nReferences:\n52e9578 ([PATCH] Introducing software archaeologist's tool \"pickaxe\".)\nf506b8e (git log/diff: add -G that greps in the patch text)\n\nInputs-from: Phil Hord \nCo-authored-by: Junio C Hamano \nSigned-off-by: Ramkumar Ramachandra \n---\n Documentation/diff-options.txt | 38 +++++++++++++++++++++++++++--------\n Documentation/gitdiffcore.txt | 45 +++++++++++++++++++++++++-----------------\n 2 files changed, 57 insertions(+), 26 deletions(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex b8a9b86..a85288f 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -383,14 +383,36 @@ ifndef::git-format-patch[]\n \tthat matches other criteria, nothing is selected.\n \n -S::\n-\tLook for differences that introduce or remove an instance of\n-\t. Note that this is different than the string simply\n-\tappearing in diff output; see the 'pickaxe' entry in\n-\tlinkgit:gitdiffcore[7] for more details.\n+\tLook for differences that change the number of occurrences of\n+\tthe specified string (i.e. addition/deletion) in a file.\n+\tIntended for the scripter's use.\n++\n+It is useful when you're looking for an exact block of code (like a\n+struct), and want to know the history of that block since it first\n+came into being: use the feature iteratively to feed the interesting\n+block in the preimage back into `-S`, and keep going until you get the\n+very first version of the block.\n \n -G::\n-\tLook for differences whose added or removed line matches\n-\tthe given .\n+\tLook for differences whose patch text contains added/removed\n+\tlines that match .\n++\n+To illustrate the difference between `-S --pickaxe-regex` and\n+`-G`, consider a commit with the following diff in the same\n+file:\n++\n+----\n++ return !regexec(regexp, two->ptr, 1, ®match, 0);\n+...\n+- hit = !regexec(regexp, mf2.ptr, 1, ®match, 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+occurrences of that string did not change).\n++\n+See the 'pickaxe' entry in linkgit:gitdiffcore[7] for more\n+information.\n \n --pickaxe-all::\n \tWhen `-S` or `-G` finds a change, show all the changes in that\n@@ -398,8 +420,8 @@ ifndef::git-format-patch[]\n \tin .\n \n --pickaxe-regex::\n-\tMake the not a plain string but an extended POSIX\n-\tregex to match.\n+\tTreat the given to `-S` as an extended POSIX regular\n+\texpression to match.\n endif::git-format-patch[]\n \n -O::\ndiff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt\nindex 568d757..c8b3e51 100644\n--- a/Documentation/gitdiffcore.txt\n+++ b/Documentation/gitdiffcore.txt\n@@ -222,26 +222,35 @@ version prefixed with '+'.\n diffcore-pickaxe: For Detecting Addition/Deletion of Specified String\n ---------------------------------------------------------------------\n \n-This transformation is used to find filepairs that represent\n-changes that touch a specified string, and is controlled by the\n--S option and the `--pickaxe-all` option to the 'git diff-*'\n-commands.\n-\n-When diffcore-pickaxe is in use, it checks if there are\n-filepairs whose \"result\" side and whose \"origin\" side have\n-different number of specified string. Such a filepair represents\n-\"the string appeared in this changeset\". It also checks for the\n-opposite case that loses the specified string.\n-\n-When `--pickaxe-all` is not in effect, diffcore-pickaxe leaves\n-only such filepairs that touch the specified string in its\n-output. When `--pickaxe-all` is used, diffcore-pickaxe leaves all\n-filepairs intact if there is such a filepair, or makes the\n-output empty otherwise. The latter behaviour is designed to\n-make reviewing of the changes in the context of the whole\n+This transformation limits the set of filepairs to those that change\n+specified strings between the preimage and the postimage in a certain\n+way. -S and -G options are used to\n+specify different ways these strings are sought.\n+\n+\"-S\" detects filepairs whose preimage and postimage\n+have different number of occurrences of the specified block of text.\n+By definition, it will not detect in-file moves. Also, when a\n+changeset moves a file wholesale without affecting the interesting\n+string, diffcore-rename kicks in as usual, and `-S` omits the filepair\n+(since the number of occurrences of that string didn't change in that\n+rename-detected filepair). When used with `--pickaxe-regex`, treat\n+the as an extended POSIX regular expression to match,\n+instead of a literal string.\n+\n+\"-G\" (mnemonic: grep) detects filepairs whose\n+textual diff has an added or a deleted line that matches the given\n+regular expression. This means that it will detect in-file (or what\n+rename-detection considers the same file) moves, which is noise. The\n+implementation runs diff twice and greps, and this can be quite\n+expensive.\n+\n+When `-S` or `-G` are used without `--pickaxe-all`, only filepairs\n+that match their respective criterion are kept in the output. When\n+`--pickaxe-all` is used, if even one filepair matches their respective\n+criterion in a changeset, the entire changeset is kept. This behavior\n+is designed to make reviewing changes in the context of the whole\n changeset easier.\n \n-\n diffcore-order: For Sorting the Output Based on Filenames\n ---------------------------------------------------------\n \n-- \n1.8.3.114.gcd03571\n"},{"id":"219259","messageId":"7vwqqbf5fh.fsf@alter.siamese.dyndns.org","threadId":"34001","inReplyTo":"1370002335-6596-2-git-send-email-artagnon@gmail.com","subject":"Re: [PATCH 1/2] diffcore-pickaxe: make error messages more consistent","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-06-03T17:52:02Z","receivedAt":"2013-06-03T17:52:02Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ramkumar Ramachandra writes:\n\n> Currently, diffcore-pickaxe reports two distinct errors for the same\n> user error:\n>\n> $ git log --pickaxe-regex -S'\\1'\n> fatal: invalid pickaxe regex: Invalid back reference\n>\n> $ git log -G'\\1' # --pickaxe-regex is implied\n> fatal: invalid log-grep regex: Invalid back reference\n>\n> Since the error has nothing to do with \"log-grep\", change the -G and -S\n> error messages to say \"invalid regex\".\n\nI'll reword the above somewhat; as I repeatedly explained, -G does\n*not* imply pickaxe-regex at all.\n\nWhile -G was being developed, it was internally called log-grep (no\nrelation to \"git log --grep=\"), and that seeped through to\nthe error message. Removing that is a good idea.\n\nThanks, will queue.\n\n\n\n>\n> Signed-off-by: Ramkumar Ramachandra \n> ---\n> diffcore-pickaxe.c | 4 ++--\n> 1 file changed, 2 insertions(+), 2 deletions(-)\n>\n> diff --git a/diffcore-pickaxe.c b/diffcore-pickaxe.c\n> index 63722f8..c97ac9b 100644\n> --- a/diffcore-pickaxe.c\n> +++ b/diffcore-pickaxe.c\n> @@ -122,7 +122,7 @@ static void diffcore_pickaxe_grep(struct diff_options *o)\n> \t\tchar errbuf[1024];\n> \t\tregerror(err, ®ex, errbuf, 1024);\n> \t\tregfree(®ex);\n> -\t\tdie(\"invalid log-grep regex: %s\", errbuf);\n> +\t\tdie(\"invalid regex: %s\", errbuf);\n> \t}\n> \n> \tpickaxe(&diff_queued_diff, o, ®ex, NULL, diff_grep);\n> @@ -246,7 +246,7 @@ static void diffcore_pickaxe_count(struct diff_options *o)\n> \t\t\tchar errbuf[1024];\n> \t\t\tregerror(err, ®ex, errbuf, 1024);\n> \t\t\tregfree(®ex);\n> -\t\t\tdie(\"invalid pickaxe regex: %s\", errbuf);\n> +\t\t\tdie(\"invalid regex: %s\", errbuf);\n> \t\t}\n> \t\tregexp = ®ex;\n> \t} else {\n"},{"id":"219260","messageId":"7vsj0zf5b0.fsf@alter.siamese.dyndns.org","threadId":"34001","inReplyTo":"1370002335-6596-3-git-send-email-artagnon@gmail.com","subject":"Re: [PATCH 2/2] diffcore-pickaxe doc: document -S and -G properly","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-06-03T17:54:43Z","receivedAt":"2013-06-03T17:54:43Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ramkumar Ramachandra writes:\n\n> The documentation of -S and -G is very sketchy. Completely rewrite the\n> sections in Documentation/diff-options.txt and\n> Documentation/gitdiffcore.txt.\n\nWill queue; thanks.\n"}]}