[PATCH 3/9 v5] Documentation: add "git bisect replace" documentation

[PATCH 3/9 v5] Documentation: add "git bisect replace" documentation

[Christian Couder]

Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
---
 Documentation/git-bisect.txt |   61 ++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 61 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt
index 39034ec..be7518c 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,66 @@ $ 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 a special ref will be created that points to commit Yn. This ref
+will be named: "refs/replace/bisect/B"
+
+When bisecting, the refs in "refs/replace/bisect/" will be scanned and
+each ref named X found there and pointing to commit Y will be grafted
+so that X will only have Y as parent.
+
+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 refs 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.5.6.1.1657.g6a50