User Tools

Site Tools


mantisbt:git_submodules

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
mantisbt:git_submodules [2014/04/30 11:53]
dregad Added section: Updating a Library's submodule
mantisbt:git_submodules [2014/04/30 13:00]
dregad Added update from within the submodule (phpmailer example)
Line 1: Line 1:
-====== Working with Git Submodules in MantisBT ====== 
- 
-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]]. 
- 
-This setup requires some special handling when initializing the repository and when switching branches, 
-especially to and from branches which do not (yet) have submodules in it. 
- 
-The purpose of this page is to provide basic instructions to easily deal with commonly encountered issues. 
- 
- 
-===== Initializing the Repository ===== 
- 
-This is covered in the MantisBT Developer's Guide. 
- 
-@@@TODO - update this when updated docbook has been merged with Master. Until then, copy/paste follows: 
- 
-===== Switching Branches ===== 
- 
- 
-==== With Submodules --> No Submodules ==== 
- 
-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 ==== 
- 
-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> 
- 
- 
- 
-==== Submodules --> Submodules ==== 
- 
-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. 
- 
-The examples 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 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> 
-    * 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 
-</code> 
-  - 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> 
  
mantisbt/git_submodules.txt ยท Last modified: 2014/04/30 13:00 by dregad