Git Submodules

A Git submodule is a Git repository placed inside another repository as a subdirectory, with its own independent history¹. The outer repository is the superproject. In this course the typical case is a project that assembles several microservices, each in its own repository (account, order, gateway…), into one place where a single docker compose up or a single CI pipeline can see them all.

This page answers one question: what does the superproject actually store, and how does that explain every command — and every surprise — of the submodule workflow?

The mental model: a pointer to a commit

The superproject does not copy the submodule's files, and it does not follow a branch. It stores two things:

• in the file .gitmodules: where to clone the submodule from (its path and URL);
• in its own tree, at the submodule's path: a gitlink, the hash of one commit of the submodule.

flowchart LR
    subgraph sup ["superproject: store (branch main)"]
        readme["README.md<br/>compose.yaml"]
        gm[".gitmodules<br/>path = api/account<br/>url = …/account.git"]
        link["api/account<br/>gitlink: 12174e7"]:::comp
    end
    subgraph acc ["submodule repository: account"]
        c1["commit a91f3c0"] --> c2["commit 12174e7"]:::tech
        c2 --> c3["commit 83eff0b"]
        br(["branch main"]) -.-> c3
    end
    gm -.->|"where to clone from"| acc
    link ==>|"pins exactly this commit"| c2

The account team can keep committing to main: the superproject still points to 12174e7 until someone in the superproject commits a new pointer. That is why submodules are reproducible (a checkout of the superproject always gets the same code) and why they never update by themselves. You can see the gitlink directly — mode 160000 means "a commit of another repository":

git ls-tree HEAD api/account
# 160000 commit 12174e72e52d514b6256f51f42dee36897ef5261    api/account

Adding a submodule

# From inside the superproject
git submodule add https://github.com/username/account.git api/account
#               or ssh:  git@github.com:username/account.git api/account

git submodule add https://github.com/username/order.git api/order

Each git submodule add:

• clones the repository into the given folder;
• adds an entry to .gitmodules, a file you commit;
• stages the gitlink, the pointer to the commit currently checked out in the submodule.

Commit both, like any other change:

git commit -m "Add account and order as submodules"

The new .gitmodules looks like this:

[submodule "api/account"]
    path = api/account
    url = https://github.com/username/account.git
[submodule "api/order"]
    path = api/order
    url = https://github.com/username/order.git

The workflow, step by step

Follow one change from a fresh clone to a teammate's machine. Watch two things: what is in api/account/ at each step, and which repository each push goes to.

sequenceDiagram
    actor You
    participant W as your clone
    participant S as store repo (GitHub)
    participant A as account repo (GitHub)
    actor T as teammate
    You->>S: git clone …/store.git (no --recurse-submodules)
    S-->>W: files + gitlink 12174e7, but api/account/ is empty
    You->>W: git submodule update --init
    W->>A: clone account, check out 12174e7
    A-->>W: api/account at 12174e7, detached HEAD
    You->>W: cd api/account, git switch main, edit, commit 83eff0b
    W->>A: git push (the submodule first)
    You->>W: cd ../.., git add api/account, git commit
    Note over W: gitlink 12174e7 → 83eff0b
    W->>S: git push (then the superproject)
    T->>S: git pull --recurse-submodules
    S-->>T: gitlink 83eff0b, so api/account is checked out at 83eff0b

The same steps as commands:

# 1. clone: --recurse-submodules (or --recursive) also clones and checks out every submodule
git clone --recurse-submodules https://github.com/username/store.git

# ...or, if you already cloned without it (api/account/ is empty):
git submodule update --init --recursive

# 2. work inside the submodule: leave the detached HEAD first
cd api/account
git switch main
git pull
# edit, then commit and push in the submodule
git commit -am "Validate e-mail on sign-up"
git push

# 3. record the new pointer in the superproject, then push it
cd ../..
git add api/account
git commit -m "Bump account to 83eff0b"
git push

--recursive matters when submodules have submodules of their own. git diff --submodule=log shows which submodule commits a pointer change brings in, before you commit it.

Getting updates

Two different questions, two different commands:

• "Give me the commits the superproject points to" (after someone else bumped a pointer):

  git pull --recurse-submodules
  # if the pull brought a new submodule, also: git submodule update --init --recursive
  

• "Move the pointers to the newest commit of each submodule's branch" (you are the one bumping):

  git submodule update --remote --merge   # or --rebase
  # then commit the new pointers in the superproject
  git add api/account api/order
  git commit -m "Bump submodules to latest main"
  

Quick reference

Common pitfalls

fatal: remote error: upload-pack: not our ref 28d0def2c3f5d7814c753cdf5e3ebbe5b1f0e9a4
fatal: Fetched in submodule path 'api/account', but it did not contain 28d0def2c3f5d7814c753cdf5e3ebbe5b1f0e9a4. Direct fetching of that commit failed.

• The empty folder: a clone without --recurse-submodules leaves api/account/ empty, so the build or docker compose fails on missing files. Write the clone command in the README.
• CI needs the submodules too: actions/checkout does not fetch them unless you set submodules: true (or recursive), and a private submodule needs a token that can read it.

Alternatives

Submodules fit when the pieces have separate owners and release cycles, and you want to pin exact versions. Often something simpler fits better:

For a shared Java library, publishing a Maven artifact is usually the cleanest; for a team project that assembles microservices, a monorepo or submodules both work — pick one and document it.

Key takeaways