Submodules and Subtrees
Sometimes a project genuinely depends on another Git repository's source code directly — a shared internal library, a vendored dependency without a package manager, or a design-system repo consumed by multiple frontends. Git offers two distinct mechanisms to compose repositories this way: submodules, which keep the embedded repository as a separate, independently-versioned entity linked by a commit pointer, and subtrees, which merge the external repository's history (or a snapshot of it) directly into your own repository's history. They solve the same high-level problem — reusing code across repos — with very different tradeoffs around complexity, discoverability, and history ownership.
Cricket analogy: A franchise needing a specialist fielding-drill program can either keep it run by the partner academy and just reference their current syllabus version, or fully absorb the drills into their own training manual — same goal of shared expertise, different ownership tradeoffs.
How submodules work
A submodule is registered in a .gitmodules file at the root of the parent repo, mapping a path to a remote URL and branch. Internally, the parent repository doesn't store the submodule's files — it stores a special 'gitlink' entry that is simply the exact commit SHA the submodule should be checked out to. This means the parent repo and the submodule remain two entirely separate Git histories; cloning the parent with a plain git clone leaves submodule directories empty until you run git submodule update --init --recursive. Updating a submodule to a newer commit and committing that change in the parent is a two-step, explicit process — which is precise but easy for teammates to forget, often producing confusing 'my submodule folder is empty' or 'wrong commit checked out' issues.
Cricket analogy: A club's roster sheet lists a loaned player's parent club and exact loan terms, but the pitch stays empty of that player until the loan paperwork is formally processed — the loanee's own match history stays entirely with the parent club, separate from this team's record.
# Add a submodule
$ git submodule add https://github.com/example-org/shared-ui-kit.git libs/ui-kit
$ git commit -m "Add shared-ui-kit as a submodule"
# Cloning a repo that has submodules
$ git clone https://github.com/example-org/storefront.git
$ cd storefront
$ git submodule update --init --recursive
# or, in one step:
$ git clone --recurse-submodules https://github.com/example-org/storefront.git
# Pull the latest changes from a submodule's own remote
$ cd libs/ui-kit
$ git checkout main && git pull
$ cd ../..
$ git status
Changes not staged for commit:
modified: libs/ui-kit (new commits)
$ git add libs/ui-kit
$ git commit -m "Bump shared-ui-kit to latest main"
# git subtree, by contrast, embeds history directly — no .gitmodules, no separate clone step
$ git subtree add --prefix=libs/ui-kit https://github.com/example-org/shared-ui-kit.git main --squash
$ git subtree pull --prefix=libs/ui-kit https://github.com/example-org/shared-ui-kit.git main --squashHow subtrees differ
git subtree, instead of storing a pointer, actually merges the external repository's files and (optionally, with --squash, a single squashed commit of) its history into a subdirectory of the parent repo. There's no .gitmodules file, no second checkout step, and no risk of an 'empty folder' after clone — everything is just present, because it's genuinely part of the parent's own commit history. The tradeoff is that the parent repository grows to contain the vendored code's full history (unless squashed), and pushing changes back upstream to the original library repo (git subtree push) is more cumbersome and less commonly done than with submodules, where contributing back is just a normal commit-and-push inside the submodule's own clone.
Cricket analogy: Instead of loaning a player, a club can fully sign and absorb an academy player, folding their entire (or condensed) youth history into the senior squad's own record — no separate paperwork, no risk of an empty roster slot, but the club's records grow, and a later return transfer is more awkward than recalling a loan.
A simple way to decide: if you need contributors to easily push fixes back to the upstream library and want a hard, versioned boundary, prefer submodules. If you mainly want to vendor code once (or occasionally sync a snapshot) and want the simplicity of everything being 'just there' after a clone, prefer subtrees.
Forgetting git submodule update --init --recursive after cloning or pulling is the most common submodule mistake — the submodule directory silently exists but is empty or stuck at a stale commit, which can cause builds to fail in ways that look unrelated to submodules at all.
- Submodules store a commit-pointer (gitlink) to a separate repository; the parent and child histories stay distinct.
- Cloning a repo with submodules requires an explicit init/update step or --recurse-submodules.
- Subtrees merge the external repository's files (and optionally squashed history) directly into the parent's history.
- Submodules make contributing changes back upstream simpler; subtrees make cloning and onboarding simpler.
- Use .gitmodules to configure submodule paths, URLs, and branches for a project.
- Choose submodules for hard version boundaries with active upstream contribution; choose subtrees for simple vendoring.
Practice what you learned
1. What does the parent repository actually store for a Git submodule?
2. Why might a submodule folder appear empty right after cloning a parent repository?
3. How does `git subtree` fundamentally differ from `git submodule` in what it stores?
4. Which approach generally makes it easier to push local fixes back to the upstream library's own repository?
5. What flag can be used with `git subtree add` or `pull` to avoid importing the entire external history?
Was this page helpful?
You May Also Like
Remotes Explained
A remote is a named reference to another copy of a repository, usually hosted elsewhere, that Git uses to synchronize commits, branches, and tags between machines.
Monorepos vs Polyrepos
Compare storing all projects in a single monorepo versus many independent polyrepos, and the tradeoffs each makes around tooling, ownership, and history.
Push, Pull, and Fetch
Push, pull, and fetch are the three commands that move commits between your local repository and a remote — understanding exactly what each does (and doesn't do) prevents most everyday Git confusion.
The Git Object Model
A deep dive into how Git stores data internally as blobs, trees, commits, and tags — the content-addressable database underlying every Git operation.
Related Reading
Related Study Notes in Software Engineering
Browse all study notesMicroservices Study Notes
Software Architecture · 30 topics
Software EngineeringTesting & TDD Study Notes
Software Testing · 30 topics
Software EngineeringDesign Patterns Study Notes
Software Design · 30 topics
Software EngineeringSoftware Engineering Study Notes
Python · 75 topics
Software EngineeringSystem Design Study Notes
Architecture · 46 topics