Git submodules let you include one Git repository inside another. This is useful when you want to incorporate external code while keeping it in its own repository.

Common Use Case

You have a website repository, but you want a portion of it (like documentation or a handbook) to be publicly editable on GitHub, separate from the main private repository.

Adding a Submodule

First, if you have existing content in the folder where you want the submodule:

rm -rf content/handbook
git commit -m "Remove handbook folder for submodule"

Then add the submodule:

git submodule add https://github.com/username/handbook

The submodule is now tracked in your repository.

How Submodules Work

When you add a submodule:

1. Git clones the submodule repository
2. Creates a .gitmodules file tracking the submodule URL
3. Tracks which commit of the submodule your project uses

Your main repository doesn’t contain the submodule’s files—just a reference to a specific commit.

Deployment

Many deployment platforms (like Netlify) automatically detect and clone submodules when building your site.

Working with Submodules Locally

Submodules aren’t automatically symlinked. For local development, you might want to create a symlink to your local copy of the submodule:

# From within the content folder
ln -s ../../../dev/handbook/

Tell Git to stop tracking changes to this symlinked folder:

git update-index --skip-worktree content/handbook

To restore tracking later:

git update-index --no-skip-worktree content/handbook

Cloning a Repository with Submodules

When cloning a repository that has submodules:

git clone --recurse-submodules https://github.com/username/repo

Or if you already cloned without submodules:

git submodule init
git submodule update

Updating Submodules

To update a submodule to its latest commit:

cd submodule-folder
git pull origin main
cd ..
git add submodule-folder
git commit -m "Update submodule to latest"

Or update all submodules at once:

git submodule update --remote

Submodule Commands Reference

Command	Description
git submodule add <url>	Add a new submodule
git submodule init	Initialize submodules after cloning
git submodule update	Fetch submodule contents
git submodule update --remote	Update to latest remote commits
git submodule status	Show submodule status

When to Use Submodules

Good use cases:

• Sharing code between multiple projects
• Including third-party libraries you want to version control
• Making part of a private repo publicly editable
• Separating concerns between different teams

Alternatives:

• Package managers (npm, pip, etc.) for dependencies
• Monorepos if you want everything in one repository
• Git subtrees for simpler embedding (though with different tradeoffs)

Submodules add complexity, so use them when you genuinely need separate repositories that reference each other.

Lessons in this unit:

0:	Introduction
1:	Working with Remotes
2:	Squashing Commits
3:	Rebase vs Merge
4:	Git Bisect for Debugging
5:	Git Worktrees
6:	▶︎ Git Submodules
7:	Understanding Detached HEAD
8:	Managing Secrets in Git
9:	Git Workflows and Best Practices
10:	How to push to 2 repositories at the same time and keep them in sync
11:	How to update a Git branch from another branch
12:	Git, detached HEAD
13:	Trigger deploys on Netlify with submodules
14:	A Git Cheat Sheet
15:	Git, squashing vs not squashing
16:	An incomplete list of great Git tutorials
17:	Git, what if you forgot to add a file to a commit?
18:	Git workflow to manage work on multiple branches
19:	How to setup the Git SSH keys