Share code between projects with Git submodules
Short answer: Git submodules let one repository include another at a specific commit, which suits code you share between projects, such as a design system, a set of email templates or an internal library used by your website and your app. They're precise but easy to trip over: a normal clone leaves submodule folders empty, and updating means committing a new pointer in the parent. Use git clone --recurse-submodules, document the update routine, and consider a package registry instead if the shared code changes often.
When teams reach for submodules
Small businesses that build several things often end up with code that belongs in more than one place:
- A shared component library used by the marketing site and the customer portal.
- Brand assets and email templates used by several apps.
- A pricing or calculation module that the website, the mobile app's backend and an internal tool must agree on.
- Configuration or infrastructure scripts reused across client projects at an agency.
Copying files between repositories works until the copies drift apart. A submodule keeps one source of truth and lets each project choose exactly which version it uses.
How submodules work
Git's documentation describes a submodule as a repository embedded inside another repository, with its own history; the repository it's embedded in is called the superproject. The superproject doesn't store the submodule's files. It stores a pointer to one exact commit of the submodule, plus an entry in a .gitmodules file naming its URL and path.
That design is the source of both the benefits and the surprises. Each project pins a precise version of the shared code, so an update to the library can't silently break the website. But nothing updates automatically either.
Adding a submodule
From the parent repository, run git submodule add <url> <path>, for example adding your component library at vendor/components. Commit the new .gitmodules file and the submodule folder entry. Anyone looking at the parent's history now sees exactly which library commit is in use.
Cloning a project that has submodules
The most common confusion: someone clones the parent and finds the submodule folders empty. A plain clone doesn't fetch them. The Pro Git book explains that passing --recurse-submodules to git clone will automatically initialise and update each submodule, including nested ones.
If you've already cloned, run git submodule update --init --recursive to fetch them. Put this in your project's README and your CI configuration, because build servers hit the same problem.
Updating shared code
When the library gains a fix you want:
- Go into the submodule folder and fetch, or run
git submodule update --remotefrom the parent to move it to the latest commit on its tracked branch. - Test the parent project with the new version.
- Commit in the parent. The commit records the new submodule pointer, so everyone else gets that version when they update.
- Teammates run
git submodule updateafter pulling to bring their copy in line.
If someone forgets step 4, they'll see the submodule as "modified" in git status, because their checked-out library commit doesn't match the pointer.
Working inside a submodule
The Pro Git book warns that after an update, the submodule is left in a "detached HEAD" state, with no local branch tracking changes. If you edit files there and commit, those commits aren't on any branch and are easy to lose.
To make changes to the shared code:
- Check out a branch inside the submodule first (
git switch mainor a feature branch). - Commit and push the submodule's changes to its own repository.
- Then commit the updated pointer in the parent.
Pushing the parent before pushing the submodule leaves teammates with a pointer to a commit that doesn't exist on the server. git push --recurse-submodules=check makes Git refuse that mistake.
Settings that save headaches
git config submodule.recurse truemakes many commands, including pull and checkout, update submodules automatically.git diff --submoduleshows the list of submodule commits between two pointers, which is more useful than a bare hash change in reviews.- In CI, enable your provider's submodule checkout option and give the build access to the submodule's repository if it's private.
When a package is the better choice
Submodules suit shared code that changes occasionally and must be pinned precisely. If the shared code changes weekly, is consumed by many projects, or is written in a language with a good package manager, publishing it as a versioned package is usually smoother. Each project upgrades with one dependency bump, and version numbers say more than commit hashes.
A monorepo, where all projects live in one repository, is the other alternative. It removes cross-repository coordination entirely, at the cost of a bigger repository and shared tooling.
A worked example
Picture a hypothetical Chicago design studio that builds websites for clients and keeps a shared library of accessible form components. Copy-pasting the components had left a dozen slightly different versions in client projects. The studio moved the components into their own repository and added it as a submodule to each new client site, pinned to a tagged release. When a fix to the date-picker landed, each site updated its pointer on its own schedule, after testing, and the project README listed the clone and update commands.
FAQ
Do submodules work with private repositories?
Yes, but everyone and every build server needs access to each private submodule as well as the parent.
Can a submodule follow a branch automatically?
You can record a branch in .gitmodules and use git submodule update --remote, but the parent still stores a specific commit until you commit the change.
How do I remove a submodule?
Use git rm on the submodule path, commit, and remove leftover configuration if your Git version doesn't do it for you.
Are submodules supported by Git hosts?
Major hosts display them as links to the exact commit in the other repository.
If you're juggling shared code across several projects, tell us how your repositories are set up and we'll suggest a structure.