{"thread":{"id":"33916","subject":"[PATCH v3 0/2] Improve diffcore-pickaxe documentation","startedAt":"2013-05-24T10:33:53Z","lastAt":"2013-06-02T20:28:09Z","messageCount":7,"participants":["Ramkumar Ramachandra","Junio C Hamano"],"isPatch":true,"patchVersion":3,"patchTotal":2},"messages":[{"id":"218356","messageId":"1369391635-13056-1-git-send-email-artagnon@gmail.com","threadId":"33916","inReplyTo":null,"subject":"[PATCH v3 0/2] Improve diffcore-pickaxe documentation","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-05-24T10:33:53Z","receivedAt":"2013-05-24T10:33:53Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"[1/2] replaces \"pickaxe regex\" with \"regex\", as suggested by Junio.\n\n[2/2] is now co-authored by Junio.  I've taken what I think are the\nbest changes introduced by both versions and merged them.  The\ninter-diff follows.\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex b61a666..2835eef 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -383,18 +383,19 @@ ifndef::git-format-patch[]\n \tthat matches other criteria, nothing is selected.\n \n -S<string>::\n-\tLook for commits that change the number of occurrences of the\n-\tspecified string (i.e. addition/ deletion) in a file.\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 especially useful when you're looking for an exact block of code\n (like a struct), and want to know the history of that block since it\n-first came into being.\n+first came into being: use the feature iteratively to feed the\n+interesting block in the preimage back into `-S`, and keep going until\n+you get the very first version of the block.\n \n -G<regex>::\n-\tGrep through the patch text of commits for added/removed lines\n-\tthat match <regex>.  `--pickaxe-regex` is implied in this\n-\tmode.\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@@ -408,7 +409,7 @@ file:\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 didn't change).\n+occurrences of that string did not change).\n +\n See the 'pickaxe' entry in linkgit:gitdiffcore[7] for more\n information.\n@@ -419,8 +420,8 @@ information.\n \tin <string>.\n \n --pickaxe-regex::\n-\tTreat the <string> not as a plain string, but an extended\n-\tPOSIX regex to match.  It is implied when `-G` is used.\n+\tTreat the <string> given to `-S` as an extended POSIX regular\n+\texpression to match.\n endif::git-format-patch[]\n \n -O<orderfile>::\ndiff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt\nindex d0f2b91..ef4c04a 100644\n--- a/Documentation/gitdiffcore.txt\n+++ b/Documentation/gitdiffcore.txt\n@@ -225,31 +225,29 @@ diffcore-pickaxe: For Detecting Addition/Deletion of Specified String\n There are two kinds of pickaxe: the S kind (corresponding to 'git log\n -S') and the G kind (mnemonic: grep; corresponding to 'git log -G').\n \n-The S kind detects filepairs whose \"result\" side and \"origin\" side\n-have different number of occurrences of specified string.  By\n-definition, it will not detect in-file moves.  Also, when a commit\n-moves a file wholesale without affecting the string being looked at,\n-rename detection kicks in as usual, and 'git log -S' omits the commit\n-(since the number of occurrences of that string didn't change in that\n-rename-detected filepair).  The implementation essentially runs a\n-count, and is significantly cheaper than the G kind.\n-\n-The G kind detects filepairs whose patch text has an added or a\n-deleted line that matches the given regexp.  This means that it can\n-detect in-file (or what rename-detection considers the same file)\n-moves.  The implementation of 'git log -G' runs diff twice and greps,\n-and this can be quite expensive.\n-\n-When `--pickaxe-regex` is used with `-S`, treat the <string> not as a\n-plain string, but an extended POSIX regex to match.  It is implied\n-when `-G` is used.\n-\n-When `--pickaxe-all` is not in effect, diffcore-pickaxe leaves only\n-the filepairs that touch the specified string in its output.  When in\n-effect, diffcore-pickaxe leaves all filepairs intact if there is such\n-a filepair, or makes the output empty otherwise.  The latter behavior\n-is designed to make reviewing of the changes in the context of the\n-whole changeset easier.\n+\"-S<block of text>\" 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, rename detection kicks in as usual, and `-S` omits the\n+filepair (since the number of occurrences of that string didn't change\n+in that rename-detected filepair).  The implementation essentially\n+runs a count, and is significantly cheaper than the G kind.  When used\n+with `--pickaxe-regex`, treat the <block of text> as an extended POSIX\n+regular expression to match, instead of a literal string.\n+\n+\"-G<regular expression>\" detects filepairs whose textual diff has an\n+added or a deleted line that matches the given regular expression.\n+This means that it can detect in-file (or what rename-detection\n+considers the same file) moves.  The implementation runs diff twice\n+and greps, and this can be quite 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 diffcore-order: For Sorting the Output Based on Filenames\n ---------------------------------------------------------\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  | 43 ++++++++++++++++++++++++------------------\n diffcore-pickaxe.c             |  4 ++--\n 3 files changed, 57 insertions(+), 28 deletions(-)\n\n-- \n1.8.3.rc3.17.gd95ec6c.dirty\n"},{"id":"218357","messageId":"1369391635-13056-2-git-send-email-artagnon@gmail.com","threadId":"33916","inReplyTo":"1369391635-13056-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-24T10:33:54Z","receivedAt":"2013-05-24T10:33:54Z","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 <artagnon@gmail.com>\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, &regex, errbuf, 1024);\n \t\tregfree(&regex);\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, &regex, 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, &regex, errbuf, 1024);\n \t\t\tregfree(&regex);\n-\t\t\tdie(\"invalid pickaxe regex: %s\", errbuf);\n+\t\t\tdie(\"invalid regex: %s\", errbuf);\n \t\t}\n \t\tregexp = &regex;\n \t} else {\n-- \n1.8.3.rc3.17.gd95ec6c.dirty\n"},{"id":"218358","messageId":"1369391635-13056-3-git-send-email-artagnon@gmail.com","threadId":"33916","inReplyTo":"1369391635-13056-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-24T10:33:55Z","receivedAt":"2013-05-24T10:33:55Z","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<regexp> that greps in the patch text)\n\nInputs-from: Phil Hord <phil.hord@gmail.com>\nCo-authored-by: Junio C Hamano <gitster@pobox.com>\nSigned-off-by: Ramkumar Ramachandra <artagnon@gmail.com>\n---\n Documentation/diff-options.txt | 38 +++++++++++++++++++++++++++++--------\n Documentation/gitdiffcore.txt  | 43 ++++++++++++++++++++++++------------------\n 2 files changed, 55 insertions(+), 26 deletions(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex 104579d..2835eef 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<string>::\n-\tLook for differences that introduce or remove an instance of\n-\t<string>. 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 especially useful when you're looking for an exact block of code\n+(like a struct), and want to know the history of that block since it\n+first came into being: use the feature iteratively to feed the\n+interesting block in the preimage back into `-S`, and keep going until\n+you get the very first version of the block.\n \n -G<regex>::\n-\tLook for differences whose added or removed line matches\n-\tthe given <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+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 <string>.\n \n --pickaxe-regex::\n-\tMake the <string> not a plain string but an extended POSIX\n-\tregex to match.\n+\tTreat the <string> given to `-S` as an extended POSIX regular\n+\texpression to match.\n endif::git-format-patch[]\n \n -O<orderfile>::\ndiff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt\nindex 568d757..ef4c04a 100644\n--- a/Documentation/gitdiffcore.txt\n+++ b/Documentation/gitdiffcore.txt\n@@ -222,26 +222,33 @@ 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+There are two kinds of pickaxe: the S kind (corresponding to 'git log\n+-S') and the G kind (mnemonic: grep; corresponding to 'git log -G').\n+\n+\"-S<block of text>\" 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, rename detection kicks in as usual, and `-S` omits the\n+filepair (since the number of occurrences of that string didn't change\n+in that rename-detected filepair).  The implementation essentially\n+runs a count, and is significantly cheaper than the G kind.  When used\n+with `--pickaxe-regex`, treat the <block of text> as an extended POSIX\n+regular expression to match, instead of a literal string.\n+\n+\"-G<regular expression>\" detects filepairs whose textual diff has an\n+added or a deleted line that matches the given regular expression.\n+This means that it can detect in-file (or what rename-detection\n+considers the same file) moves.  The implementation runs diff twice\n+and greps, and this can be quite 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.rc3.17.gd95ec6c.dirty\n"},{"id":"218400","messageId":"7v38tcb7yx.fsf@alter.siamese.dyndns.org","threadId":"33916","inReplyTo":"1369391635-13056-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-05-24T17:31:18Z","receivedAt":"2013-05-24T17:31:18Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ramkumar Ramachandra <artagnon@gmail.com> 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>\n> References:\n> 52e9578 ([PATCH] Introducing software archaeologist's tool \"pickaxe\".)\n> f506b8e (git log/diff: add -G<regexp> that greps in the patch text)\n>\n> Inputs-from: Phil Hord <phil.hord@gmail.com>\n> Co-authored-by: Junio C Hamano <gitster@pobox.com>\n> Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>\n> ---\n>  Documentation/diff-options.txt | 38 +++++++++++++++++++++++++++++--------\n>  Documentation/gitdiffcore.txt  | 43 ++++++++++++++++++++++++------------------\n>  2 files changed, 55 insertions(+), 26 deletions(-)\n>\n> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\n> index 104579d..2835eef 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<string>::\n> -\tLook for differences that introduce or remove an instance of\n> -\t<string>. 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 especially useful when you're looking for an exact block of code\n> +(like a struct), and want to know the history of that block since it\n> +first came into being: use the feature iteratively to feed the\n> +interesting block in the preimage back into `-S`, and keep going until\n> +you get the very first version of the block.\n\nOK, even though I would not say \"especially\" nor \"useful\" if I were\nwriting it, as it is the only use case it was designed for.\n\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> +occurrences of that string did not change).\n> ++\n> +See the 'pickaxe' entry in linkgit:gitdiffcore[7] for more\n> +information.\n\nOK.\n\n>  --pickaxe-regex::\n> -\tMake the <string> not a plain string but an extended POSIX\n> -\tregex to match.\n> +\tTreat the <string> given to `-S` as an extended POSIX regular\n> +\texpression to match.\n\nOK.\n\n> diff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt\n> index 568d757..ef4c04a 100644\n> --- a/Documentation/gitdiffcore.txt\n> +++ b/Documentation/gitdiffcore.txt\n> @@ -222,26 +222,33 @@ 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\n\n> +There are two kinds of pickaxe: the S kind (corresponding to 'git log\n> +-S') and the G kind (mnemonic: grep; corresponding to 'git log -G').\n\nThis is good as the beginning of a second paragraph or the second\nsentence of the first paragraph.  This patch loses the description\nof the general purpose of this machinery that should come at the\nvery beginning of the section (the original had a very good ut valid\nonly back when we had only -S; my \"how about this\" text did not have\na good one).\n\nFor example, the \"rename\" is about taking one set of filepairs and\nexpressing (some of) them as renames or copies by merging a deletion\nfilepair and a creation filepair into a rename-modify filepair, or\nturning a creation filepair into a copy-modify filepair by finding a\npreimage.  What does this transformation do?\n\nAgain here is my attempt for that missing first paragraph:\n\n\tThis transformation limits the set of filepairs to those\n\tthat change specified strings between the preimage and the\n\tpostimage in a certain way.\n\n        -S<block of text> and -G<regex> options are used to specify\n\tdifferent ways these strings are sought.  Without\n\t--pickaxe-all, only the filepairs matching the given\n\tcriterion is left in the output; all filepairs are left in\n\tthe output when --pickaxe-all is used and if at least one\n\tfilepair matches the given criterion.\n\nbut I do not have enough time now to condense the above down to a\nreadable paragraph of reasonable length (I expect that the ideal\nfinal form would be like 5-6 lines at most).\n\n> +\"-S<block of text>\" 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, rename detection kicks in as usual, and `-S` omits the\n> +filepair (since the number of occurrences of that string didn't change\n> +in that rename-detected filepair).\n\nI am not sure why it is necessary to say anything about what the\nprevious step (diffcore-rename) might have done.  The input of this\n(or any other) step in the diffcore pipeline is a preimage-postimage\nfilepairs, and to this transformation the filename does not matter.\nWhether a file was moved (either \"wholesale\", implying nothing\nchanged, or renamed with modification at the same time) without\ntouching the block of text, or a file did not get involved in any\nrenaming, the only thing that matters is what the preimage and the\npostimage in a filepair has (or does not have).\n\n> + The implementation essentially\n> +runs a count, and is significantly cheaper than the G kind.  When used\n> +with `--pickaxe-regex`, treat the <block of text> as an extended POSIX\n> +regular expression to match, instead of a literal string.\n\nSure.  Is \"essentially runs a count\" needed, though?  The reader has\njust read \"number of occurrences of the specified block of text\" so\nit would be obvious that the implementation counts.  It may be true\nthat it is significantly cheaper, but because they serve different\npurposes, I am not sure it is worth saying.  It is like saying that\na hammer is significantly faster to drive a nail into wood than a\nscrewdriver to drive a screw into wood, without saying \"nail\" and\n\"screw\".  It only invites readers to use a hammer to drive a screw.\n\n> +\"-G<regular expression>\" detects filepairs whose textual diff has an\n> +added or a deleted line that matches the given regular expression.\n> +This means that it can detect in-file (or what rename-detection\n> +considers the same file) moves.\n\n\"it can\" sounds as if it is always a merit, which is probably not\nwhat you wanted to imply.\n\nWhen you are trying to see how a particular line came into the\nshape, you would want to know what the previous shape of it was, but\na literal move will also be shown, which is a noise for the purpose\nof digging.\n\n> +The implementation runs diff twice\n> +and greps, and this can be quite expensive.\n\nUnlike the \"count\" one above which was obvious, the \"runs diff and\ngreps hence expensive\" part is worth saying.\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\nOK.\n\n>  \n> -\n>  diffcore-order: For Sorting the Output Based on Filenames\n>  ---------------------------------------------------------\n"},{"id":"219097","messageId":"CALkWK0m+kUa0QUotHXSYK40vFviFFv2yETnf6sEZMh05gOgLKg@mail.gmail.com","threadId":"33916","inReplyTo":"7v38tcb7yx.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 2/2] diffcore-pickaxe doc: document -S and -G properly","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-05-31T12:04:54Z","receivedAt":"2013-05-31T12:04:54Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Junio C Hamano wrote:\n> [...]\n\nI agree with everything else, and made changes accordingly.\n\n>         This transformation limits the set of filepairs to those\n>         that change specified strings between the preimage and the\n>         postimage in a certain way.\n\nDefinitely good.\n\n>         -S<block of text> and -G<regex> options are used to specify\n>         different ways these strings are sought.\n\nDefinitely better than the \"two kinds of pickaxe\" thing.\n\n>         Without\n>         --pickaxe-all, only the filepairs matching the given\n>         criterion is left in the output; all filepairs are left in\n>         the output when --pickaxe-all is used and if at least one\n>         filepair matches the given criterion.\n\nWhy do a poor-man's version of --pickaxe-all here, when the last\nparagraph already does justice to this?\n\nWhen `-S` or `-G` are used without `--pickaxe-all`, only filepairs\nthat match their respective criterion are kept in the output.  When\n`--pickaxe-all` is used, if even one filepair matches their respective\ncriterion in a changeset, the entire changeset is kept.  This behavior\nis designed to make reviewing changes in the context of the whole\nchangeset easier.\n\n> I am not sure why it is necessary to say anything about what the\n> previous step (diffcore-rename) might have done.  The input of this\n> (or any other) step in the diffcore pipeline is a preimage-postimage\n> filepairs, and to this transformation the filename does not matter.\n> Whether a file was moved (either \"wholesale\", implying nothing\n> changed, or renamed with modification at the same time) without\n> touching the block of text, or a file did not get involved in any\n> renaming, the only thing that matters is what the preimage and the\n> postimage in a filepair has (or does not have).\n\nWhile what you're saying is technically true, I think it is important\nto explain the interaction between diffcore-pickaxe and\ndiffcore-rename as I have done.  Someone who wants to understand what\n`git log -S` does will come to this page and read this section:\nwithout reading diffcore-rename, she will have an incomplete picture;\nwhat's the harm in explaining diffcore-rename in the context of\ndiffcore-pickaxe?\n\nI did do a s/rename detection/diffcore-rename/ though, so the user\nknows where to look for more on this rename thing.\n"},{"id":"219188","messageId":"7v7gicnv6o.fsf@alter.siamese.dyndns.org","threadId":"33916","inReplyTo":"CALkWK0m+kUa0QUotHXSYK40vFviFFv2yETnf6sEZMh05gOgLKg@mail.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-02T19:56:15Z","receivedAt":"2013-06-02T19:56:15Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ramkumar Ramachandra <artagnon@gmail.com> writes:\n\n>>         Without\n>>         --pickaxe-all, only the filepairs matching the given\n>>         criterion is left in the output; all filepairs are left in\n>>         the output when --pickaxe-all is used and if at least one\n>>         filepair matches the given criterion.\n>\n> Why do a poor-man's version of --pickaxe-all here, when the last\n> paragraph already does justice to this?\n\nThe point of the first paragraph is to serve to help both:\n\n (1) people who read about this rather technical part of the\n     diffcore pipeline machinery, to prepare them by listing what\n     they will learn about in the section; and\n\n (2) those who already have read and want to skim over, by giving a\n     concise summary.\n\nIt may have been \"poor\" because it was merely \"something like this\"\npatch, though.\n\n\n> While what you're saying is technically true, I think it is important\n> to explain the interaction between diffcore-pickaxe and\n> diffcore-rename as I have done.  Someone who wants to understand what\n> `git log -S` does will come to this page and read this section:\n> without reading diffcore-rename, she will have an incomplete picture;\n> what's the harm in explaining diffcore-rename in the context of\n> diffcore-pickaxe?\n\nThat is a red-herring; that is exactly why we upfront say that the\ndiffcore machinery is a pipeline and we describe upstream processing\nlike rename before we talk about pickaxe in the same document.\n\nThis document is the most accurate _technical_ documentation of how\nthe pipeline works (and it is not in section 1 of the manual set).\nIf you want to improve end-user documentation by adding explanation\nfor interactions between pipeline stages and also pathspec, I am all\nfor it, but I think that belongs to the larger \"git help diff\", not\n\"git help diffcore\".\n"},{"id":"219191","messageId":"CALkWK0=3SNJ0TFNaM18=DdMN5OQX4L=7-DO1x1U-ASqgFuDmhg@mail.gmail.com","threadId":"33916","inReplyTo":"7v7gicnv6o.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 2/2] diffcore-pickaxe doc: document -S and -G properly","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-06-02T20:28:09Z","receivedAt":"2013-06-02T20:28:09Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Junio C Hamano wrote:\n>> Why do a poor-man's version of --pickaxe-all here, when the last\n>> paragraph already does justice to this?\n>\n> The point of the first paragraph is to serve to help both:\n\nMy question pertains to whether or not the explanation of\n--pickaxe-all can wait till the last paragraph.  You want to\nexplain all the options in the first paragraph, but not\n--pickaxe-regex?\n\n>> While what you're saying is technically true, I think it is important\n>> to explain the interaction between diffcore-pickaxe and\n>> diffcore-rename as I have done.  Someone who wants to understand what\n>> `git log -S` does will come to this page and read this section:\n>> without reading diffcore-rename, she will have an incomplete picture;\n>> what's the harm in explaining diffcore-rename in the context of\n>> diffcore-pickaxe?\n>\n> This document is the most accurate _technical_ documentation of how\n> the pipeline works (and it is not in section 1 of the manual set).\n> If you want to improve end-user documentation by adding explanation\n> for interactions between pipeline stages and also pathspec, I am all\n> for it, but I think that belongs to the larger \"git help diff\", not\n> \"git help diffcore\".\n\nIt's impossible to explain in the diff-options, because I do not have\neven have access to the word \"filepair\", and no diffcore-rename\nmachinery to point to.  I could attempt a vague approximation, but I\ndo not think it's worth it.  I'll remove it if you insist.\n"}]}