Git Submodules in Practice: Managing a Multi-Repo Project

Everyone tells you to avoid git submodules. The internet is full of horror stories about detached HEAD states, forgotten updates, and teammates who can’t clone the repo. I’m going to push back — submodules are the right tool for specific situations, and if you understand the mental model, they’re manageable.

I use submodules to manage a WordPress theme repo and a Next.js frontend repo under a shared parent. Here’s how it works.

When Submodules Make Sense

Use submodules when you have independently versioned repositories that need to be composed together, each with its own CI/CD pipeline and release cycle. They’re the wrong choice when your code is tightly coupled and changes frequently span both repos — use a monorepo with workspaces instead.

Setting Up Submodules

mkdir adzbyte.com && cd adzbyte.com
git init

git submodule add git@github.com:user/adzbyte-theme.git adzbyte-theme
git submodule add git@github.com:user/adzbyte-next.git adzbyte-next

git commit -m "Add theme and frontend submodules"

This creates a .gitmodules file mapping submodule paths to remote URLs. Each submodule directory is tracked as a pointer to a specific commit — not the contents of the repo.

The Mental Model

A submodule reference is a commit hash, not a branch. The parent says “use commit abc123 of that repo.” That means:

• Inside a submodule directory, you’re in a separate git repo
• The submodule starts in a detached HEAD state
• To make changes, check out a branch first
• The parent only updates its pointer when you explicitly tell it to

Day-to-Day Workflow

Cloning (first time):

git clone --recurse-submodules git@github.com:user/adzbyte.com.git

# Or if you already cloned without submodules
git submodule update --init --recursive

Pulling updates:

git pull
git submodule update --recursive

The git pull updates the parent’s pointer. The submodule update checks out the new commit. Forget the second step and your submodule stays on the old commit.

Updating a submodule to latest:

git submodule update --remote adzbyte-next
git add adzbyte-next
git commit -m "Update Next.js frontend to latest"

Common Pitfalls

1. Forgetting to push the submodule before the parent. Push the submodule first, then the parent. Otherwise the parent references a commit that doesn’t exist on the remote.

cd adzbyte-next
git push
cd ..
git add adzbyte-next
git commit -m "Update submodule pointer"
git push

2. Detached HEAD confusion. After git submodule update, you’re on a detached HEAD. Start making changes without checking out a branch and those commits are easy to lose.

3. Merge conflicts in submodule pointers. When two people update the same submodule to different commits, decide which commit wins, cd into the submodule, check out that commit, and resolve in the parent.

Useful Git Config

# Show submodule changes in git status
git config --global status.submoduleSummary true

# Always clone recursively
git config --global submodule.recurse true

# Show submodule diff summary
git config --global diff.submodule log

The submodule.recurse setting is the biggest quality-of-life improvement — git pull, git checkout, and other commands automatically update submodules.

vs. Monorepo

Submodules give you independent repos with coordinated versioning. Monorepos give you a single repo with shared tooling. Pick submodules when the repos are genuinely independent projects deployed together. Pick a monorepo when code is tightly coupled and you want shared CI and atomic cross-boundary commits.

For my setup — a WordPress theme with its own release pipeline and a Next.js frontend with its own deployment — submodules fit naturally. They keep each project’s history clean and let me version the combination separately from the parts.