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] – created dregadmantisbt: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 ====== ====== 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.txt · Last modified: 2014/04/30 13:00 by dregad

Driven by DokuWiki