Git submodule

03 May 2013

Git submodule is very useful and important when doing a huge project. However the mechanism is not clearly described in most of the online manuals:

1) Submodule Add

git submodule add git@github.com:yyang/repo submodule_path_here

This will log and register certain submodule in .gitmodules file. Registration is also triggered via git submodule init.

2) Submodule update

git submodule update

Such command will checkout certain version into the registered path.

However the version is locked through .git/modules/submodule_path_here/FETCH_HEAD during initial registration, and such update command will not fetch a new version, this command has similar effect as git checkout $certain_version.

3) Update version

We can either do:

cd submodule_path_here
git checkout master
git pull

Or do:

git submodule foreach git pull origin master

Both will update the version in FETCH_HEAD to the latest, and fetch the versions respectively. Such operation requires commit to update the repo.

4) Edits under submodules folder

Git will search for the nearest git repo - so whenever there’s a commit it will commit to submodule, very nice.

– Update Oct. 12, 2015 –

5) Tracking submodules branches

Accordint to this Stack Overflow post, the easiest way to implement submodule is to specify branch during submodule add:

[submodule "SubmoduleTestRepo"]
    path = SubmoduleTestRepo
    url = https://github.com/jzaccone/SubmoduleTestRepo.git
    branch = master

And to fix whatever matter, please refer this post: [http://stackoverflow.com/questions/1777854/git-submodules-specify-a-branch-tag/18799234#18799234]