User Tools

  • Logged in as: anonymous (anonymous)
  • Log Out

Site Tools


mantisbt:git_submodules

Differences

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

Link to this comparison view

Next revision
Previous revision
mantisbt:git_submodules [2013/08/30 13:15]
dregad created
mantisbt:git_submodules [2014/04/30 13:00] (current)
dregad Added update from within the submodule (phpmailer example)
Line 1: Line 1:
 ====== Working with Git Submodules in MantisBT ====== ====== Working with Git Submodules in MantisBT ======
- 
-//​work-in-progress...//​ 
  
 Some [[3rdpartycode|3rd party libraries]] are stored and maintained in the MantisBT repository ​ 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, This setup requires some special handling when initializing the repository and when switching branches,
Line 19: Line 17:
  
 ===== Switching Branches ===== ===== Switching Branches =====
 +
  
 ==== With Submodules --> No Submodules ==== ==== With Submodules --> No Submodules ====
Line 24: Line 23:
 Checking out a branch with Submodules when the current branch does not have them. 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 ==== ==== No Submodules --> With Submodules ====
Line 30: Line 77:
 Checking out a branch without Submodules when the current branch has them. 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. 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  
 + ​9346d288a1b7f7a50cc35b6a0e56d29e9d000ecf adodb (v5.19-6-g9346d28) 
 + ​75a4e5595c0dfcb2e2e1e41b9ba2282828d3f292 disposable (release-2.0.0-3-g75a4e55) 
 + ​cb771839899d9f6be9f1268b986c30327ff1199b phpmailer (v5.2.6-2-gcb77183) 
 + ​41beaddd279c695aacb63407e2c98b04b7eaff51 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>​ 
  
mantisbt/git_submodules.1377882935.txt.gz · Last modified: 2013/08/30 19:12 (external edit)