Chapter 3 polish

book/05-distributed-git/1-distributed-git.asc

@@ -1,3 +1,4 @@
+[[_distributed_git]]
 == Distributed Git
 
 Now that you have a remote Git repository set up as a point for all the developers to share their code, and you’re familiar with basic Git commands in a local workflow, you’ll look at how to utilize some of the distributed workflows that Git affords you.

book/07-git-tools/1-git-tools.asc

@@ -1798,6 +1798,92 @@ Or, to compare what is in your `rack` subdirectory with what the `master` branch
 $ git diff-tree -p rack_remote/master
 ----
 
+[[_undoing_merges]]
+==== Undoing Merges
+
+Now that you know how to create a merge commit, you'll probably make some by mistake.
+One of the great things about working with Git is that it's okay to make mistakes, because it's possible (and in many cases easy) to fix them.
+
+Merge commits are no different.
+Let's say you started work on a topic branch, accidentally merged it into `master`, and now your commit history looks like this:
+
+.Accidental merge commit
+image::images/undomerge-start.png[Accidental merge commit.]
+
+There are two ways to approach this problem, depending on what your desired outcome is.
+
+===== Fix the references
+
+If the unwanted merge commit only exists on your local repository, the easiest and best solution is to move the branches so that they point where you want them to.
+In most cases, if you follow the errant `git merge` with `git reset --merge ORIG_HEAD`, this will reset the branch pointers so they look like this:
+
+.History after `git reset --merge`
+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:
+
+. Move the branch HEAD points to.
+  In this case, we want to move `master` to where it was before the merge commit (`C6`).
+. Make the index look like HEAD.
+. 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; the short version is that 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
+
+If moving the branch pointers around isn't going to work for you, Git gives you the option of making a new commit which undoes all the changes from an existing one.
+Git calls this operation a ``revert'', and in this particular scenario, you'd invoke it like this:
+
+[source,shell]
+----
+$ git revert -m 1 HEAD
+[master b1d8379] Revert "Merge branch 'topic-branch'"
+----
+
+The `-m 1` flag indicates which parent is the ``mainline'' and should be kept.
+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`.]
+
+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.
+
 === Notes
 
 === Bundle