Git Submodule Cheatsheet

Kenichi Shibata
Jun 21 · 3 min read
Photo by Yancy Min on Unsplash

Clone repo with submodules included

git clone <url> --recursive

Create a submodule in a currently existing repo

If you want to update the path of the submodule (i.e. where the submodule will be stored on your local clone use

Please note this will change the entry in the .gitmodule file and you may not want to commit it and most of the time you will only be using git submodule update --init since it will be more consistent with the SCM

Check Submodules status

Git submodules are actually using the commit rev of another repository and you will need to push these changes to your main repo if you want to updgrade them.

These are proven when checking out the plumbing of the rev which points to the submodule

Pull a submodule after cloning a repository

Update the repository url on .git/config from .gitmodules also

Checkout a specific branch on submodule

By default your submodule will check out the specific rev of a repository during the time of its commit to the main repository. If you want to use a branch in the submodule (for example stable branches) you will have to add branch on .gitmodules file and use

If you didn’t specify any branches and used --remote it will automatically fetch master branch. If you are developing the submodule as well you can use either --merge or --rebase as convenience

Developing In Submodule

You can use a special push if you want to update your submodule from your main repo

Also you can use a foreach comamand

Finally you can use these alias to improve your workflow


The Must-Read Publication for Aspiring Developers & DevOps Enthusiasts

Kenichi Shibata

Written by

Git Ninja! Linux Nerd. Javascript evangelist. AWS Architect. Software engineer. Kubernetes Mentor and Architect



The Must-Read Publication for Aspiring Developers & DevOps Enthusiasts