{"thread":{"id":"33850","subject":"[PATCH v2 0/2] Improve diffcore-pickaxe documentation","startedAt":"2013-05-17T12:23:21Z","lastAt":"2013-05-24T16:54:19Z","messageCount":10,"participants":["Ramkumar Ramachandra","Junio C Hamano","Phil Hord"],"isPatch":true,"patchVersion":2,"patchTotal":2},"messages":[{"id":"217707","messageId":"1368793403-4642-1-git-send-email-artagnon@gmail.com","threadId":"33850","inReplyTo":null,"subject":"[PATCH v2 0/2] Improve diffcore-pickaxe documentation","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-05-17T12:23:21Z","receivedAt":"2013-05-17T12:23:21Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"[1/2] is unchangd, but [2/2] has some major changes: thanks to inputs\nfrom Junio and Phil. The inter-diff for [2/2] follows.\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex 765abc5..b61a666 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -383,13 +383,13 @@ ifndef::git-format-patch[]\n \tthat matches other criteria, nothing is selected.\n \n -S::\n-\tLook for commits where the specified string was added or\n-\tremoved. More precisely, find commits that change the number\n-\tof occurrences of the specified string.\n+\tLook for commits that change the number of occurrences of the\n+\tspecified string (i.e. addition/ deletion) in a file.\n+\tIntended for the scripter's use.\n +\n-It is often useful when you're looking for an exact string (like a\n-function prototype), and want to know the history of that string since\n-it first came into being.\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 \n -G::\n \tGrep through the patch text of commits for added/removed lines\n@@ -419,8 +419,8 @@ information.\n \tin .\n \n --pickaxe-regex::\n-\tMake the not a plain string but an extended POSIX\n-\tregex to match. Implied when using `-G`.\n+\tTreat the not as a plain string, but an extended\n+\tPOSIX regex to match. It is implied when `-G` is used.\n endif::git-format-patch[]\n \n -O::\ndiff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt\nindex 39b9c51..d0f2b91 100644\n--- a/Documentation/gitdiffcore.txt\n+++ b/Documentation/gitdiffcore.txt\n@@ -223,16 +223,16 @@ diffcore-pickaxe: For Detecting Addition/Deletion of Specified String\n ---------------------------------------------------------------------\n \n There are two kinds of pickaxe: the S kind (corresponding to 'git log\n--S') and the G kind (corresponding to 'git log -G').\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. While\n-rename detection works as usual, 'git log -S' cannot omit commits\n-where a the small string being looked for is moved verbatim from one\n-file to another (since the number of occurrences of that string\n-changed in each of those two filepairs). The implementation\n-essentially runs a count, and is significantly cheaper than the G\n-kind.\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@@ -240,12 +240,16 @@ 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-A diffcore-pickaxe option worth mentioning: `--pickaxe-all`. When not\n-in effect, diffcore-pickaxe leaves only such filepairs that touch the\n-specified string in its output. When in effect, diffcore-pickaxe\n-leaves all filepairs intact if there is such a filepair, or makes the\n-output empty otherwise. The latter behavior is designed to make\n-reviewing of the changes in the context of the whole changeset easier.\n+When `--pickaxe-regex` is used with `-S`, treat the 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 \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 | 37 ++++++++++++++++++++++++++-------\n Documentation/gitdiffcore.txt | 47 +++++++++++++++++++++++++-----------------\n diffcore-pickaxe.c | 2 +-\n 3 files changed, 58 insertions(+), 28 deletions(-)\n\n-- \n1.8.1.2.432.g070c57d\n"},{"id":"217708","messageId":"1368793403-4642-2-git-send-email-artagnon@gmail.com","threadId":"33850","inReplyTo":"1368793403-4642-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-17T12:23:22Z","receivedAt":"2013-05-17T12:23:22Z","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 error\nmessage to match the -S error message.\n\nSigned-off-by: Ramkumar Ramachandra \n---\n diffcore-pickaxe.c | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/diffcore-pickaxe.c b/diffcore-pickaxe.c\nindex 63722f8..d69a7a2 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 pickaxe regex: %s\", errbuf);\n \t}\n \n \tpickaxe(&diff_queued_diff, o, ®ex, NULL, diff_grep);\n-- \n1.8.1.2.432.g070c57d\n"},{"id":"217709","messageId":"1368793403-4642-3-git-send-email-artagnon@gmail.com","threadId":"33850","inReplyTo":"1368793403-4642-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-17T12:23:23Z","receivedAt":"2013-05-17T12:23:23Z","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 \nSigned-off-by: Ramkumar Ramachandra \n---\n Documentation/diff-options.txt | 37 ++++++++++++++++++++++++++-------\n Documentation/gitdiffcore.txt | 47 +++++++++++++++++++++++++-----------------\n 2 files changed, 57 insertions(+), 27 deletions(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex 104579d..b61a666 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -383,14 +383,35 @@ 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 commits that change the number of occurrences of the\n+\tspecified 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 \n -G::\n-\tLook for differences whose added or removed line matches\n-\tthe given .\n+\tGrep through the patch text of commits for added/removed lines\n+\tthat match . `--pickaxe-regex` is implied in this\n+\tmode.\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 didn't 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 +419,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 not as a plain string, but an extended\n+\tPOSIX regex to match. It is implied when `-G` is used.\n endif::git-format-patch[]\n \n -O::\ndiff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt\nindex 568d757..d0f2b91 100644\n--- a/Documentation/gitdiffcore.txt\n+++ b/Documentation/gitdiffcore.txt\n@@ -222,25 +222,34 @@ 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-changeset easier.\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+\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 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 \n diffcore-order: For Sorting the Output Based on Filenames\n ---------------------------------------------------------\n-- \n1.8.1.2.432.g070c57d\n"},{"id":"217771","messageId":"7vfvxlw055.fsf@alter.siamese.dyndns.org","threadId":"33850","inReplyTo":"1368793403-4642-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-18T01:24:22Z","receivedAt":"2013-05-18T01:24:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ramkumar Ramachandra writes:\n\n> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\n> index 104579d..b61a666 100644\n> --- a/Documentation/diff-options.txt\n> +++ b/Documentation/diff-options.txt\n> @@ -383,14 +383,35 @@ 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 commits that change the number of occurrences of the\n\nThe first part of the change is misguided. First of all, this text\nalso appears in the documentation of \"git diff\" and -S limits the\noutput to those filepairs that match its criteria.\n\n\"git log A..B -- foo\" looks for commits that has changes in paths\nthat matches 'foo'. \"git log\" that selects commits is affected by\nthe outcome of what \"diff\" shows. This \"looks for *commits*\" is a\ncharacteristic of \"log\", not specific to the -S option.\n\nThe aspect of \"diff\" behaviour that is affected by -S is what is\nconsidered as difference. Usually \"diff\" says \"preimage and\npostimage are different\" for any change, but -S changes that. The\npreimage and postimage has to have different number of specified\nblock of text to be considered different.\n\nAnd that is why the original says \"look for differences\".\n\n> +\tspecified 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\nI am not sure this half-way description is a good idea. If you want\nto use it to discover what happend \"since it first came into being\",\nyou need to use this (and the feature is designed for such a use\npattern) iteratively, find the first commit that changes the block\nof the text that appear in the latest version, find the corresponding\nblock of interest in the preimage and then feed that to -S and start\ndigging from that first-discovered commit. If the text describes\nthat iteration fully, I think that is fine, but if you read the\nabove literally, it looks as if you feed one version of -S and it\nwould do the necessary adjustment on its own, which is misleading.\n\n> -G::\n> -\tLook for differences whose added or removed line matches\n> -\tthe given .\n> +\tGrep through the patch text of commits for added/removed lines\n> +\tthat match . `--pickaxe-regex` is implied in this\n> +\tmode.\n\nThe same comment on differences vs commits apply to this.\n\nIf there were any behaviour change --pickaxe-regex introduces to -S\nthat also applies to -G \"other than the pattern is used as a regular\nexpression\", I would agree it is a good idea to say that other\nbehaviour is implied, but as far as I know, there is no such\nimplication. Drop --pickaxe-regex, as it is not even implied in the\ncode:\n\n\t} else if ((argcount = short_opt('G', av, &optarg))) {\n\t\toptions->pickaxe = optarg;\n\t\toptions->pickaxe_opts |= DIFF_PICKAXE_KIND_G;\n\t\treturn argcount;\n\t}\n\nso even if there were some code added in the future that does\n\n\tif (options->pickaxe_opts & DIFF_PICKAXE_REGEX) {\n\t\tdo this thing only when the user said\n --pickaxe-regex from the command line\n\t}\n\nit will _not_ apply to users of -G.\n\n\"grep through\", if the reader knows \"grep\", with \"match \", it\nis crystal clear that this expects a regular expression. And that\nis the only thing that makes -G and --pickaxe-regex superficially\nrelated.\n\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 didn't change).\n> ++\n> +See the 'pickaxe' entry in linkgit:gitdiffcore[7] for more\n> +information.\n\nThis is a readable example (I think we tend not to use contraction,\nso if I were writing it, I wouldn't have written \"didn't change\",\nthough).\n\n> --pickaxe-regex::\n> -\tMake the not a plain string but an extended POSIX\n> -\tregex to match.\n> +\tTreat the not as a plain string, but an extended\n> +\tPOSIX regex to match. It is implied when `-G` is used.\n\nDitto. Rather, \n\n\tTreat the given to the -S option as an extended\n\tPOSIX regular expression to match.\n\n> diff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt\n> index 568d757..d0f2b91 100644\n> --- a/Documentation/gitdiffcore.txt\n> +++ b/Documentation/gitdiffcore.txt\n> @@ -222,25 +222,34 @@ 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> -changeset easier.\n\nThis part is impossible to review on a bus, so I won't comment in\nthis message.\n\nWhy did you even have to touch the paragraph for --pickaxe-all?\nThat applies to both -S and -G. I thought it would be just the\nmatter of slightly tweaking the introductory paragraph (which was\nwritten back when there was only -S), keeping the second paragraph\nfor -S as-is, and insert an additional paragraph for -G before\n--pickaxe-all.\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> +\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 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> \n> diffcore-order: For Sorting the Output Based on Filenames\n> ---------------------------------------------------------\n"},{"id":"217772","messageId":"7v8v3dw03q.fsf@alter.siamese.dyndns.org","threadId":"33850","inReplyTo":"1368793403-4642-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-05-18T01:25:13Z","receivedAt":"2013-05-18T01:25:13Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"As I already said, I think calling this as pickaxe-regex is wrong\n(\"invalid regex\" is fine, though). More on this in the review for\n[2/2].\n"},{"id":"217845","messageId":"7vsj1jzao7.fsf@alter.siamese.dyndns.org","threadId":"33850","inReplyTo":"7vfvxlw055.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 2/2] diffcore-pickaxe doc: document -S and -G properly","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-05-19T07:33:12Z","receivedAt":"2013-05-19T07:33:12Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Ramkumar Ramachandra writes:\n> ...\n>> -G::\n>> -\tLook for differences whose added or removed line matches\n>> -\tthe given .\n>> +\tGrep through the patch text of commits for added/removed lines\n>> +\tthat match . `--pickaxe-regex` is implied in this\n>> +\tmode.\n>\n> The same comment on differences vs commits apply to this.\n> ...\n> it will _not_ apply to users of -G.\n\ns/.$/ unless they say --pickaxe-regex./; so -G does not imply it at\nall.\n\n> \"grep through\", if the reader knows \"grep\", with \"match \", it\n> is crystal clear that this expects a regular expression. And that\n> is the only thing that makes -G and --pickaxe-regex superficially\n> related.\n\ns/^The description begins with /; Sorry, but I couldn't write\ncomplete sentences on a bus ;-)\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>> -changeset easier.\n>\n> This part is impossible to review on a bus, so I won't comment in\n> this message.\n>\n> Why did you even have to touch the paragraph for --pickaxe-all?\n> That applies to both -S and -G. I thought it would be just the\n> matter of slightly tweaking the introductory paragraph (which was\n> written back when there was only -S), keeping the second paragraph\n> for -S as-is, and insert an additional paragraph for -G before\n> --pickaxe-all.\n\nNow I see that the paragraph for --pickaxe-all needs to be touched;\nthe original talks about \"touch the specified string\", which only\napplies to -S and needs to be adjusted.\n\nSo here is my attempt of clarifying it.\n\n\tThis transformation is used to find filepairs that represent\n\ttwo kinds of changes, and is controlled by the -S, -G and\n\t--pickaxe-all options.\n\n\tThe \"-S\" option tells Git to consider that a\n\tfilepair has differences only if the number of occurrences\n\tof the specified block of text is different between its\n\tpreimage and its postimage, and treat other filepairs as if\n\tthey did not have any change. This is meant to be used with\n\ta block of text that is unique enough to occur only once (so\n\texpected the number of occurences is 1 vs 0 or 0 vs 1) to\n\tuse with \"git log\" to find a commit that touched the block\n\tof text the last time. When used with the \"--pickaxe-regex\"\n\toption, the is used as a POSIX extended\n\tregular expression to match, instead of a literal string.\n\n\tThe \"-G\" option tells Git to consider\n\tthat a filepair has differences only if a textual diff\n\tbetween its preimage and postimage would indicate a line\n\tthat matches the given regular expression is changed, and\n\ttreat other filepairs as if they did not have any change.\n\n\tWhen -S or -G option is used without \"--pickaxe-all\" option,\n\tonly filepairs that match their respective criterion are\n\tkept in the output. When `--pickaxe-all` is used, all\n\tfilepairs intact if there is such a filepair, or makes the\n\toutput empty otherwise. This behaviour is designed to make\n\treviewing of the changes in the context of the whole\n\tchangeset easier.\n"},{"id":"218351","messageId":"CALkWK0n+NTnO0_4jNuR3Z5qmA_=-Dux+gq8kNzAT4YLC12Z8uQ@mail.gmail.com","threadId":"33850","inReplyTo":"7vsj1jzao7.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-24T09:37:20Z","receivedAt":"2013-05-24T09:37:20Z","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 the other comments, and have made suitable changes.\nLet's review your block now.\n\n> This transformation is used to find filepairs that represent\n> two kinds of changes, and is controlled by the -S, -G and\n> --pickaxe-all options.\n\nWhy do you call this a \"transformation\"? Is git log --author=\"foo\" a\ntransformation on the git-log output? Then how is git log -Sfoo a\ntransformation?\n\nTwo kinds of changes controlled by three different options? Isn't the\noriginal much clearer?\n\nThe title says diffcore-pickaxe, and the first paragraph says:\n\nThere 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\" option tells Git to consider that a\n> filepair has differences only if the number of occurrences\n> of the specified block of text is different between its\n> preimage and its postimage, and treat other filepairs as if\n> they did not have any change.\n\nI'll rewrite this without the trailing \"and treat other filepairs as\nif they did not have any change\" (which I'm not fond of).\n\n> This is meant to be used with\n> a block of text that is unique enough to occur only once (so\n> expected the number of occurences is 1 vs 0 or 0 vs 1) to\n> use with \"git log\" to find a commit that touched the block\n> of text the last time.\n\nYou're saying how you think it's \"meant\" to be used, but in doing so\nyou've failed to describe its operation faithfully. I've already\ndescribed how it's meant to be used in diff-options (digging a block\nof text iteratively) and this is the place to explain what it is doing\nfaithfully. Hence my previous writeup on changes in number of\noccurrences and rename detection: I _had_ to read the code to\nunderstand it properly, and your writeup is not helping by telling me\nabout idiomatic usage.\n\nAlso, you've dropped computational expense which was there in the original.\n\n> When used with the \"--pickaxe-regex\"\n> option, the is used as a POSIX extended\n> regular expression to match, instead of a literal string.\n\nBetter.\n\n> The \"-G\" option tells Git to consider\n> that a filepair has differences only if a textual diff\n> between its preimage and postimage would indicate a line\n> that matches the given regular expression is changed, and\n> treat other filepairs as if they did not have any change.\n\n\"would indicate\"? Really? I'll rewrite this without the trailing\n\"and treat other filepairs ..\".\n\nYou've once again dropped what it means in the context of in-file\nmoves (rename detection), and computational expense from the original.\n\n> When -S or -G option is used without \"--pickaxe-all\" option,\n> only filepairs that match their respective criterion are\n> kept in the output.\n\nMuch better.\n\n> When `--pickaxe-all` is used, all\n> filepairs intact if there is such a filepair, or makes the\n> output empty otherwise.\n\n-ENOPARSE. I didn't particularly like the original, and this isn't\nbetter. I'll rewrite it.\n\n> This behaviour is designed to make\n> reviewing of the changes in the context of the whole\n> changeset easier.\n\nSame as original. Okay.\n\nThanks.\n"},{"id":"218374","messageId":"CABURp0qCOMJnQ=+p81eXLtj6+zujO=MsYODx8zR_cXjVXwV=HA@mail.gmail.com","threadId":"33850","inReplyTo":"CALkWK0n+NTnO0_4jNuR3Z5qmA_=-Dux+gq8kNzAT4YLC12Z8uQ@mail.gmail.com","subject":"Re: [PATCH 2/2] diffcore-pickaxe doc: document -S and -G properly","fromName":"Phil Hord","fromEmail":"phil.hord@gmail.com","sentAt":"2013-05-24T14:58:29Z","receivedAt":"2013-05-24T14:58:29Z","isPatch":true,"sender":{"key":"phil.hord@gmail.com","avatar":"https://avatars.githubusercontent.com/u/123908?v=4"},"body":"On Fri, May 24, 2013 at 5:37 AM, Ramkumar Ramachandra\n wrote:\n> Junio C Hamano wrote:\n>> [...]\n>\n> I agree with the other comments, and have made suitable changes.\n> Let's review your block now.\n>\n>> This transformation is used to find filepairs that represent\n>> two kinds of changes, and is controlled by the -S, -G and\n>> --pickaxe-all options.\n>\n> Why do you call this a \"transformation\"? Is git log --author=\"foo\" a\n> transformation on the git-log output? Then how is git log -Sfoo a\n> transformation?\n>\n> Two kinds of changes controlled by three different options? Isn't the\n> original much clearer?\n\nThey are all three filters. They transform the output by limiting it\nto commits which meet specific conditions. Transformation is used in\nthe network-graphs sense of the word. It fits the beginning of the\ndocument where it says this:\n\n The diffcore mechanism is fed a list of such comparison results\n (each of which is called \"filepair\", although at this point each\n of them talks about a single file), and transforms such a list\n into another list. There are currently 5 such transformations:\n\n - diffcore-break\n - diffcore-rename\n - diffcore-merge-broken\n - diffcore-pickaxe\n - diffcore-order\n"},{"id":"218383","messageId":"CALkWK0kVYCsLg3R9H1OVr2R9k_cBQCghG+gTdrD8UKXEhgeYpg@mail.gmail.com","threadId":"33850","inReplyTo":"CABURp0qCOMJnQ=+p81eXLtj6+zujO=MsYODx8zR_cXjVXwV=HA@mail.gmail.com","subject":"Re: [PATCH 2/2] diffcore-pickaxe doc: document -S and -G properly","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-05-24T16:01:09Z","receivedAt":"2013-05-24T16:01:09Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Phil Hord wrote:\n> It fits the beginning of the\n> document where it says this:\n\nAh, I missed that. Either way, I'm quite happy with v3: we can change\nthe first paragraph to use the word \"transformation\" if we really\nwant.\n"},{"id":"218396","messageId":"7v8v34b9ok.fsf@alter.siamese.dyndns.org","threadId":"33850","inReplyTo":"CABURp0qCOMJnQ=+p81eXLtj6+zujO=MsYODx8zR_cXjVXwV=HA@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-05-24T16:54:19Z","receivedAt":"2013-05-24T16:54:19Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Phil Hord writes:\n\n> On Fri, May 24, 2013 at 5:37 AM, Ramkumar Ramachandra\n> wrote:\n>> Junio C Hamano wrote:\n>>> [...]\n>>\n>> I agree with the other comments, and have made suitable changes.\n>> Let's review your block now.\n>>\n>>> This transformation is used to find filepairs that represent\n>>> two kinds of changes, and is controlled by the -S, -G and\n>>> --pickaxe-all options.\n>>\n>> Why do you call this a \"transformation\"? Is git log --author=\"foo\" a\n>> transformation on the git-log output? Then how is git log -Sfoo a\n>> transformation?\n>>\n>> Two kinds of changes controlled by three different options? Isn't the\n>> original much clearer?\n>\n> They are all three filters. They transform the output by limiting it\n> to commits which meet specific conditions. Transformation is used in\n> the network-graphs sense of the word. It fits the beginning of the\n> document where it says this:\n>\n> The diffcore mechanism is fed a list of such comparison results\n> (each of which is called \"filepair\", although at this point each\n> of them talks about a single file), and transforms such a list\n> into another list. There are currently 5 such transformations:\n>\n> - diffcore-break\n> - diffcore-rename\n> - diffcore-merge-broken\n> - diffcore-pickaxe\n> - diffcore-order\n\nThanks.\n"}]}