Lesson 20 of 30

Submodules and Monorepos

Q: Your team wants to share a design-system library across three separate frontend repos. Would you reach for Git submodules? Walk through the tradeoffs.

A strong answer covers: Explains that a submodule pins the parent repo to one exact commit of the child repo via a gitlink, not a copy of its files; Names the real-world pain: two-step commits (update submodule, then commit the new pointer in the parent), and easy-to-forget --recurse-submodules on clone; Presents the monorepo alternative and its tradeoff: atomic cross-project commits vs. losing independent versioning/access control and a larger single repo; Reaches a judgment call rather than treating one option as universally correct — depends on team size, coupling, and how often the shared code changes.

Submodules let one repo embed another at an exact commit. In practice, most teams find the coordination overhead isn't worth it — and reach for a monorepo instead.

15 min read

Check your understanding

Every option explains itself — why the right one is right, and why each wrong one is wrong. Miss one and it comes back later on a spaced-repetition schedule.

No quiz for this one — it's a practical topic

This topic is about judgment and practical tradeoffs more than a single right answer — a mock interview is the better way to test yourself on it.

Be interviewed on this →

Stuck? Ask the AI tutor

Hints without spoilers, and a plain explanation of why a wrong answer was wrong — answered only from this lesson. Free account, no card.

Interview questions on Submodules and Monorepos

What interviewers actually ask about this, and what a strong answer has to cover.

Your team wants to share a design-system library across three separate frontend repos. Would you reach for Git submodules? Walk through the tradeoffs.

A strong answer covers

Explains that a submodule pins the parent repo to one exact commit of the child repo via a gitlink, not a copy of its files
Names the real-world pain: two-step commits (update submodule, then commit the new pointer in the parent), and easy-to-forget --recurse-submodules on clone
Presents the monorepo alternative and its tradeoff: atomic cross-project commits vs. losing independent versioning/access control and a larger single repo
Reaches a judgment call rather than treating one option as universally correct — depends on team size, coupling, and how often the shared code changes

Likely follow-ups

If a teammate updates the submodule's code and pushes, but forgets to commit the pointer bump in the parent repo, what does everyone else actually experience?
What happens to CI if it clones the parent repo without initializing submodules?
At what point, in your experience or judgment, does the coordination overhead of submodules stop being worth it compared to just merging everything into one repo?

The plain-language idea

A submodule is a Git repository nested inside another Git repository, pinned to one specific commit. The parent repo doesn't store the submodule's files — it stores a pointer: "at this path, check out this exact commit of that other repo." This is how you share code across repos (a design-system package, a shared library) while keeping each one's own history and versioning independent.

A monorepo is the opposite approach to the same underlying problem — instead of splitting related code into separate repos and stitching them back together, you keep everything in one repo, one history, one set of commits touching multiple projects at once.

See it in a real thing: adding and updating a submodule

git submodule add https://github.com/acme/design-tokens.git packages/design-tokens

This clones design-tokens into packages/design-tokens/ and creates a .gitmodules file at the repo root:

[submodule "packages/design-tokens"]
	path = packages/design-tokens
	url = https://github.com/acme/design-tokens.git

Committing this doesn't commit the submodule's files — it commits a special "gitlink" entry that records the exact commit SHA the submodule is pinned to. git status on the parent repo shows the submodule as a single pending change, not a folder full of files.

Anyone freshly cloning the parent repo gets an empty packages/design-tokens/ folder unless they also initialize submodules:

git clone --recurse-submodules https://github.com/acme/main-app.git
# or, after a plain clone:
git submodule update --init --recursive

To pull in the submodule's latest upstream changes and bump the pin:

cd packages/design-tokens
git pull origin main
cd ../..
git add packages/design-tokens
git commit -m "chore: bump design-tokens to latest"

That last git add is committing the new pinned commit, not any file content — the parent repo now points at a different SHA of the child repo.

What people usually miss

Watch out

A submodule bump is a two-step commit, and forgetting the second step is the #1 submodule bug. You update the submodule's own code and commit inside it — but the parent repo still points at the old SHA until you separately git add and commit the pointer change in the parent. Someone else pulling the parent gets the old submodule content until that second commit lands.
Cloning doesn't recurse by default. A plain git clone of a repo with submodules leaves those folders empty. It's a constant source of "why is this directory blank" confusion for anyone who doesn't know to pass --recurse-submodules or run git submodule update --init.
Monorepos aren't just "one big repo" for convenience — they trade one set of problems for another. You lose independent versioning and per-project access control, and the repo can get large and slow to clone; you gain atomic cross-project commits (one PR changes a library and every consumer of it, together, reviewed together) and no submodule-pin drift. Most teams that try submodules for tightly-coupled internal code eventually migrate to a monorepo — the coordination tax of "did you remember to bump the pin" grows with team size in a way a monorepo just doesn't have.

The genealogy: a gitlink is Git's fourth object type

Blobs, trees, and commits are the objects you meet everywhere else in Git. A submodule reference is the fourth kind — a "gitlink" — a tree entry that points at a commit in a different repository entirely, rather than at a blob or another tree. It's the same commit-addressing idea from tagging and detached HEAD (a fixed pointer to one exact snapshot), just crossing a repository boundary instead of staying inside one.