Differences

This shows you the differences between two versions of the page.

--- mantisbt:git_submodules [2013/08/30 13:15] – created dregad
+++ mantisbt:git_submodules [2014/04/30 13:00] (current) – Added update from within the submodule (phpmailer example) dregad
@@ Line 1: / Line 1: @@
 ====== Working with Git Submodules in MantisBT ======
-//work-in-progress...//
 Some [[3rdpartycode|3rd party libraries]] are stored and maintained in the MantisBT repository
-using [[http://git-scm.com/book/en/Git-Tools-Submodules|Git Submodules].
+using [[http://git-scm.com/book/en/Git-Tools-Submodules|Git Submodules]].
 This setup requires some special handling when initializing the repository and when switching branches,
@@ Line 19: / Line 17: @@
 ===== Switching Branches =====
 ==== With Submodules --> No Submodules ====
@@ Line 24: / Line 23: @@
 Checking out a branch with Submodules when the current branch does not have them.
-@@@
+<code>
+$ git status
+# On branch WithSubmodules
+nothing to commit, working directory clean
+$ git checkout NoSubmodules
+error: The following untracked working tree files would be overwritten by checkout:
+	(list of files)
+Aborting
+</code>
+**Solution 1**
+**WARNING**: this will cause the loss of all changes in any of the submodules that have not been pushed upstream.
+Only do this if you are sure that you don't have any pending modifications.
+First we force checkout to ignore changes, then we remove all untracked files.
+<code>
+$ git checkout --force NoSubmodules
+warning: unable to rmdir library/adodb: Directory not empty
+warning: unable to rmdir library/phpmailer: Directory not empty
+Switched to branch 'NoSubmodules'
+$ git clean --force
+Removing library/adodb/.gitattributes
+[...]
+Removing library/phpmailer/.gitignore
+</code>
+**Solution 2**
+This is slightly more complex but safer alternative, recommended if there are changes to be kept in the submodules.
+Move the submodules directory to a temporary location, e.g. ''/tmp''
+<code>
+$ sed -rn "s/^.*path\s*=\s*(.*)$/\1/p" .gitmodules |xargs -I{} mv {} /tmp
+$ git checkout NoSubmodules
+Switched to branch 'NoSubmodules'
+</code>
+When switching back from the older branch, the submodules directories will be empty. At that point you can either
+  * Update the submodules to reclone them (in which case earlier changes will be lost) <code>
+$ git submodule update</code>
+  * Restore the directories previously moved to ''/tmp'' back into the empty directories, e.g. <code>
+sed -rn "s/^.*path\s*=\s*(.*)$/\1/p" .gitmodules |xargs -n 1 basename |xargs -I{} mv -v /tmp/{} library
+</code>
 ==== No Submodules --> With Submodules ====
@@ Line 30: / Line 77: @@
 Checking out a branch without Submodules when the current branch has them.
-@@@
+<code>
+$ git status
+# On branch NoSubmodules
+nothing to commit, working directory clean
+$ git checkout WithSubmodules
+M	library/adodb
+M	library/phpmailer
+Switched to branch 'WithSubmodules'
+</code>
+**Solution**
+Use the following command to reset all Submodules to the state of their respective recorded commit:
+<code>
+git submodule foreach git checkout -- .
+</code>
@@ Line 37: / Line 101: @@
 Checking out a branch with Submodules when the current branch has the same submodules but pointing to a different commit.
-@@@
+For example, branch SubmodulesNew has an updated ADOdb library:
+<code>
+$ git status
+# On branch SubmodulesOld
+nothing to commit, working directory clean
+$ git checkout SubmodulesNew
+M	library/adodb
+Switched to a new branch 'SubmodulesNew'
+</code>
+**Solution**
+Just update the submodule(s)...
+<code>
+$ git submodule update
+Submodule path 'library/adodb': checked out '<commit sha>'
+</code>
+===== Updating a Library's submodule =====
+This section describes the process to update a submodule when a new version of a library has been released upstream.
+==== Updating via an external repository ====
+The example given here are for the ADOdb library, but the same logic should apply (possibly with some variations) to other submodules as well.
+We assume that you already have a local repository configured with the appropriate remotes (//upstream// for the library's official repository and //origin// for the MantisBT fork)
+  - Update the library's fork in the //mantisbt// Github organization
+    * Get the latest from upstream <code>
+cd /path/to/local/adodb
+git fetch upstream
+</code>
+    * Optional: update the //master// branch <code>
+git rebase upstream/master master
+</code>
+    * Update the branch <code>
+git checkout mantis-1.3
+git merge v5.19
+</code>
+    * Resolve any conflicts
+    * Push changes to the fork <code>
+git push origin --tags master mantis-1.3
+</code> Note that it's not strictly necessary to push the tags or the master branch. Having the tags allows a better description of the submodule's current commit when running ''git submodule'' (see example at the end of this section)
+  - Update the submodule
+    * Go to your local mantisbt repository and update it<code>
+cd /path/to/mantisbt
+git checkout master
+git pull
+</code>
+    * Go to the submodule's directory and checkout the branch <code>
+cd library/adodb
+git checkout mantis-1.3
+git pull
+cd ..
+</code>
+  - Update ''README.libs'' to reflect the new version
+  - Commit the changes <code>
+git commit -a
+</code>
+At this point, checking the submodules' status should give you a "clean" list , e.g. (notice no '+' sign in column 1)
+<code>
+$ git submodule
+d288a1b7f7a50cc35b6a0e56d29e9d000ecf adodb (v5.19-6-g9346d28)
+a4e5595c0dfcb2e2e1e41b9ba2282828d3f292 disposable (release-2.0.0-3-g75a4e55)
+ cb771839899d9f6be9f1268b986c30327ff1199b phpmailer (v5.2.6-2-gcb77183)
+beaddd279c695aacb63407e2c98b04b7eaff51 securimage (heads/mantis)
+</code>
+==== Updating from within the submodule ====
+It's worth mentioning that step 1 above can also be performed straight from the submodule itself (see example below for phpmailer), provided of course that the remotes (origin and upstream) have been properly configured.
+**WARNING**: if you update the submodule in-place, it is critical that you actually push the changes to //origin// otherwise the other developers will have an corrupted repository with missing commits when they pull the changes.
+  * Update the submodule from upstream <code>
+cd library/phpmailer
+git fetch upstream
+git rebase upstream/master master
+git checkout mantis
+git merge v5.2.7
+# Resolve conflicts
+</code>
+  * Push changes to the fork - **don't forget this step !**<code>
+git push origin --tags master mantis
+cd ..
+</code>
+  * Edit ''README.libs''
+  * Commit the changes <code>
+git commit -a
+</code>