A submodule is a Git repository nested inside another repository. The parent project references a specific commit of the submodule. It is useful for including libraries or shared code between projects.

Why is the submodule folder empty after a clone?

By default, git clone does not download submodules. Use --recurse-submodules during the clone, or run git submodule update --init afterward.

How do I update a submodule?

cd into the submodule folder and run git pull, or from the parent: git submodule update --remote. Do not forget to commit the updated reference in the parent project.

How do I remove a submodule?

It takes several steps: git submodule deinit path, git rm path, then remove the section in .gitmodules and .git/modules. Finally, commit the changes.

What are the alternatives to submodules?

Package managers (npm, pip) are often simpler for dependencies. Git subtree is an alternative that merges the code into the parent repo. Monorepos avoid the need for submodules.

Git submodule: include a repo inside another

git submodule lets you include a Git repository inside another. Ideal for sharing code between projects or integrating external libraries.

Practice git submodule Git Glossary

gitquest — enquête

Advanced

What is git submodule?

git submodule lets you integrate a Git repository into another as a versioned dependency. The parent project points to a specific commit of the submodule.

It is like having a book within a book: the parent project contains a reference to the submodule, but each has its own history and its own commits.

Git submodule syntax

git submodule add url path

Add a submodule

git submodule update --init

Initialize and download

git submodule update --remote

Update to the latest commit

Git submodule in practice

Adding, cloning, and updating submodules.

Adding a submodule

gitquest — submodule add

# Add a submodule to your project

$git submodule add https://github.com/lib/utils.git libs/utils

Cloning into 'libs/utils'...

remote: Enumerating objects: 42, done.

$git status

new file: .gitmodules

new file: libs/utils

$git commit -m "feat: add utils submodule"

[main a1b2c3d] feat: add utils submodule

Cloning and updating

gitquest — submodule update

# Clone a project that has submodules

$git clone --recurse-submodules https://github.com/my/project.git

Submodule 'libs/utils' registered and cloned

# Or initialize after a regular clone

$git submodule update --init --recursive

Submodule path 'libs/utils': checked out 'c3d4e5f'

# Update a submodule

$git submodule update --remote

Submodule path 'libs/utils': checked out 'e4f5g6h'

Essential submodule commands

git submodule add url

Add a new submodule

git submodule update --init

Initialize after a clone

git submodule update --remote

Update to the latest commit

git submodule status

View submodule status

git submodule foreach cmd

Run a command in each submodule

git submodule deinit path

Deinitialize a submodule

Common mistakes with git submodule

Empty folder after a clone

Submodules are not downloaded by default. Use git clone --recurse-submodules or git submodule update --init after the clone.

Forgetting to commit the update

After a git submodule update --remote, the new reference must be committed in the parent project. Otherwise, other developers will not see the update.

Difficulty removing a submodule

Removal requires several steps. Remember to deinit, rm, and clean up .gitmodules. It is one of the most confusing operations in Git.

Part of the Git Advanced guide

Related commands

git clone

Clone with --recurse-submodules

git remote

Manage remote repositories

git config

Configure submodules

GitQuest is created by Anaïs (nouvelle fenêtre), web developer and head of education, specializing in tech training and digital accessibility.

Questions about git submodule

Master complex projects with GitQuest

Learn to manage submodules and multi-repo projects.

Start the investigations