User Tools

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

Site Tools


This is an old revision of the document!

Working with Git Submodules in MantisBT


Some 3rd party libraries are stored and maintained in the MantisBT repository using [[|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.

$ 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)

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.

$ 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

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

$ sed -rn "s/^.*path\s*=\s*(.*)$/\1/p" .gitmodules |xargs -I{} mv {} /tmp
$ git checkout NoSubmodules
Switched to branch 'NoSubmodules'

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)
    $ git submodule update
  • Restore the directories previously moved to /tmp back into the empty directories, e.g.
    sed -rn "s/^.*path\s*=\s*(.*)$/\1/p" .gitmodules |xargs -n 1 basename |xargs -I{} mv -v /tmp/{} library

No Submodules --> With Submodules

Checking out a branch without Submodules when the current branch has them.

$ git status
# On branch NoSubmodules
nothing to commit, working directory clean

$ git checkout WithSubmodules
M	library/adodb
M	library/phpmailer
Switched to branch 'WithSubmodules'


Use the following command to reset all Submodules to the state of their respective recorded commit:

git submodule foreach git checkout -- .

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:

$ git status
# On branch SubmodulesOld
nothing to commit, working directory clean

$ git checkout SubmodulesNew
M	library/adodb
Switched to a new branch 'SubmodulesNew'


Just update the submodule(s)…

$ git submodule update 
Submodule path 'library/adodb': checked out '<commit sha>'
mantisbt/git_submodules.1377906717.txt.gz · Last modified: 2013/08/30 20:30 (external edit)