What was bound to happen has happened. Ana has spent months extracting reusable pieces out of task-manager: the button with a loading state, the confirmation dialog, the text field with validation. At first they lived in app.js; then in a separate components.js. And now there are two more projects in the company that want to use them.

The team has done the right thing: it has created a repository of its own, ui-components, at git.example.com/team/ui-components.git, with its own history, its own tagged versions and its own maintainers.

And now the uncomfortable question arises: how does task-manager use that library?

Copying the files and pasting them works up until the first fix, at which point there are three divergent copies. And it is not enough to "have the library somewhere": it needs to be recorded which exact version of ui-components each commit of task-manager uses, so that running git checkout v1.0.0 six months from now can rebuild exactly that application.

Git's native answer to that problem is submodules. They are powerful, they are the right solution for certain cases, and they have a reputation — deserved — for biting anyone who does not understand how they work. This lesson is about understanding them properly.

1. What a submodule is exactly
2. git submodule add: adding ui-components
3. What exactly gets committed: the commit-type object
4. Cloning a project with submodules
5. Updating: the submodule versus the pointer
6. Working inside a submodule and detached HEAD
7. Inspection: status, foreach and diff --submodule
8. submodule.recurse and other options that take the pain away
9. The real problems
10. Alternatives: submodules, subtree, packages and monorepo

The complete definition, and everything else follows from it:

A submodule is an entry in the parent repository's tree pointing at a specific commit of another repository, plus a line in the .gitmodules file saying where to clone that other repository from.

Two pieces, no more:

1. The pointer: an entry in the tree (lesson 01-04) whose type is neither blob nor tree, but commit. It stores a 40-character hash and nothing else.
2. .gitmodules: a version-controlled text file, at the parent's root, associating each path with its URL.

The crucial part: the parent repository does not contain the library's code. It contains a sticky note saying "ui-components goes here, at exactly commit 7f3a9d2". The code lives in the other repository, with its own .git, its own history and its own branches.

From that come the three properties that define the experience of working with submodules:

• Exact reproducibility. Each commit of task-manager pins a specific version of the library. git checkout v1.0.0 + updating the submodules rebuilds the application exactly as it was.
• Independent histories. A commit in the library does not show up in the application's history. They are two separate repositories with two separate git logs.
• Explicit updating. The pointer does not move on its own. If the library moves forward, the parent carries on pointing at the same commit until somebody decides to move it and commits that.

That last property is simultaneously the greatest virtue and the greatest source of complaints.

Ana does it from the root of task-manager:

Syntax:

• If you omit the path, the repository's name is used (ui-components/).
• -b <branch> registers a tracking branch, useful for --remote (section 5).

What has happened, exactly:

Two new files, not two hundred. The library's entire directory shows up as a single entry. That is the first visible sign that the content is not being stored.

The generated .gitmodules:

And the commit:

Note the last line: create mode 160000. The modes we knew from lesson 01-04 were 100644 (ordinary file), 100755 (executable) and 040000 (directory). 160000 is the special mode for a submodule, and that number is literally how Git marks "there is a pointer to an external commit here".

Ana can now use it from index.html:

And she pushes:

It is worth looking at it from the inside, because understanding it here avoids all the later confusion. We pick up the tools from lesson 01-04:

There it is. The vendor tree contains an entry of type commit with mode 160000. It is not a tree, it is not a blob: it is a reference to a commit object that is not even in task-manager's object database.

Indeed: that object lives in the ui-components repository, not here. The parent only stores its name.

And the total size that reference takes up in the parent repository:

A tree with one entry: a few dozen bytes. The task-manager repository has not grown at all from taking on a library of 200 commits.

From this you can see why the diff of a submodule change looks so odd:

One line changing. The library's entire content may have changed, but for the parent this is a pointer moving.

Bruno clones the project for the first time:

The directory exists but it is empty. This is the first classic stumble, and it happens to everyone: git clone does not download the submodules by default.

There are two ways of fixing it.

It clones the parent and, straight afterwards, initialises and clones each submodule at the pinned commit.

Or in a single command:

The split into two steps makes sense once you understand it:

The init step exists because it lets you change the URL locally before cloning (for example, to use an internal mirror or HTTPS instead of SSH) without touching the .gitmodules shared by the whole team:

You can also initialise only some of them, in projects with many:

Here is the distinction that generates the most confusion, and it deserves a heading of its own.

There are two different updates and they do opposite things:

This is the normal case, and the one you run after a git pull:

