finish the merge section

Author: schacon

book/07-git-tools/sections/advanced-merging.asc

@@ -476,17 +476,6 @@ index 0399cd5,59727f0..e1d0799
   hello()
 ----
 
-==== Other Types of Merges
-
-* Subtree (bring back deleted section?)
-* Octopus
-* Squash (git merge --squash)
-* Verify Sigs / Sign Merge
-* Recursive Options
-  - Ours / Theirs
-  - Ignore-space
-
-
 [[_undoing_merges]]
 ==== Undoing Merges
 
@@ -572,3 +561,61 @@ 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` is fully merged.
+
+==== Other Types of Merges
+
+So far we've covered the normal merge of two branches, normally handled with what is called the ``recursive'' strategy of merging. There are other ways to merge branches together however. Let's cover a few of them quickly.
+
+===== Our or Theirs Preference
+
+First of all, there is another useful thing we can do with the normal ``recursive'' mode of merging. We've already seen the `ignore-all-space` and `ignore-space-change` options which are passed with a `-X` but we can also tell Git to favor one side or the other when it sees a conflict.
+
+By default, when Git sees a conflict between two branches being merged, it will add merge conflict markers into your code and mark the file as conflicted and let you resolve it. If you would prefer for Git to simply choose a specific side and ignore the other side instead of letting you manually merge the conflict, you can pass the `merge` command either a `-Xours` or `-Xtheirs`.
+
+If Git sees this, it will not add conflict markers. Any differences that are mergable, it will merge. Any differences that conflict, it will simply choose the side you specify in whole, including binary files.
+
+If we go back to the ``hello world'' example we were using before, we can see that merging in our branch causes conflicts.
+
+[source,shell]
+----
+$ git merge mundo
+Auto-merging hello.rb
+CONFLICT (content): Merge conflict in hello.rb
+Resolved 'hello.rb' using previous resolution.
+Automatic merge failed; fix conflicts and then commit the result.
+----
+
+However if we run it with `-Xours` or `-Xtheirs` it does not.
+
+[source,shell]
+----
+$ git merge -Xours mundo
+Auto-merging hello.rb
+Merge made by the 'recursive' strategy.
+ hello.rb | 2 +-
+ test.sh  | 2 ++
+ 2 files changed, 3 insertions(+), 1 deletion(-)
+ create mode 100644 test.sh
+----
+
+In that case, instead of getting conflict markers in the file with ``hello mundo'' on one side and ``hola world'' on the other, it will simply pick ``hola world''. However, all the other non-conflicting changes on that branch are merged successfully in.
+
+This option can also be passed to the `git merge-file` command we saw earlier by running something like `git merge-file --ours` for individual file merges.
+
+If you want to do something like this but not have Git even try to merge changes from the other side in, there is a more draconian option, which is the ``ours'' merge _strategy_. This is different from the ``ours'' recursive merge _option_.
+
+This will basically do a fake merge. It will record a new merge commit with both branches as parents, but it will not even look at the branch you're merging in. It will simply record as the result of the merge the exact code in your current branch.
+
+[source,shell]
+----
+$ git merge -s ours mundo
+Merge made by the 'ours' strategy.
+$ git diff HEAD HEAD~
+$
+----
+
+You can see that there is no difference between the branch we were on and the result of the merge.
+
+This can often be useful to basically trick Git into thinking that a branch is already merged when doing a merge later on. For example, say you branched off a ``release'' branch and have done some work on it that you will want to merge back into your ``master'' branch at some point. In the meantime some bugfix on ``master'' needs to be backported into your `release` branch. You can merge the bugfix branch into the `release` branch and also `merge -s ours` the same branch into your `master` branch (even though the fix is already there) so when you later merge the `release` branch again, there are no conflicts from the bugfix.
+
+include::sections/subtree-merges.asc[]

book/07-git-tools/sections/subtree-merges.asc

@@ -1,33 +1,24 @@
-=== Subtree Merging
-
-Now that you’ve seen the difficulties of the submodule system, let’s look at an alternate way to solve the same problem.
-When Git merges, it looks at what it has to merge together and then chooses an appropriate merging strategy to use.
-If you’re merging two branches, Git uses a _recursive_ strategy.
-If you’re merging more than two branches, Git picks the _octopus_ strategy.
-These strategies are automatically chosen for you because the recursive strategy can handle complex three-way merge situations – for example, more than one common ancestor – but it can only handle merging two branches.
-The octopus merge can handle multiple branches but is more cautious to avoid difficult conflicts, so it’s chosen as the default strategy if you’re trying to merge more than two branches.
-
-However, there are other strategies you can choose as well.
-One of them is the _subtree_ merge, and you can use it to deal with the subproject issue.
-Here you’ll see how to do the same rack embedding as in the last section, but using subtree merges instead.
+===== Subtree Merging
 
 The idea of the subtree merge is that you have two projects, and one of the projects maps to a subdirectory of the other one and vice versa.
-When you specify a subtree merge, Git is smart enough to figure out that one is a subtree of the other and merge appropriately – it’s pretty amazing.
+When you specify a subtree merge, Git is often smart enough to figure out that one is a subtree of the other and merge appropriately.
+
+We'll go through an example of adding a seperate project into an existing project and then merging the code of the second into a subdirectory of the first.
 
-You first add the Rack application to your project.
-You add the Rack project as a remote reference in your own project and then check it out into its own branch:
+First, we'll add the Rack application to our project.
+We'll add the Rack project as a remote reference in our own project and then check it out into its own branch:
 
 [source,shell]
 ----
-$ git remote add rack_remote git@github.com:schacon/rack.git
+$ git remote add rack_remote https://github.com/rack/rack
 $ git fetch rack_remote
 warning: no common commits
 remote: Counting objects: 3184, done.
 remote: Compressing objects: 100% (1465/1465), done.
 remote: Total 3184 (delta 1952), reused 2770 (delta 1675)
 Receiving objects: 100% (3184/3184), 677.42 KiB | 4 KiB/s, done.
 Resolving deltas: 100% (1952/1952), done.
-From git@github.com:schacon/rack
+From https://github.com/rack/rack
  * [new branch]      build      -> rack_remote/build
  * [new branch]      master     -> rack_remote/master
  * [new branch]      rack-0.4   -> rack_remote/rack-0.4
@@ -37,7 +28,7 @@ Branch rack_branch set up to track remote branch refs/remotes/rack_remote/master
 Switched to a new branch "rack_branch"
 ----
 
-Now you have the root of the Rack project in your `rack_branch` branch and your own project in the `master` branch.
+Now we have the root of the Rack project in our `rack_branch` branch and our own project in the `master` branch.
 If you check out one and then the other, you can see that they have different project roots:
 
 [source,shell]
@@ -51,28 +42,30 @@ $ ls
 README
 ----
 
-You want to pull the Rack project into your `master` project as a subdirectory.
-You can do that in Git with `git read-tree`.
+This is sort of a strange concept. Not all the branches in your repository actually have to be branches of the same project. It's not common, because it's rarely helpful, but it's fairly easy to have branches contain completely different histories.
+
+In this case, we want to pull the Rack project into our `master` project as a subdirectory.
+We can do that in Git with `git read-tree`.
 You’ll learn more about `read-tree` and its friends in <<_git_internals>>, but for now know that it reads the root tree of one branch into your current staging area and working directory.
-You just switched back to your `master` branch, and you pull the `rack` branch into the `rack` subdirectory of your `master` branch of your main project:
+We just switched back to your `master` branch, and we pull the `rack` branch into the `rack` subdirectory of our `master` branch of our main project:
 
 [source,shell]
 ----
 $ git read-tree --prefix=rack/ -u rack_branch
 ----
 
-When you commit, it looks like you have all the Rack files under that subdirectory – as though you copied them in from a tarball.
-What gets interesting is that you can fairly easily merge changes from one of the branches to the other.
-So, if the Rack project updates, you can pull in upstream changes by switching to that branch and pulling:
+When we commit, it looks like we have all the Rack files under that subdirectory – as though we copied them in from a tarball.
+What gets interesting is that we can fairly easily merge changes from one of the branches to the other.
+So, if the Rack project updates, we can pull in upstream changes by switching to that branch and pulling:
 
 [source,shell]
 ----
 $ git checkout rack_branch
 $ git pull
 ----
 
-Then, you can merge those changes back into your master branch.
-You can use `git merge -s subtree` and it will work fine; but Git will also merge the histories together, which you probably don’t want.
+Then, we can merge those changes back into our `master` branch.
+We can use `git merge -s subtree` and it will work fine; but Git will also merge the histories together, which we probably don’t want.
 To pull in the changes and prepopulate the commit message, use the `--squash` and `--no-commit` options as well as the `-s subtree` strategy option:
 
 [source,shell]
@@ -83,10 +76,12 @@ Squash commit -- not updating HEAD
 Automatic merge went well; stopped before committing as requested
 ----
 
-All the changes from your Rack project are merged in and ready to be committed locally.
+All the changes from the Rack project are merged in and ready to be committed locally.
 You can also do the opposite – make changes in the `rack` subdirectory of your master branch and then merge them into your `rack_branch` branch later to submit them to the maintainers or push them upstream.
 
-To get a diff between what you have in your `rack` subdirectory and the code in your `rack_branch` branch – to see if you need to merge them – you can’t use the normal `diff` command.
+This gives us a way to have a workflow somewhat similar to the submodule workflow without using submodules. We can keep branches with other related projects in our repository and subtree merge them into our project occasionally. It is nice in some ways, for example all the code is committed to a single place. However, it has other drawbacks in that it's a bit more complex and easier to make mistakes in reintegrating changes or accidentally pushing a branch into an unrelated repository.
+
+Another slightly weird thing is that to get a diff between what you have in your `rack` subdirectory and the code in your `rack_branch` branch – to see if you need to merge them – you can’t use the normal `diff` command.
 Instead, you must run `git diff-tree` with the branch you want to compare to:
 
 [source,shell]