First draft of undoing merges, figures

Author: ben

en/book/03-git-branching/chapter3.asc

@@ -418,14 +418,15 @@ image::images/undomerge-reset.png[History after `git reset --merge`.]
 We covered `reset` back in <<_reset>>, so it shouldn't be too hard to figure out what's going on here.
 Here's a quick refresher: `reset --hard` usually goes through three steps:
 
-1. Move the ref that `HEAD` points to. In this case, we want to move `master` to where it was before the merge commit (`C4`)
+1. Move the ref that `HEAD` points to. In this case, we want to move `master` to where it was before the merge commit (`C6`)
 2. Make the index look like `HEAD`.
 3. Make the working directory look like the index.
 
 In the case of `--merge`, Git is extra careful with steps 2 and 3 to preserve any changes you've made in the working directory or the index, but otherwise works as though this were a `--hard` reset.
 
 The downside of this approach is that it's rewriting history, which can be prolematic with a shared repository.
 Check out <<_rebase_peril>> for more on what can happen, but if other people have the commits you're rewriting, you should probably avoid `reset`.
+This approach also won't work if any other commits have been created since the merge; moving the refs would effectively lose those changes.
 
 ===== Reverse the commit
 
@@ -434,18 +435,48 @@ Git calls this operation a ``revert'', and in this particular scenario, you'd in
 
 [source,shell]
 ----
-$ git revert -m 1
+$ git revert -m 1 HEAD
+[master b1d8379] Revert "Merge branch 'topic-branch'"
 ----
 
 The `-m 1` flag tells Git which parent to keep.
-When you invoke a merge into `HEAD` (`git merge experiment`), the new commit has two parents: the first one is `HEAD` (`C4`), and the second is the tip of the branch being merged in (`C3`).
-In this case, we want to undo all the changes introduced by merging in parent #2 (`C3`), while keeping all the content from parent #1 (`C4`).
+When you invoke a merge into `HEAD` (`git merge topic-branch`), the new commit has two parents: the first one is `HEAD` (`C6`), and the second is the tip of the branch being merged in (`C4`).
+In this case, we want to undo all the changes introduced by merging in parent #2 (`C4`), while keeping all the content from parent #1 (`C6`).
 
 The history with the revert commit looks like this:
 
 .History after `git revert -m 1`
+image::images/undomerge-revert.png[History after `git revert -m 1`.]
 
-Take a look at <<_undoing>> for more information on Git's various methods of undoing things.
+The new commit `^M` has exactly the same contents as `C6`, so starting from here it's as if the merge never happened, except that the now-unmerged commits are still in `HEAD`'s history.
+Git will get confused if you try to merge `topic-branch` into `master` again:
+
+[source,shell]
+----
+$ git merge topic-branch
+Already up-to-date.
+----
+
+There's nothing in `topic-branch` that isn't already reachable from `master`.
+What's worse, if you add work to `topic-branch` and merge again, Git will only bring in the changes _since_ the reverted merge:
+
+.History with a bad merge
+image::images/undomerge-revert2.png[History with a bad merge.]
+
+The best way around this is to un-revert the original merge, since now you want to bring in the changes that were reverted out, *then* create a new merge commit:
+
+[source,shell]
+----
+$ git revert M
+[master 09f0126] Revert "Revert "Merge branch 'topic-branch'""
+$ git merge topic-branch
+----
+
+.History after re-merging a reverted merge
+image::images/undomerge-revert3.png[History after re-merging a reverted merge.]
+
+In this example, `M` and `^M` cancel out.
+`^^M` effectively merges in the changes from `C3` and `C4`, and `C8` merges in the changes from `C7`, so now `topic-branch` is fully merged.
 
 
 === Branch Management