Ana has pushed a commit that moves the library's pointer. Bruno does a git pull of the parent, and submodule update leaves his copy of ui-components at exactly the commit Ana pinned. Synchronisation, not updating.

Git has done a fetch in the submodule and checked out the tip of its tracking branch. Which branch? In this order:

1. The one given in .gitmodules with branch = <branch> (or git submodule add -b).
2. If there is none, the remote's HEAD, which is usually main.

And now the important part: that still has not changed anything in the parent's history. It is an uncommitted change:

(new commits) means: "the submodule is at a different commit from the one I have recorded". For the update to be real and to reach the rest of the team, it has to be committed in the parent:

The rule that sums up the whole section: updating the submodule is a change on your disk; updating the pointer is a commit in the parent. If you do not commit, nobody else sees the update, and the next git submodule update undoes it for you.

Carla needs to fix the confirmation dialog, which is in the library. She goes into the submodule's directory:

Detached HEAD, the state from lesson 03-02. And it makes complete sense: the parent does not say "use the library's main branch", it says "use commit 7f3a9d2". Git does exactly that, and checking out a loose commit leaves HEAD detached.

Dangerous consequence: if Carla edits and commits here without further thought, she creates a commit that belongs to no branch. As soon as somebody runs git submodule update, that commit is orphaned and can only be recovered through the reflog (lesson 09-04).

The correct procedure has four steps:

Step 3 is the one that gets forgotten, and leaving it out is the most serious failure of all with submodules. If Carla commits the pointer in the parent without having published the submodule's commit, the result is:

The parent points at a commit that does not exist anywhere except on Carla's disk. The project is broken for the whole team until she publishes.

Git has a safety net for this, and it needs enabling:

check is the recommended option: it warns you and forces you to decide, rather than publishing things off its own bat.

The first character is a status indicator, and you need to know how to read it:

Examples of the problematic situations:

→ Bruno has just cloned without --recurse-submodules.

→ Somebody has moved the submodule and has not committed it in the parent.

With --recursive it descends through nested submodules.

Runs a command in each submodule:

Inside the command, Git defines useful variables:

By default, a submodule change shows up as that Subproject commit line. --submodule=log shows the commits that make up the difference, which is infinitely more informative:

Three commits of difference, with their subjects. The available modes:

And since that is what you want almost always, it is worth pinning it:

With status.submoduleSummary, git status also summarises the outstanding commits instead of just saying (new commits).

Most of the suffering with submodules comes from forgetting --recurse-submodules on some command. This option enables it by default for nearly all of them:

From then on, git pull, git switch, git checkout, git reset and others update the submodules automatically. It is the first setting anybody working with submodules should put in place.

Note: submodule.recurse does not affect git clone, which still needs its explicit --recurse-submodules.

The complete recommended set of configuration:

And a handful of commands that solve specific situations:

