tomrea.uk

Git Submodules

Git submodules are not the most intuitive.

This is a quick cookbook for common use cases.

Add Submodule

Add a submodule to a project:

git submodule add https://github.com/thomasmarkrea/test-submodule.git

Switch Version (Tag/Commit)

Switch to a certain version of the submodule code:

cd test-submodule/
git checkout v1

cd ..
git add .
git commit -m 'Switch submodule to v1'

If the version required was released after the submodule was added, a fetch is needed:

cd test-submodule/
git fetch
git checkout v2

cd ..
git add .
git commit -m 'Switch submodule to v2'

If the version isn’t tagged, the commit sha-1 can be used:

cd test-submodule/
git fetch
git checkout 916712fc7771ba5cb22915150e0facfd265d2d37

cd ..
git add .
git commit -m 'Switch submodule to v3 [WIP]'

Switch to Latest Commit

Switch to the latest commit on the submodule master branch:

cd test-submodules/
git pull origin master

cd ..
git add .
git commit -m 'Switch submodule to latest commit'

Cloning a Project with Submodules

After cloning a project that includes submodules they must be initiated before they can be used:

git clone https://github.com/thomasmarkrea/test-submodule-project.git
git submodule update --init

Git’s own submodule documentation: