[PATCH 3/3 v2] Documentation: add "git bisect replace" documentation
Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
---
Documentation/git-bisect.txt | 63 ++++++++++++++++++++++++++++++++++++++++++
1 files changed, 63 insertions(+), 0 deletions(-)
diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt
index c7981ef..3cb98b9 100644
--- a/Documentation/git-bisect.txt
+++ b/Documentation/git-bisect.txt
@@ -24,6 +24,7 @@ on the subcommand:
git bisect visualize
git bisect replay <logfile>
git bisect log
+ git bisect replace <rev> [<rev>]
git bisect run <cmd>...
This command uses 'git-rev-list --bisect' to help drive the
@@ -186,6 +187,68 @@ $ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 --
# v2.6.20-rc4 and v2.6.20-rc1 are good
------------
+Bisect replace
+~~~~~~~~~~~~~~
+
+This subcommand should be used when you have a branch or a part of a
+branch that isn't easily bisectable because of a bug that has been
+fixed latter.
+
+We suppose that a bug as been introduced at some point, say A, and
+that it has been fixed latter at another point, say B, but that
+between these points the code is not easily testable because of the
+bug, so it's not easy to bisect between these points.
+
+In this case you can create a branch starting at the parent of A, say
+O, that has a fixed history. In this fixed history for example, there
+could be first a commit C that is the result of squashing A and B
+together and then all the commits between A and B that have been cherry
+picked.
+
+For example, let's say the commits between A and B are X1, X2, ... Xn
+and they have been cherry picked after C as Y1, Y2, ... Yn:
+
+------------
+ C--Y1--Y2--...--Yn
+ /
+...--O--A--X1--X2--...--Xn--B--...
+------------
+
+By design, the last cherry picked commit (Yn) should point to the same
+tree as commit B.
+
+So in this case you can say:
+
+------------
+$ git bisect replace B Yn
+------------
+
+and commit B will be tagged with a special name like:
+"bisect-replace-with-Yn"
+
+(A branch that points to commit Yn will also be created with a name
+like: "bisect-replace-B")
+
+When bisecting, each commit with one of those tags will be grafted so
+that its parents will be replaced by the commit specified in the tag.
+
+In the example above, that means that instead of the above graph, the
+following graph will be bisected:
+
+------------
+ C--Y1--Y2--...--Yn
+ / \
+...--O B--...
+------------
+
+This means that the bisections on this branch may be much easier
+because the bug introduced by commit A and fixed by commit B will not
+annoy you anymore.
+
+As the branches and tags created by "git bisect replace" can be shared
+between developers, this feature might be especially usefull on big
+projects where many people often bisect the same code base.
+
Bisect run
~~~~~~~~~~
--
1.6.0.3.528.gad674
Christian Couder <chriscool@tuxfamily.org>