How to manage submodules

managing-submodules.md

Git Submodules

Notes on how to work with submodules. superproject here would be commcare-hq root.

Get changes from remote

git checkout master
git pull origin master

Next: Tell git to register and checkout the proper commits in submodules. Commits are pulled into submodules in detached HEAD state.

git submodule update --init

Next: Pull commits into master branch of submodules.

git submodule foreach --recursive 'git checkout master; git pull origin master'

Make changes to a submodule

Make some changes
cd submodule_a
git commit -am"Made changes in submodule."
git push # Must push submodules before superproject.
cd .. # Into commcare-hq repo root.
git commit -am"Updated submodule_a with some stuff."
git push

Gotchas

• Don't use a slash after a submodule when git adding (from the superproject):
  git add submodule_b/ # Don't do this.

Git will think you want to delete the submodule and add all the files in the submodule directory.

• It's not safe to run git submodule update if you've made changes within a submodule. They will be silently overwritten.

Make changes
cd submodule
git commit ...
cd commcare-hq
git submodule update

You'll lose your changes (as git will check out the submodule commit that the superproject told it to (not your most recent changes). Can you recover from this?

References

https://git.wiki.kernel.org/index.php/GitSubmoduleTutorial#Gotchas http://stackoverflow.com/questions/5828324/update-git-submodule

You'll lose your changes (as git will check out the submodule commit that the superproject told it to (not your most recent changes). Can you recover from this?

Yes. Your subproject is a git repo like any other, so if you have changes to make there, do so, then commit them. They will be changes to that sub repo. The parent repo specifies a specific commit in each submodule, so if you run git submodule update, it will go into each submodule and check out that commit. To recover from this, you can go back into the repo and manually check out the desired commit.

Many of us use some variation of this script in our regular workflow. Here, pull-latest-master will pull everything down to your machine, even commits beyond what is referenced in the root repository. I use this only to expressly update the submodules. More generally, code-update aims to line up your local code state to what's currently reflected on master. This is what you should use before checking out a new branch to work on a change.

Note that code-update calls git submodule update --recursive. This is so you don't have that pesky notification that submodules have changes when you run git status. You should only add and commit a submodule change when you are expressly trying to reference new code in the submodule. This can happen in two main situations:

1. You made changes in the main repo that depend on changes you also made in a submodule.
2. You are updating submodules in preparation for a deploy.