{"thread":{"id":"23410","subject":"[PATCH 0/2 v2] Document update for 'git-blame' '-M' and '-C' option","startedAt":"2010-04-10T10:15:28Z","lastAt":"2010-04-11T18:13:30Z","messageCount":6,"participants":["Bo Yang","Junio C Hamano","Pete Harlan"],"isPatch":true,"patchVersion":2,"patchTotal":2},"messages":[{"id":"139141","messageId":"1270894530-6486-1-git-send-email-struggleyb.nku@gmail.com","threadId":"23410","inReplyTo":null,"subject":"[PATCH 0/2 v2] Document update for 'git-blame' '-M' and '-C' option","fromName":"Bo Yang","fromEmail":"struggleyb.nku@gmail.com","sentAt":"2010-04-10T10:15:28Z","receivedAt":"2010-04-10T10:15:28Z","isPatch":true,"sender":{"key":"struggleyb.nku@gmail.com","avatar":"https://avatars.githubusercontent.com/u/233030?v=4"},"body":"The second version of the patches.\n\nBo Yang (2):\n Add a basic idea section for git-blame.\n Change the description of '-M' and '-C' option.\n\n Documentation/blame-options.txt | 46 +++++++++++++++++++++++---------------\n Documentation/git-blame.txt | 35 ++++++++++++++++++++++++++++-\n 2 files changed, 62 insertions(+), 19 deletions(-)\n"},{"id":"139142","messageId":"1270894530-6486-2-git-send-email-struggleyb.nku@gmail.com","threadId":"23410","inReplyTo":"1270894530-6486-1-git-send-email-struggleyb.nku@gmail.com","subject":"[PATCH 1/2 v2] Add a basic idea section for git-blame.","fromName":"Bo Yang","fromEmail":"struggleyb.nku@gmail.com","sentAt":"2010-04-10T10:15:29Z","receivedAt":"2010-04-10T10:15:29Z","isPatch":true,"sender":{"key":"struggleyb.nku@gmail.com","avatar":"https://avatars.githubusercontent.com/u/233030?v=4"},"body":"Explain the basic idea about blame shifting with\n'-M' or '-C' given.\n\nThanks-to: Thomas Rast \nSigned-off-by: Bo Yang \n---\n Documentation/git-blame.txt | 35 ++++++++++++++++++++++++++++++++++-\n 1 files changed, 34 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt\nindex a27f439..3378665 100644\n--- a/Documentation/git-blame.txt\n+++ b/Documentation/git-blame.txt\n@@ -9,7 +9,7 @@ SYNOPSIS\n --------\n [verse]\n 'git blame' [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-p] [-w] [--incremental] [-L n,m]\n-\t [-S ] [-M] [-C] [-C] [-C] [--since=]\n+\t [-S ] [-M||] [-C||] [-C||] [-C||] [--since=]\n \t [ | --contents | --reverse ] [--] \n \n DESCRIPTION\n@@ -36,6 +36,39 @@ $ git log --pretty=oneline -S'blame_usage'\n ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output\n -----------------------------------------------------------------------------\n \n+\n+BASIC IDEA\n+----------\n+\n+This section briefly explains the basic idea behind 'git-blame'. You\n+do not have to understand it to use git-blame, but it helps in\n+understanding the `-M` and `-C` options. For the sake of simplicity,\n+we assume that history is linear.\n+\n+A call to `git-blame -- ` works as follows:\n+\n+- Assume all the lines' blame to initially.\n+\n+- Run git diff ^ and ignore all +/- lines. The unchanged\n+ lines are definitely from our parent, so pass the blame of the\n+ unchanged lines to parent.\n+\n+- For the +/- lines, take the blame if there are no `-M` or `-C`\n+ options given. \n+\n+- Repeat step 2~3 for all the remain lines which does not find\n+ a blame until all lines find its blame.\n+\n+If there are `-M` or `-C` given, the command will try to search for\n+same code of current lines and pass blame to it.\n+\n+With `-M`, this command detects same lines of the current blaming code\n+inside the current file. And it will shift the blame to the author of\n+the original lines instead of author of current blaming code. It does\n+the same for `-C` except that it will search across file boundary and\n+multiple commits.\n+\n+\n OPTIONS\n -------\n include::blame-options.txt[]\n-- \n1.7.0.2.273.gc2413.dirty\n"},{"id":"139143","messageId":"1270894530-6486-3-git-send-email-struggleyb.nku@gmail.com","threadId":"23410","inReplyTo":"1270894530-6486-1-git-send-email-struggleyb.nku@gmail.com","subject":"[PATCH 2/2 v2] Change the description of '-M' and '-C' option.","fromName":"Bo Yang","fromEmail":"struggleyb.nku@gmail.com","sentAt":"2010-04-10T10:15:30Z","receivedAt":"2010-04-10T10:15:30Z","isPatch":true,"sender":{"key":"struggleyb.nku@gmail.com","avatar":"https://avatars.githubusercontent.com/u/233030?v=4"},"body":"Both '-M' and '-C' option detect code moving and copying.\nThe difference between the two options is whether they\nsearch across file boundary.\n\nThanks-to: Thomas Rast \nSigned-off-by: Bo Yang \n---\n Documentation/blame-options.txt | 46 +++++++++++++++++++++++---------------\n 1 files changed, 28 insertions(+), 18 deletions(-)\n\ndiff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt\nindex 4833cac..d113f2e 100644\n--- a/Documentation/blame-options.txt\n+++ b/Documentation/blame-options.txt\n@@ -79,34 +79,44 @@ of lines before or after the line given by .\n \tof the --date option at linkgit:git-log[1].\n \n -M||::\n-\tDetect moving lines in the file as well. When a commit\n-\tmoves a block of lines in a file (e.g. the original file\n-\thas A and then B, and the commit changes it to B and\n-\tthen A), the traditional 'blame' algorithm typically blames\n-\tthe lines that were moved up (i.e. B) to the parent and\n-\tassigns blame to the lines that were moved down (i.e. A)\n-\tto the child commit. With this option, both groups of lines\n-\tare blamed on the parent.\n+\tDetect moving/copying lines in the file as well. Instead of\n+\ttaking blame for all '+' lines, attempt to find the same\n+\tlines 'in the same file' in the parent commit. If such a\n+\tmatch was found, shift the blame to these lines in the\n+\tparent. (This expends extra effort on the order of the size\n+\tof the file for every change.)\n++\n+The net effect is that if code is moved or copied within the file, the\n+lines are attributed to the original instead of the move/copy.\n +\n is optional but it is the lower bound on the number of\n alphanumeric characters that git must detect as moving\n within a file for it to associate those lines with the parent\n-commit.\n+commit. And the default value is 20.\n \n -C||::\n-\tIn addition to `-M`, detect lines copied from other\n-\tfiles that were modified in the same commit. This is\n-\tuseful when you reorganize your program and move code\n-\taround across files. When this option is given twice,\n-\tthe command additionally looks for copies from other\n-\tfiles in the commit that creates the file. When this\n-\toption is given three times, the command additionally\n-\tlooks for copies from other files in any commit.\n+\tLike `-M`, detect moving/copying lines between files as well.\n+\tInstead of taking blame for all '+' lines, attempt to find the same\n+\tlines across file boundary according to the number of given `-C`.\n+\tThis is useful when you reorganize your program and move/copy\n+\tcode around across files. When this option is given once, detect\n+\tlines moved/copied from other files that were modified in the\n+\tsame commit. (This expends extra effort on the order of\n+\t* for every change.) When this\n+\toption is given twice, the command additionally looks for moves/copies\n+\tfrom other files in the commit that creates this file. (This expends\n+\textra effort on the order of *\n+\tfor every change.) When this option is given three times, the\n+\tcommand additionally looks for moves/copies from other files\n+\tin any commit. (This expends extra effort on the order of\n+\t**\n+\tfor every change.)\n +\n is optional but it is the lower bound on the number of\n alphanumeric characters that git must detect as moving\n between files for it to associate those lines with the parent\n-commit.\n+commit. And the default value is 40. If there are different values\n+provided by different `-C` option, the last value will take effect finally.\n \n -h::\n --help::\n-- \n1.7.0.2.273.gc2413.dirty\n"},{"id":"139190","messageId":"7veiinw0bw.fsf@alter.siamese.dyndns.org","threadId":"23410","inReplyTo":"1270894530-6486-2-git-send-email-struggleyb.nku@gmail.com","subject":"Re: [PATCH 1/2 v2] Add a basic idea section for git-blame.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-04-10T19:53:55Z","receivedAt":"2010-04-10T19:53:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Bo Yang writes:\n\n> +With `-M`, this command detects same lines of the current blaming code\n> +inside the current file. And it will shift the blame to the author of\n> +the original lines instead of author of current blaming code. It does\n> +the same for `-C` except that it will search across file boundary and\n> +multiple commits.\n\nI grant you that the understanding what M/C options do by the end users\n(the target audience of the document) would improve if they understood the\nabove paragraph. And I know you thought the text leading to the above\nparagraph (omitted) would help them understand what this paragraph tells\nthem.\n\nBut I think we should try to do better. We can always say \"With a\ntechnical description of how it works internally, you can understand why\nthese options give you the behaviour you want\", but that should be the\nlast resort when we cannot give meaningful description without going into\nthe implementation details.\n\nIt may also help git hacker wannabes (not end users) to have more detailed\nand precise description of how the algorithm works in a separate document\nin the Documentation/technical/ area, but that is a separate issue.\n\nIf the goal is to help the end users use M/C options and understand the\noutput better, can't we take a more direct approach?\n\nIt doesn't really matter to them _why_ only B is blamed to the parent in\n\"A B\" -> \"B A\" movement without -M (and your \"BASIC IDEA\" section is too\nsketchy for readers to guess why, even if they wanted to learn the\nimplementation detail, which they typically don't).\n\nThings like:\n\n - they can use -M to annotate across block-of-lines swappage within a file;\n - use of -M adds cost --- it spends extra cycles;\n - similarly -C annotates across block-of-lines swappage between files;\n - use -f -C adds larger cost; ...\n\nare the only important things they want to know about, no?\n\n Documentation/blame-options.txt | 19 ++++++++++---------\n 1 files changed, 10 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt\nindex 4833cac..5d5ed37 100644\n--- a/Documentation/blame-options.txt\n+++ b/Documentation/blame-options.txt\n@@ -79,14 +79,15 @@ of lines before or after the line given by .\n \tof the --date option at linkgit:git-log[1].\n \n -M||::\n-\tDetect moving lines in the file as well. When a commit\n-\tmoves a block of lines in a file (e.g. the original file\n-\thas A and then B, and the commit changes it to B and\n-\tthen A), the traditional 'blame' algorithm typically blames\n-\tthe lines that were moved up (i.e. B) to the parent and\n-\tassigns blame to the lines that were moved down (i.e. A)\n-\tto the child commit. With this option, both groups of lines\n-\tare blamed on the parent.\n+\tDetect moved or copied lines within a file. When a commit\n+\tmoves or copies a block of lines (e.g. the original file\n+\thas A and then B, and the commit changes it to B and then\n+\tA), the traditional 'blame' algorithm notices only the\n+\thalf of the movement and typically blames the lines that were\n+\tmoved up (i.e. B) to the parent and assigns blame to the lines\n+\tthat were moved down (i.e. A) to the child commit. With this\n+\toption, both groups of lines are blamed on the parent by\n+\trunning extra passes of inspection.\n +\n is optional but it is the lower bound on the number of\n alphanumeric characters that git must detect as moving\n@@ -94,7 +95,7 @@ within a file for it to associate those lines with the parent\n commit.\n \n -C||::\n-\tIn addition to `-M`, detect lines copied from other\n+\tIn addition to `-M`, detect lines moved or copied from other\n \tfiles that were modified in the same commit. This is\n \tuseful when you reorganize your program and move code\n \taround across files. When this option is given twice,\n"},{"id":"139229","messageId":"y2l41f08ee11004101923j90709b65mee7c3defb6511246@mail.gmail.com","threadId":"23410","inReplyTo":"7veiinw0bw.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 1/2 v2] Add a basic idea section for git-blame.","fromName":"Bo Yang","fromEmail":"struggleyb.nku@gmail.com","sentAt":"2010-04-11T02:23:25Z","receivedAt":"2010-04-11T02:23:25Z","isPatch":true,"sender":{"key":"struggleyb.nku@gmail.com","avatar":"https://avatars.githubusercontent.com/u/233030?v=4"},"body":"Hi Junio,\n\nOn Sun, Apr 11, 2010 at 3:53 AM, Junio C Hamano wrote:\n> It doesn't really matter to them _why_ only B is blamed to the parent in\n> \"A B\" -> \"B A\" movement without -M (and your \"BASIC IDEA\" section is too\n> sketchy for readers to guess why, even if they wanted to learn the\n> implementation detail, which they typically don't).\n>\n> Things like:\n>\n>    - they can use -M to annotate across block-of-lines swappage within a file;\n>    - use of -M adds cost --- it spends extra cycles;\n>    - similarly -C annotates across block-of-lines swappage between files;\n>    - use -f -C adds larger cost; ...\n>\n> are the only important things they want to know about, no?\n\nI think all the four things above are mentioned in [PATCH 2/2 v2]\nmessage, it contains who should the command pass blame to and the\norder of the algorithm used. Would you please take a look at that\npatch?\n\nAnd the BASIC IDEA section just want to make a basic description about\nhow blame works briefly. If you thought that it is non-use for\nend-users, how about just discard it and make a more technical one at\ntechnical/git-blame.txt ?\nThanks!\n\nRegards!\nBo\n"},{"id":"139276","messageId":"4BC2114A.5080406@pcharlan.com","threadId":"23410","inReplyTo":"7veiinw0bw.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 1/2 v2] Add a basic idea section for git-blame.","fromName":"Pete Harlan","fromEmail":"pgit@pcharlan.com","sentAt":"2010-04-11T18:13:30Z","receivedAt":"2010-04-11T18:13:30Z","isPatch":true,"sender":{"key":"pgit@pcharlan.com","avatar":null},"body":"On 04/10/2010 12:53 PM, Junio C Hamano wrote:\n> Bo Yang writes:\n> \n>> +With `-M`, this command detects same lines of the current blaming code\n>> +inside the current file. And it will shift the blame to the author of\n>> +the original lines instead of author of current blaming code. It does\n>> +the same for `-C` except that it will search across file boundary and\n>> +multiple commits.\n> \n> I grant you that the understanding what M/C options do by the end users\n> (the target audience of the document) would improve if they understood the\n> above paragraph. And I know you thought the text leading to the above\n> paragraph (omitted) would help them understand what this paragraph tells\n> them.\n> \n> But I think we should try to do better. We can always say \"With a\n> technical description of how it works internally, you can understand why\n> these options give you the behaviour you want\", but that should be the\n> last resort when we cannot give meaningful description without going into\n> the implementation details.\n> \n> It may also help git hacker wannabes (not end users) to have more detailed\n> and precise description of how the algorithm works in a separate document\n> in the Documentation/technical/ area, but that is a separate issue.\n> \n> If the goal is to help the end users use M/C options and understand the\n> output better, can't we take a more direct approach?\n> \n> It doesn't really matter to them _why_ only B is blamed to the parent in\n> \"A B\" -> \"B A\" movement without -M (and your \"BASIC IDEA\" section is too\n> sketchy for readers to guess why, even if they wanted to learn the\n> implementation detail, which they typically don't).\n> \n> Things like:\n> \n> - they can use -M to annotate across block-of-lines swappage within a file;\n> - use of -M adds cost --- it spends extra cycles;\n> - similarly -C annotates across block-of-lines swappage between files;\n> - use -f -C adds larger cost; ...\n> \n> are the only important things they want to know about, no?\n> \n> Documentation/blame-options.txt | 19 ++++++++++---------\n> 1 files changed, 10 insertions(+), 9 deletions(-)\n> \n> diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt\n> index 4833cac..5d5ed37 100644\n> --- a/Documentation/blame-options.txt\n> +++ b/Documentation/blame-options.txt\n> @@ -79,14 +79,15 @@ of lines before or after the line given by .\n> \tof the --date option at linkgit:git-log[1].\n> \n> -M||::\n> -\tDetect moving lines in the file as well. When a commit\n> -\tmoves a block of lines in a file (e.g. the original file\n> -\thas A and then B, and the commit changes it to B and\n> -\tthen A), the traditional 'blame' algorithm typically blames\n> -\tthe lines that were moved up (i.e. B) to the parent and\n> -\tassigns blame to the lines that were moved down (i.e. A)\n> -\tto the child commit. With this option, both groups of lines\n> -\tare blamed on the parent.\n> +\tDetect moved or copied lines within a file. When a commit\n> +\tmoves or copies a block of lines (e.g. the original file\n> +\thas A and then B, and the commit changes it to B and then\n> +\tA), the traditional 'blame' algorithm notices only the\n\nThere's an extraneous \"the\" at the end of this line.\n\nOther than that everything you say here sounds like a good idea to me.\n\n--Pete\n\n> +\thalf of the movement and typically blames the lines that were\n> +\tmoved up (i.e. B) to the parent and assigns blame to the lines\n> +\tthat were moved down (i.e. A) to the child commit. With this\n> +\toption, both groups of lines are blamed on the parent by\n> +\trunning extra passes of inspection.\n> +\n> is optional but it is the lower bound on the number of\n> alphanumeric characters that git must detect as moving\n> @@ -94,7 +95,7 @@ within a file for it to associate those lines with the parent\n> commit.\n> \n> -C||::\n> -\tIn addition to `-M`, detect lines copied from other\n> +\tIn addition to `-M`, detect lines moved or copied from other\n> \tfiles that were modified in the same commit. This is\n> \tuseful when you reorganize your program and move code\n> \taround across files. When this option is given twice,\n"}]}