That last one deserves an explanation: deinit deregisters it, git rm removes the tree entry and the .gitmodules line, and the rm -rf of .git/modules/ deletes the internal repository Git keeps (since version 1.7.8, the submodule's .git is not inside its directory but in the parent's .git/modules/<name>, and in the submodule's directory there is a .git file pointing there — the same technique we shall see with worktree in lesson 06-06).

Everything above works. These are the stumbles that occur in practice and how to solve them.

Symptom. Somebody clones and vendor/ui-components/ has nothing in it. The application does not start.

Cause. git clone without --recurse-submodules.

Solution. git submodule update --init --recursive. And prevention: document it in the README.md, and — better still — a post-checkout hook from lesson 06-01 that warns:

Already seen in section 6: somebody committed the pointer without publishing the submodule's commit.

Solution. That person does a git push in the submodule. Prevention: push.recurseSubmodules check.

Symptom. git status in the parent says modified: vendor/ui-components (modified content) and there is no way of making it go away.

Cause. Somebody has edited files inside the submodule without committing them there.

Solution, depending on what you want:

The ignore option accepts none (the default), untracked (ignores untracked files), dirty (also ignores modifications) and all (ignores even a different pointer). all is dangerous: it hides exactly the information you need to see.

Symptom. Carla moves from a branch that has the submodule to another that does not (or that has it at a different version), and odd files appear or the directory is left with old content.

Cause. The parent's checkout moves the pointer, but the content of the submodule's directory does not update on its own unless you ask for it.

Solution. submodule.recurse true, or remembering git checkout --recurse-submodules <branch>.

And a particularly annoying case: on going back to a branch from before the submodule was added, the directory sits there with content and untracked. It is not a bug: it is that Git does not delete directories containing a repository, so as not to destroy work.

Two branches update the submodule to different commits:

There are no conflict markers to edit: the conflict is over which hash should win. Resolving it consists of deciding the right commit:

Often the right answer is neither of the two, but a later commit of the submodule containing the changes from both branches. Merge them first inside the submodule, and then point there.

And the problem least talked about: submodules add a step to everything. Every pull may need a submodule update; every change in the library is two commits and two pushes; every new person gets the first clone wrong. None of that is serious on its own, but it adds up.

That is why the important question is not "how do you use submodules?", but "is this the right tool for my case?". On to that.

There are four reasonable ways of composing a project out of several pieces.

A paragraph on each:

git subtree does the opposite of submodules: it copies the content of the library into the parent and keeps it synchronised with merges. Whoever clones has nothing special to do, because the code is right there. In exchange, the repository grows, the history is mixed in and contributing back to the library is awkward. It is a good option when you consume a dependency and rarely modify it, and when the friction of --recurse-submodules is unacceptable (for example, if the project is cloned by people outside the team). The basic commands are git subtree add, pull and push; we do not develop it here because it would deserve a lesson of its own.

A package manager (npm, pip, Maven, Cargo…) is, in most modern projects, the right answer. If ui-components can be published as a package — even in a private company registry — the team declares "@team/ui-components": "^2.1.0" in its package.json, the lock file guarantees reproducibility, and the whole semantic versioning machinery (lesson 05-05) works in its favour. The fact that Git can do this does not mean it should. Before choosing submodules, always ask yourself whether a package would solve the problem.

The monorepo — a single repository with the application and the library inside it — removes the problem at the root: one commit can change both at once, and they are always consistent. It is what many large companies do. The price is a repository that grows a lot and needs its own tooling for permissions, partial builds and performance. That scenario, with its techniques — partial clones, sparse-checkout, shallow clones — is the subject of lesson 10-04: Scaling Git for Large Projects.

Submodules win when several of these conditions hold at once:

• The dependency is source code you build alongside your own, not a publishable artefact.
• You need to pin an exact commit, not a range of versions.
• You modify the library fairly often and you want it to be a first-class repository.
• There is no internal package registry (or you do not want to set one up).
• The team is small and can be trained in the mechanics.

Typical real-world cases: CMS themes and plugins, C/C++ libraries built from source, configurations shared between projects, firmware with third-party components.

And a mention that has to be made here because it sometimes gets confused: if your problem is not shared code but large, binary files — high-resolution images, videos, models, executables — the answer is none of the four, but Git LFS, which replaces those files with text pointers and keeps the content in a separate store. It is the subject of lesson 10-03: Git LFS for Large Files.

For task-manager, the team ends up taking this decision: a submodule for now, because ui-components is in full development, is modified every week and it is not worth publishing a package on every change. When the library settles down and other teams start consuming it, they will move to publishing it in the internal npm registry. It is a sensible decision: the way a project is composed can change with its maturity.

Mistake 1: cloning without --recurse-submodules. Mistake number one. Empty directory and broken application. Solution: git submodule update --init --recursive.

Mistake 2: committing the pointer without publishing the submodule's commit. It breaks the project for everybody else. Prevention: git config push.recurseSubmodules check.

Mistake 3: working in the submodule without leaving detached HEAD. The commits end up orphaned. Do git switch <branch> before touching anything.

Mistake 4: confusing submodule update with submodule update --remote. The first obeys the parent; the second brings in what is new from the remote. They are opposites.

Mistake 5: forgetting to commit in the parent after updating. Without a commit in the parent, the update exists only on your disk.

Mistake 6: using submodule.<n>.ignore = all. It hides precisely the information you need to see. At most, dirty.

Mistake 7: trying to delete a submodule with rm -rf. It leaves remnants in .git/config, .gitmodules and .git/modules/. Use the deinit + git rm sequence.

Mistake 8: choosing submodules by default. There is nearly always a simpler alternative. Justify the choice.

Tip 1: git config --global submodule.recurse true, always. It is the setting that avoids the most pain.

Tip 2: diff.submodule log and status.submoduleSummary true. They turn illegible hashes into lists of commits.

Tip 3: point at stable commits, preferably tagged ones. A submodule pointing at the tip of another team's main is an inexhaustible source of surprises. git describe --tags inside the submodule tells you where you are.

Tip 4: document the mechanics in the README.md. Five lines with the clone --recurse-submodules and the submodule update --init save every new person an hour.

Tip 5: a post-checkout hook that warns about uninitialised submodules. It is the perfect use of what you learned in lesson 06-01.

Tip 6: when updating the pointer, explain why in the message. "Update ui-components" says nothing; "Update ui-components to v2.2.0 for the focus fix" turns that commit into useful information.

Working locally (with no remote server):

1. Create a library repository with three commits and a v1.0 tag.
2. Create an application repository with two commits.
3. Add library as a submodule of application at vendor/library and commit it.
4. Inspect the tree with git cat-file -p HEAD^{tree} and locate the entry with mode 160000.
5. Check that the commit object it points at does not exist in the parent's object database.

On the previous exercise:

1. Add two new commits to library.
2. In application, check that git status says nothing (the pointer is unchanged).
3. Run git submodule update --remote and observe what changes in git status.
4. Commit the new pointer with a message that explains why.
5. Check the pointer's diff with --submodule=short, --submodule=log and --submodule=diff.

1. Clone application without --recurse-submodules and check the empty directory and the output of git submodule status.
2. Fix it with git submodule update --init.
3. In the clone, go into the submodule and check that you are in detached HEAD. Make a commit there without switching branch and observe Git's warning.
4. Recover that orphaned commit by putting it on a branch.
5. Remove the submodule from the parent completely (deinit, git rm, .git/modules/) and verify that no remnants are left.

Solution 1:

The -c protocol.file.allow=always option is needed as of Git 2.38 in order to use submodules with local paths; with https:// or git@ URLs it is not necessary.

There it is: mode 160000 and type commit.

Confirmed: the object is not in the parent's database. Only its name is stored.

Solution 2:

The parent is still pointing at the pinned commit: the library's new commits are of no concern to it. That is the property, not a bug.

Far more useful: two commits, with their subjects.

It shows the real content of the changes inside the submodule.

Space prefix: all in order.

Solution 3:

The leading - is the diagnosis: not initialised.

The + is the warning: the submodule is at a different commit from the recorded one. And that commit is not on any branch:

Now it is safe. Without that step, a git submodule update would have orphaned it.

The three places a submodule lives, all clean. A plain rm -rf would have left remnants in all three.

Submodules are Git's native answer to composing a project out of several repositories, and their entire behaviour follows from one single idea. The essentials:

• A submodule is a pointer to a specific commit of another repository, stored as a tree entry of mode 160000 and type commit, plus a line in .gitmodules. The parent does not contain the library's code.
• That gives exact reproducibility (each commit of the parent pins a version of the dependency), independent histories and explicit updating: the pointer does not move on its own.
• git submodule add <url> <path> brings it in; the resulting commit touches two files, not two hundred.
• Cloning requires --recurse-submodules, or git submodule update --init --recursive afterwards. It is the most frequent mistake.
• There are two opposite updates: submodule update puts the submodule where the parent says; submodule update --remote brings in what is new from the remote and the pointer has to be committed in the parent for it to really exist.
• Inside the submodule you are in detached HEAD: switch to a branch before working, and publish the submodule's commit before committing the pointer (push.recurseSubmodules check).
• git submodule status with its prefixes ( , -, +, U), foreach and diff --submodule=log are the inspection tools. submodule.recurse true, diff.submodule log and status.submoduleSummary true remove most of the friction.
• The real problems are always the same: empty directories, pointers to unpublished commits, uncommitted changes inside the submodule, branch switches in the parent and pointer conflicts. They all have a known solution and they all have a prevention.
• And above all: they are not the default option. Compare them with git subtree, with a package manager (often the best answer) and with the monorepo (lesson 10-04), and choose with judgement. For large binaries, the tool is Git LFS (lesson 10-03).

task-manager is now composed of two repositories, and the team has the traceability it needed. But a problem is still outstanding from the end of module 5, and it is Carla's.

Carla is working on feature/multiple-delete, a long, half-finished branch. Every time an urgent alert arrives — a production fault, a code review to attend to, a query about another branch — she has to run git stash, switch branch, sort it out, come back and git stash pop. Ten times a day. And with the submodule just added it gets worse, because every branch switch also drags its update along.

Her first idea is to clone the repository twice. It would work, but it doubles the space, doubles the fetches and leaves two repositories with histories that have to be kept synchronised by hand. There is a much better solution, built into Git and surprisingly little known: several working directories sharing a single object database. That is lesson 06-06: Multiple Working Copies with git worktree.