git submodule merges, remove subtree

Author: schacon

book/07-git-tools/sections/submodules.asc

@@ -511,7 +511,138 @@ To https://github.com/chaconinc/MainProject
 
 As you can see there, Git went into the DbConnector module and pushed it before pushing the main project. If that submodule push fails for some reason, the main project push will also fail.
 
-With these tools, submodules can be a fairly simple and effective method for developing on several related but still separate projects simultaneously.
+===== Merging Submodule Changes
+
+If you change a submodule reference at the same time as someone else, you may run into some problems. That is, if the submodule histories have diverged and are committed to diverging branches in a superproject, it may take a bit of work for you to fix.
+
+If one of the commits is a direct ancestor of the other (a fast-forward merge), then Git will simply choose the latter for the merge, so that works fine.
+
+Git will not attempt even a trivial merge for you, however. If the submodule commits diverge and need to be merged, you will get something that looks like this:
+
+[source,shell]
+----
+$ git pull
+remote: Counting objects: 2, done.
+remote: Compressing objects: 100% (1/1), done.
+remote: Total 2 (delta 1), reused 2 (delta 1)
+Unpacking objects: 100% (2/2), done.
+From https://github.com/chaconinc/MainProject
+   9a377d1..eb974f8  master     -> origin/master
+Fetching submodule DbConnector
+warning: Failed to merge submodule DbConnector (merge following commits not found)
+Auto-merging DbConnector
+CONFLICT (submodule): Merge conflict in DbConnector
+Automatic merge failed; fix conflicts and then commit the result.
+----
+
+So basically what has happened here is that Git has figured out that the two branches record points in the submodule's history that are divergent and need to be merged. It explains it as ``merge following commits not found'', which is confusing but we'll explain why that is in a bit.
+
+To solve the problem, you need to figure out what state the submodule should be in. Strangely, Git doesn't really give you much information to help out here, not even the SHAs of the commits of both sides of the history. Fortunately, it's simple to figure out.  If you run `git diff` you can get the SHAs of the commits recorded in both branches you were trying to merge.
+
+[source,shell]
+----
+$ git diff
+diff --cc DbConnector
+index eb41d76,c771610..0000000
+--- a/DbConnector
++++ b/DbConnector
+----
+
+So, in this case, `eb41d76` is the commit in our submodule that *we* had and `c771610` is the commit that upstream had. If we go into our submodule directory, it should already be on `eb41d76` as the merge would not have touched it. If for whatever reason it's not, you can simply create and checkout a branch pointing to it.
+
+What is important is the SHA of the commit from the other side. This is what you'll have to merge in and resolve. You can either just try the merge with the SHA directly, or you can create a branch for it and then try to merge that in. We would suggest the latter, even if only to make a nicer merge commit message.
+
+So, we will go into our submodule directory, create a branch based on that second SHA from `git diff` and manually merge.
+
+[source,shell]
+----
+$ cd DbConnector
+
+$ git rev-parse HEAD
+eb41d764bccf88be77aced643c13a7fa86714135
+
+$ git branch try-merge c771610
+(DbConnector) $ git merge try-merge
+Auto-merging src/main.c
+CONFLICT (content): Merge conflict in src/main.c
+Recorded preimage for 'src/main.c'
+Automatic merge failed; fix conflicts and then commit the result.
+----
+
+We got an actual merge conflict here, so if we resolve that and commit it, then we can simply update the main project with the result.
+
+[source,shell]
+----
+$ vim src/main.c <1>
+$ git add src/main.c
+$ git commit -am 'merged our changes'
+Recorded resolution for 'src/main.c'.
+[master 9fd905e] merged our changes
+
+$ cd .. <2>
+$ git diff <3>
+diff --cc DbConnector
+index eb41d76,c771610..0000000
+--- a/DbConnector
++++ b/DbConnector
+@@@ -1,1 -1,1 +1,1 @@@
+- Subproject commit eb41d764bccf88be77aced643c13a7fa86714135
+ -Subproject commit c77161012afbbe1f58b5053316ead08f4b7e6d1d
+++Subproject commit 9fd905e5d7f45a0d4cbc43d1ee550f16a30e825a
+$ git add DbConnector <4>
+
+$ git commit -m "Merge Tom's Changes" <5>
+[master 10d2c60] Merge Tom's Changes
+----
+
+<1> First we resolve the conflict
+<2> Then we go back to the main project directory
+<3> We can check the SHAs again
+<4> Resolve the conflicted submodule entry
+<5> Commit our merge
+
+It can be a bit confusing, but it's really not very hard.
+
+Interestingly, there is another case that Git handles.
+If a merge commit exists in the submodule directory that contains **both** commits in it's history, Git will suggest it to you as a possible solution. It sees that at some point in the submodule project, someone merged branches containing these two commits, so maybe you'll want that one.
+
+This is why the error message from before was ``merge following commits not found'', because it could not do *this*. It's confusing because who would expect it to **try** to do this?
+
+If it does find a single acceptable merge commit, you'll see something like this:
+
+[source,shell]
+----
+$ git merge origin/master
+warning: Failed to merge submodule DbConnector (not fast-forward)
+Found a possible merge resolution for the submodule:
+ 9fd905e5d7f45a0d4cbc43d1ee550f16a30e825a: > merged our changes
+If this is correct simply add it to the index for example
+by using:
+
+  git update-index --cacheinfo 160000 9fd905e5d7f45a0d4cbc43d1ee550f16a30e825a "DbConnector"
+
+which will accept this suggestion.
+Auto-merging DbConnector
+CONFLICT (submodule): Merge conflict in DbConnector
+Automatic merge failed; fix conflicts and then commit the result.
+----
+
+What it's suggesting that you do is to update the index like you had run `git add`, which clears the conflict, then commit. You probably shouldn't do this though. You can just as easily go into the submodule directory, see what the difference is, fast-forward to this commit, test it properly, and then commit it.
+
+[source,shell]
+----
+$ cd DbConnector/
+$ git merge 9fd905e
+Updating eb41d76..9fd905e
+Fast-forward
+
+$ cd ..
+$ git add DbConnector
+$ git commit -am 'Fast forwarded to a common submodule child'
+----
+
+This accomplishes the same thing, but at least this way you can verify that it works and you have the code in your submodule directory when you're done.
+
 
 ==== Submodule Tips
 
@@ -710,10 +841,4 @@ Then, when you switch back, you get an empty `CryptoLibrary` directory for some
 
 It's important to note that submodules these days keep all their Git data in the top project's `.git` directory, so unlike much older versions of Git, destorying a submodule directory won't lose any commits or branches that you had.
 
-
-
-==== Alternatives to Submodules
-
-===== Subtree
-
-git-subtree
+With these tools, submodules can be a fairly simple and effective method for developing on several related but still separate projects simultaneously.