{"thread":{"id":"24550","subject":"[RFC/PATCH] Document -B[/], -M and -C variants of -B, -M and -C","startedAt":"2010-07-28T09:43:59Z","lastAt":"2010-08-05T16:14:25Z","messageCount":8,"participants":["Matthieu Moy","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"146600","messageId":"1280310239-16897-1-git-send-email-Matthieu.Moy@imag.fr","threadId":"24550","inReplyTo":null,"subject":"[RFC/PATCH] Document -B[/], -M and -C variants of -B, -M and -C","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2010-07-28T09:43:59Z","receivedAt":"2010-07-28T09:43:59Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"These options take an optional argument, but this optional argument was\nnot documented.\n\nSigned-off-by: Matthieu Moy \n---\nI'm not really happy with my description of -Bn/m, which I essentially\ntook from eeaa46031479 (Junio, Jun 3 2005, diff: Update -B\nheuristics). Someone with better understanding of how it works can\nprobably propose something better.\n\n Documentation/diff-options.txt | 18 ++++++++++++++----\n 1 files changed, 14 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex 2371262..d07809c 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -206,10 +206,18 @@ endif::git-format-patch[]\n \tthe diff-patch output format. Non default number of\n \tdigits can be specified with `--abbrev=`.\n \n--B::\n+-B[]::\n+-B/::\n \tBreak complete rewrite changes into pairs of delete and create.\n-\n--M::\n+\tIf `n` is specified, it gives the threshold (as a percentage\n+\tof changed lines) above which a change is considered as\n+\tcomplete rewrite. For example, `-B90%` means git will detect a\n+\trewrite if more than 90% of the lines have been modified. If\n+\t`m` is specified, then it is the minimum amount of deleted\n+\tlines a surviving broken pair must have to avoid being merged\n+\tback together. See linkgit:gitdiffcore[7] for more details.\n+\n+-M[]::\n ifndef::git-log[]\n \tDetect renames.\n endif::git-log[]\n@@ -218,9 +226,11 @@ ifdef::git-log[]\n \tFor following files across renames while traversing history, see\n \t`--follow`.\n endif::git-log[]\n+\tIf `n` is specified, it has the same meaning as for `-B`.\n \n--C::\n+-C[]::\n \tDetect copies as well as renames. See also `--find-copies-harder`.\n+\tIf `n` is specified, it has the same meaning as for `-B`.\n \n ifndef::git-format-patch[]\n --diff-filter=[ACDMRTUXB*]::\n-- \n1.7.2.25.g9ebe3\n"},{"id":"146720","messageId":"7vk4oeuv4b.fsf@alter.siamese.dyndns.org","threadId":"24550","inReplyTo":"1280310239-16897-1-git-send-email-Matthieu.Moy@imag.fr","subject":"Re: [RFC/PATCH] Document -B[/], -M and -C variants of -B, -M and -C","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-07-29T16:10:28Z","receivedAt":"2010-07-29T16:10:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Matthieu Moy writes:\n\n> I'm not really happy with my description of -Bn/m, which I essentially\n> took from eeaa46031479 (Junio, Jun 3 2005, diff: Update -B\n> heuristics). Someone with better understanding of how it works can\n> probably propose something better.\n\nYour explanation for '' being the same across -B/-M/-C is reasonable.\nExplanation of '' might want to clarify why it counts only the deletion\nand to mention that \"100-similarity != dissimilarity\", but as the end-user\nlevel documentation, these probably are unnecessary.\n\n> +-B[]::\n> +-B/::\n> \tBreak complete rewrite changes into pairs of delete and create.\n> +\tIf `n` is specified, it gives the threshold (as a percentage\n> +\tof changed lines) above which a change is considered as\n> +\tcomplete rewrite. For example, `-B90%` means git will detect a\n> +\trewrite if more than 90% of the lines have been modified. ...\n\nI am fine with the use of word \"lines\" if it is clear that we are giving a\nsimplified explanation (white lie) to the readers, but the (dis)similarity\nnumbers don't have much to do with \"lines\". I would of course be happier\nif we can come up with a phrase that tells the readers that these numbers\nrange between 0-100%, and the larger the is, the larger the extent of\nchange has to be for the filepair to be considered for -B/-M processing,\nwithout use of word \"lines\".\n\nThanks.\n"},{"id":"146782","messageId":"vpqmxt93sew.fsf@bauges.imag.fr","threadId":"24550","inReplyTo":"7vk4oeuv4b.fsf@alter.siamese.dyndns.org","subject":"Re: [RFC/PATCH] Document -B[/], -M and -C variants of -B, -M and -C","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2010-07-30T15:23:19Z","receivedAt":"2010-07-30T15:23:19Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Junio C Hamano writes:\n\n> Matthieu Moy writes:\n>\n>> I'm not really happy with my description of -Bn/m, which I essentially\n>> took from eeaa46031479 (Junio, Jun 3 2005, diff: Update -B\n>> heuristics). Someone with better understanding of how it works can\n>> probably propose something better.\n>\n> Your explanation for '' being the same across -B/-M/-C is reasonable.\n> Explanation of '' might want to clarify why it counts only the deletion\n> and to mention that \"100-similarity != dissimilarity\", but as the end-user\n> level documentation, these probably are unnecessary.\n\nThe thing is: I don't know the anwser myself, so I'm not in a position\ndo write such documentation :-(.\n\n>> +-B[]::\n>> +-B/::\n>> \tBreak complete rewrite changes into pairs of delete and create.\n>> +\tIf `n` is specified, it gives the threshold (as a percentage\n>> +\tof changed lines) above which a change is considered as\n>> +\tcomplete rewrite. For example, `-B90%` means git will detect a\n>> +\trewrite if more than 90% of the lines have been modified. ...\n>\n> I am fine with the use of word \"lines\" if it is clear that we are giving a\n> simplified explanation (white lie) to the readers, but the (dis)similarity\n> numbers don't have much to do with \"lines\".\n\nLikewise, I didn't write \"lines\" as a white lie, but because of my\nignorance ... hence my request for help.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"146786","messageId":"7vk4ocrkfa.fsf@alter.siamese.dyndns.org","threadId":"24550","inReplyTo":"vpqmxt93sew.fsf@bauges.imag.fr","subject":"Re: [RFC/PATCH] Document -B[/], -M and -C variants of -B, -M and -C","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-07-30T16:42:01Z","receivedAt":"2010-07-30T16:42:01Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Matthieu Moy writes:\n\n> Junio C Hamano writes:\n>> Matthieu Moy writes:\n>\n>> Explanation of '' might want to clarify why it counts only the deletion\n>> and to mention that \"100-similarity != dissimilarity\", but as the end-user\n>> level documentation, these probably are unnecessary.\n>\n> The thing is: I don't know the anwser myself, so I'm not in a position\n> do write such documentation :-(.\n> ...\n> Likewise, I didn't write \"lines\" as a white lie, but because of my\n> ignorance ... hence my request for help.\n\nSorry, but I actually do not have much more to say than what eeaa460\n(diff: Update -B heuristics., 2005-06-03) says.\n\nWhen breaking for the purpose of showing a patch as \"total rewrite\", what\nmatters is how little the original contents remain in the result. Imagine\nthat you start from a 100-line document and removed 97 lines from it. You\nthen added 27 lines of new material to make a 30-line document or added\n997 lines to make a 1000-line document---either way you rewrote the\ndocument and how dissimilar the result is relative to the original\nwouldn't be different in either case. N.B. this is only true as long as\nthere are enough new material in the result---removing 97% without adding\nanything is not a rewrite. This 97% is \"how much did we discard from the\noriginal\", and it is the number you would see as the \"dissimilarity index\"\n('m' in '-Bn/m').\n\nWhen breaking, tentatively, for the purpose of rename detection, the\namount of the new material starts mattering more. The reason why we try\nto see if we want to break the pair is exactly because we hope that we may\nfind something similar to the new material in a blob that used to be in\nbut disappeared from another path in the preimage. So we count both\ndeletion and addition to see if the pair has a lot of changes ('n' in\n'-Bn/m'), which is similar to the way how \"similiarity index\" used in the\n\"rename\" codepath is computed, to decide if we want to tentatively break\nthe pair. Halves of a pair that is tentatively broken, when they do not\nhave a matching rename, are merged back together if they were not total\nrewrite (i.e. the dissimilarity index for the pair is lower than the\nthreshold 'm').\n\nIn either case, the algorithm to compute how much \"stuff\" was copied from\nthe original and how much \"stuff\" was added anew to the result is not\nbased on \"lines\", but based on \"bytes\".\n"},{"id":"146938","messageId":"1280747527-30444-1-git-send-email-Matthieu.Moy@imag.fr","threadId":"24550","inReplyTo":"7vk4ocrkfa.fsf@alter.siamese.dyndns.org","subject":"[PATCH v2] Document -B[/], -M and -C variants of -B, -M and -C","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2010-08-02T11:12:07Z","receivedAt":"2010-08-02T11:12:07Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"These options take an optional argument, but this optional argument was\nnot documented.\n\nWhile we're there, fix a typo in a comment in diffcore.h.\n\nSigned-off-by: Matthieu Moy \n---\nHere's a new version. I've eliminated \"line\" from the wording. I'm\nstill not sure I'm technically correct, especially about the\ninteraction between \"n\" and \"m\" (the \"A rewrite is considered when\nboth thresholds are reached par of the patch).\n\n Documentation/diff-options.txt | 24 +++++++++++++++++++-----\n diffcore.h | 2 +-\n 2 files changed, 20 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex 2371262..f1ab4e7 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -206,10 +206,22 @@ endif::git-format-patch[]\n \tthe diff-patch output format. Non default number of\n \tdigits can be specified with `--abbrev=`.\n \n--B::\n-\tBreak complete rewrite changes into pairs of delete and create.\n-\n--M::\n+-B[]::\n+-B/::\n+\tBreak complete rewrite changes into pairs of delete and\n+\tcreate. When `n` and/or `m` are specified, they give threshold\n+\t(as a percentage of changed content) above which a change is\n+\tconsidered as complete rewrite. `n` is a threshold on the\n+\tsimilarity index (i.e. amount of addition/deletions compared\n+\tto the file's size). For example, `-B90%` means git will\n+\tdetect a rewrite if more than 90% of the file's content have\n+\tbeen modified. `m` is a threshold on the disimilarity index\n+\t(i.e. amount of deletions from the old version). A rewrite is\n+\tconsidered when both thresholds are reached. When either `n`\n+\tor `m` is not specified, the default applies (`n` = 50% and\n+\t`m` = 60%). See linkgit:gitdiffcore[7] for more details.\n+\n+-M[]::\n ifndef::git-log[]\n \tDetect renames.\n endif::git-log[]\n@@ -218,9 +230,11 @@ ifdef::git-log[]\n \tFor following files across renames while traversing history, see\n \t`--follow`.\n endif::git-log[]\n+\tIf `n` is specified, it has the same meaning as for `-B`.\n \n--C::\n+-C[]::\n \tDetect copies as well as renames. See also `--find-copies-harder`.\n+\tIf `n` is specified, it has the same meaning as for `-B`.\n \n ifndef::git-format-patch[]\n --diff-filter=[ACDMRTUXB*]::\ndiff --git a/diffcore.h b/diffcore.h\nindex 491bea0..fed9b15 100644\n--- a/diffcore.h\n+++ b/diffcore.h\n@@ -18,7 +18,7 @@\n #define MAX_SCORE 60000.0\n #define DEFAULT_RENAME_SCORE 30000 /* rename/copy similarity minimum (50%) */\n #define DEFAULT_BREAK_SCORE 30000 /* minimum for break to happen (50%) */\n-#define DEFAULT_MERGE_SCORE 36000 /* maximum for break-merge to happen 60%) */\n+#define DEFAULT_MERGE_SCORE 36000 /* maximum for break-merge to happen (60%) */\n \n #define MINIMUM_BREAK_SIZE 400 /* do not break a file smaller than this */\n \n-- \n1.7.2.1.10.g5cb67a\n"},{"id":"146964","messageId":"7vsk2wlvxv.fsf@alter.siamese.dyndns.org","threadId":"24550","inReplyTo":"1280747527-30444-1-git-send-email-Matthieu.Moy@imag.fr","subject":"Re: [PATCH v2] Document -B[/], -M and -C variants of -B, -M and -C","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-08-02T18:18:52Z","receivedAt":"2010-08-02T18:18:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Matthieu Moy writes:\n\n> These options take an optional argument, but this optional argument was\n> not documented.\n>\n> While we're there, fix a typo in a comment in diffcore.h.\n>\n> Signed-off-by: Matthieu Moy \n> ---\n> Here's a new version. I've eliminated \"line\" from the wording. I'm\n> still not sure I'm technically correct, especially about the\n> interaction between \"n\" and \"m\" (the \"A rewrite is considered when\n> both thresholds are reached par of the patch).\n\nI think they are technically correct, but I doubt diff-options.txt is a\nplace to be more technically correct than to be useful to the end users.\n\nWhat does an end user want to know from the list of options?\n\n> +-B[]::\n> +-B/::\n> +\tBreak complete rewrite changes into pairs of delete and\n> +\tcreate. When `n` and/or `m` are specified, they give threshold\n> +\t(as a percentage of changed content) above which a change is\n> +\tconsidered as complete rewrite. `n` is a threshold on the\n> +\tsimilarity index (i.e. amount of addition/deletions compared\n> +\tto the file's size). For example, `-B90%` means git will\n> +\tdetect a rewrite if more than 90% of the file's content have\n> +\tbeen modified. `m` is a threshold on the disimilarity index\n> +\t(i.e. amount of deletions from the old version). A rewrite is\n> +\tconsidered when both thresholds are reached. When either `n`\n> +\tor `m` is not specified, the default applies (`n` = 50% and\n> +\t`m` = 60%). See linkgit:gitdiffcore[7] for more details.\n\nAfter reading this, we know that with magic numbers given to -B, we can\n\"break\" changes into \"pairs of delete and create\". What does it mean in\nthe practical terms? That is a lot more essential information than how\nthe magic numbers affect the decision to break or not break. The user\ndoes not get a motivation to help git \"break\" a pair from the above.\n\n The -B option serves two purposes.\n\n It affects the way a change that amounts to a total rewrite of a file\n not as a series of deletion and insertion mixed together with a very\n few lines that happen to match textually as the context, but as a\n single deletion of everything old followed by a single insertion of\n everything new, and the number controls this aspect of the -B\n option (defaults to 60%). `-B/70%` specifies that less than 30% of\n the original should remain in the result for git to consider it a\n total rewrite (i.e. otherwise the resulting patch will be a series of\n deletion and insertion mixed together with context lines).\n\n When used with -M, a totally-rewritten file is also considered as the\n source of a rename (usually -M only considers a file that disappeared\n as the source of a rename), and the number controls this aspect of\n the -B option (defaults to 50%). `-B20%` specifies that a change with\n addition and deletion compared to 20% or more of the file's size are\n eligible for being picked up as a possible source of a rename to\n another file.\n"},{"id":"147195","messageId":"vpqbp9hoxbd.fsf@bauges.imag.fr","threadId":"24550","inReplyTo":"7vsk2wlvxv.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH v2] Document -B[/], -M and -C variants of -B, -M and -C","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2010-08-05T16:09:58Z","receivedAt":"2010-08-05T16:09:58Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Junio C Hamano writes:\n\n> After reading this, we know that with magic numbers given to -B, we can\n> \"break\" changes into \"pairs of delete and create\". What does it mean in\n> the practical terms? That is a lot more essential information than how\n> the magic numbers affect the decision to break or not break. The user\n> does not get a motivation to help git \"break\" a pair from the above.\n>\n> The -B option serves two purposes.\n> [...]\n\nI like your version much more than mine. I took it with a bit of\nasciidoc reformatting.\n\nI detailed a bit more the -M case, so that users do not have to\nread the whole -B thing to understand -M. I'm citing the expression\n\"similarity index\" since it sometimes appears in the output of diff,\nhence, can help the user to match what's happening and the doc.\n\nNew version follows.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"147217","messageId":"1281024865-31780-1-git-send-email-Matthieu.Moy@imag.fr","threadId":"24550","inReplyTo":"vpqbp9hoxbd.fsf@bauges.imag.fr","subject":"[PATCH] Document -B[/], -M and -C variants of -B, -M and -C","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2010-08-05T16:14:25Z","receivedAt":"2010-08-05T16:14:25Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"These options take an optional argument, but this optional argument was\nnot documented.\n\nOriginal patch by Matthieu Moy, but documentation for -B mostly copied\nfrom the explanations of Junio C Hamano.\n\nWhile we're there, fix a typo in a comment in diffcore.h.\n\nSigned-off-by: Matthieu Moy \n---\n Documentation/diff-options.txt | 35 ++++++++++++++++++++++++++++++-----\n diffcore.h | 2 +-\n 2 files changed, 31 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex 2371262..eecedaa 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -206,10 +206,29 @@ endif::git-format-patch[]\n \tthe diff-patch output format. Non default number of\n \tdigits can be specified with `--abbrev=`.\n \n--B::\n-\tBreak complete rewrite changes into pairs of delete and create.\n-\n--M::\n+-B[][/]::\n+\tBreak complete rewrite changes into pairs of delete and\n+\tcreate. This serves two purposes:\n++\n+It affects the way a change that amounts to a total rewrite of a file\n+not as a series of deletion and insertion mixed together with a very\n+few lines that happen to match textually as the context, but as a\n+single deletion of everything old followed by a single insertion of\n+everything new, and the number `m` controls this aspect of the -B\n+option (defaults to 60%). `-B/70%` specifies that less than 30% of the\n+original should remain in the result for git to consider it a total\n+rewrite (i.e. otherwise the resulting patch will be a series of\n+deletion and insertion mixed together with context lines).\n++\n+When used with -M, a totally-rewritten file is also considered as the\n+source of a rename (usually -M only considers a file that disappeared\n+as the source of a rename), and the number `n` controls this aspect of\n+the -B option (defaults to 50%). `-B20%` specifies that a change with\n+addition and deletion compared to 20% or more of the file's size are\n+eligible for being picked up as a possible source of a rename to\n+another file.\n+\n+-M[]::\n ifndef::git-log[]\n \tDetect renames.\n endif::git-log[]\n@@ -218,9 +237,15 @@ ifdef::git-log[]\n \tFor following files across renames while traversing history, see\n \t`--follow`.\n endif::git-log[]\n+\tIf `n` is specified, it is a is a threshold on the similarity\n+\tindex (i.e. amount of addition/deletions compared to the\n+\tfile's size). For example, `-M90%` means git should consider a\n+\tdelete/add pair to be a rename if more than 90% of the file\n+\thasn't changed.\n \n--C::\n+-C[]::\n \tDetect copies as well as renames. See also `--find-copies-harder`.\n+\tIf `n` is specified, it has the same meaning as for `-M`.\n \n ifndef::git-format-patch[]\n --diff-filter=[ACDMRTUXB*]::\ndiff --git a/diffcore.h b/diffcore.h\nindex 491bea0..fed9b15 100644\n--- a/diffcore.h\n+++ b/diffcore.h\n@@ -18,7 +18,7 @@\n #define MAX_SCORE 60000.0\n #define DEFAULT_RENAME_SCORE 30000 /* rename/copy similarity minimum (50%) */\n #define DEFAULT_BREAK_SCORE 30000 /* minimum for break to happen (50%) */\n-#define DEFAULT_MERGE_SCORE 36000 /* maximum for break-merge to happen 60%) */\n+#define DEFAULT_MERGE_SCORE 36000 /* maximum for break-merge to happen (60%) */\n \n #define MINIMUM_BREAK_SIZE 400 /* do not break a file smaller than this */\n \n-- \n1.7.2.1.30.g18195\n"}]}