Skip to content

Support us

Authors: fire1ce | Created: 2022-03-23 | Last update: 2022-03-24

Git Submodules Cheat Sheet

What is a Submodule?

Git submodules allow you to keep a git repository as a subdirectory of another git repository. Git submodules are simply a reference to another repository at a particular snapshot in time. Git submodules enable a Git repository to incorporate and track version history of external code.

Add a Submodule

You need to know the remote git repository url and where you want to place that it in your repository.

for example:

git submodule add path/to/submodule
git add .
git commit -m "adds submodule path/to/submodule"

Cloning A Project With Submodules

When you clone a repository that contains submodules there are a few extra steps to be taken.

for example:

git clone repo
cd repo
git submodule init
git submodule update

If you’re sure you want to fetch all submodules (and their submodules), you can also use this fancy one-liner:

git clone --recurse-submodules

Submodule Update

If you’re simply tracking the master or main branch for the submodule, you can suffice with a simple fetch and merge.

cd path/to/submodule
git fetch
git merge origin/master

If you’re in a hurry, you can streamline this for all submodules in your repo with:

git submodule update --remote --recursive

Commit this change to your own repo, so others are locked to this new version of the submodule as well.

Remove a submodule

  • Delete the relevant section from the .gitmodules file.
  • Stage the .gitmodules changes git add .gitmodules
  • Delete the relevant section from .git/config.
  • Run git rm --cached path_to_submodule (no trailing slash).
  • Run rm -rf .git/modules/path_to_submodule (no trailing slash).
  • Commit git commit -m "Removed submodule"
  • Delete the now untracked submodule files rm -rf path_to_submodule