Git Submodules Cheat Sheet

Git submodules let you include an entire Git repository inside another one as a subdirectory. They’re handy when you want to keep related projects organized but still separate. From my experience, I am putting up this set of commands for managing submodules in your workflow.

Adding a Submodule to an Existing Repository

If you already have a main repository and want to bring in a new submodule, follow these steps:

cd /path/to/main-repo
git submodule add <repository-url> <submodule-path>
git add .gitmodules <submodule-path>
git commit -m "Added submodule <name>"

This adds the submodule to your main repo, and commits the necessary files so everything is tracked properly.

Cloning a Repository with Submodules

When you clone a project that uses submodules, you can automatically pull them in like this:

git clone --recurse-submodules <repository-url>

Initializing and Updating Submodules After Cloning

If you’ve already cloned the main repository but didn’t bring along the submodules, run:

git submodule init
git submodule update

This sets up your submodules locally and fetches their content.

Updating Submodules to Latest Changes

To ensure your submodule is up to date with changes from its original repository:

cd <submodule-path>
git pull origin <branch>
cd ..
git add <submodule-path>
git commit -m "Updated submodule <name>"

Then your main repository will reflect the newest state of your submodule.

Updating All Submodules

If you’ve got multiple submodules and want them all up to date, this command is a timesaver:

git submodule update --remote
git add <submodule-path>
git commit -m "Updated all submodules"

Pushing Changes in a Submodule

When you make changes within a submodule, you have to commit and push in two places: inside the submodule itself, then in the main repository to record the updated reference.

cd <submodule-path>
git add <files>
git commit -m "Your message"
git push origin <branch>
cd ..
git add <submodule-path>
git commit -m "Updated submodule reference"
git push origin <branch>

Removing a Submodule

If you no longer need a submodule, use these steps to remove it cleanly:

git config -f .gitmodules --remove-section submodule.<submodule-path>
git rm -r <submodule-path>
git config --remove-section submodule.<submodule-path>
git commit -m "Removed submodule <name>"
rm -rf .git/modules/<submodule-path>

Checking Submodule Status

Need a quick look at the state of your submodules? Just run:

git submodule status

Running Commands in All Submodules

If you want to run the same command in every submodule, this is your friend:

git submodule foreach <command>

Fetching and Merging Changes from Submodules

To grab the latest changes and merge them directly into your local submodule:

cd <submodule-path>
git fetch origin
git merge origin/<branch>
cd ..
git add <submodule-path>
git commit -m "Merged changes from submodule"

Reinitializing Submodules

Should you ever need to start fresh (for example, if something got messed up in your local submodule config):

git submodule deinit -f <submodule-path>
git submodule update --init

Cloning and Automatically Initializing Submodules

If you haven’t yet cloned the main repository, you can grab everything in one line:

git clone --recurse-submodules <repository-url>

Pulling Changes and Updating Submodules Automatically

To fetch updates from your main repo and submodules together:

git pull --recurse-submodules

Untracking a Submodule Without Deleting Files

If you want to stop tracking the submodule in Git but keep its actual files locally:

git rm --cached <submodule-path>

Happy coding!