{"thread":{"id":"16172","subject":"[PATCH 3/3 v2] Documentation: add \"git bisect replace\" documentation","startedAt":"2008-11-04T17:35:29Z","lastAt":"2008-11-04T17:35:29Z","messageCount":1,"participants":["Christian Couder"],"isPatch":true,"patchVersion":2,"patchTotal":3},"messages":[{"id":"94908","messageId":"20081104183529.505c8f90.chriscool@tuxfamily.org","threadId":"16172","inReplyTo":null,"subject":"[PATCH 3/3 v2] Documentation: add \"git bisect replace\" documentation","fromName":"Christian Couder","fromEmail":"chriscool@tuxfamily.org","sentAt":"2008-11-04T17:35:29Z","receivedAt":"2008-11-04T17:35:29Z","isPatch":true,"sender":{"key":"christian.couder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/208954?v=4"},"body":"Signed-off-by: Christian Couder <chriscool@tuxfamily.org>\n---\n Documentation/git-bisect.txt |   63 ++++++++++++++++++++++++++++++++++++++++++\n 1 files changed, 63 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt\nindex c7981ef..3cb98b9 100644\n--- a/Documentation/git-bisect.txt\n+++ b/Documentation/git-bisect.txt\n@@ -24,6 +24,7 @@ on the subcommand:\n  git bisect visualize\n  git bisect replay <logfile>\n  git bisect log\n+ git bisect replace <rev> [<rev>]\n  git bisect run <cmd>...\n \n This command uses 'git-rev-list --bisect' to help drive the\n@@ -186,6 +187,68 @@ $ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 --\n                    # v2.6.20-rc4 and v2.6.20-rc1 are good\n ------------\n \n+Bisect replace\n+~~~~~~~~~~~~~~\n+\n+This subcommand should be used when you have a branch or a part of a\n+branch that isn't easily bisectable because of a bug that has been\n+fixed latter.\n+\n+We suppose that a bug as been introduced at some point, say A, and\n+that it has been fixed latter at another point, say B, but that\n+between these points the code is not easily testable because of the\n+bug, so it's not easy to bisect between these points.\n+\n+In this case you can create a branch starting at the parent of A, say\n+O, that has a fixed history. In this fixed history for example, there\n+could be first a commit C that is the result of squashing A and B\n+together and then all the commits between A and B that have been cherry\n+picked.\n+\n+For example, let's say the commits between A and B are X1, X2, ... Xn\n+and they have been cherry picked after C as Y1, Y2, ... Yn:\n+\n+------------\n+       C--Y1--Y2--...--Yn\n+      /\n+...--O--A--X1--X2--...--Xn--B--...\n+------------\n+\n+By design, the last cherry picked commit (Yn) should point to the same\n+tree as commit B.\n+\n+So in this case you can say:\n+\n+------------\n+$ git bisect replace B Yn\n+------------\n+\n+and commit B will be tagged with a special name like:\n+\"bisect-replace-with-Yn\"\n+\n+(A branch that points to commit Yn will also be created with a name\n+like: \"bisect-replace-B\")\n+\n+When bisecting, each commit with one of those tags will be grafted so\n+that its parents will be replaced by the commit specified in the tag.\n+\n+In the example above, that means that instead of the above graph, the\n+following graph will be bisected:\n+\n+------------\n+       C--Y1--Y2--...--Yn\n+      /                  \\\n+...--O                    B--...\n+------------\n+\n+This means that the bisections on this branch may be much easier\n+because the bug introduced by commit A and fixed by commit B will not\n+annoy you anymore.\n+\n+As the branches and tags created by \"git bisect replace\" can be shared\n+between developers, this feature might be especially usefull on big\n+projects where many people often bisect the same code base.\n+\n Bisect run\n ~~~~~~~~~~\n \n-- \n1.6.0.3.528.gad674\n"}]}