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 https://github.com/fire1ce/3os.org 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 https://github.com/fire1ce/3os.org 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 https://github.com/fire1ce/3os.org

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

Support us