Git Submodule
Last updated
A submodule embeds one Git repository inside another, pinned to a specific commit. The parent repo records which commit of the submodule it depends on, so everyone gets the same version. It's how you include a shared library or component that lives in its own repository without copying its code.
Try these in the terminal playground - a real shell in your browser, nothing to install.
Syntax
| Command | What it does |
|---|---|
git submodule add <url> libs/x | Add a repo as a submodule at libs/x |
git clone --recurse-submodules <url> | Clone a repo and its submodules |
git submodule update --init --recursive | Init and fetch submodules after a plain clone |
git submodule update --remote | Update submodules to their latest commit |
git submodule status | Show each submodule's commit |
Common cases
| Goal | Command |
|---|---|
| Clone a project that uses submodules | git clone --recurse-submodules <url> |
| Fetch submodules after already cloning | git submodule update --init --recursive |
| Bump a submodule to its latest | git submodule update --remote |
Git submodule FAQ
What is a git submodule?
A submodule is a Git repository nested inside another Git repository at a fixed commit. The parent repo stores a pointer to that exact commit rather than the submodule's files, so collaborators check out the same version. It's used to include a dependency or shared component that has its own repo and history.
How do I clone a repository with submodules?
Use
git clone --recurse-submodules <url> to clone the parent and all its submodules in one step. If you already cloned without that flag, run git submodule update --init --recursive afterward to populate the submodule folders.How do I update a submodule to the latest commit?
Run
git submodule update --remote, which fetches each submodule's tracked branch and moves it to the latest commit. Then commit the change in the parent repo, since the parent records which submodule commit it points at - the update isn't saved until you commit that pointer.Why is my submodule folder empty after cloning?
Because you cloned without
--recurse-submodules, so Git created the folders but didn't fetch their contents. Fix it with git submodule update --init --recursive, which initializes and downloads every submodule.Can I practice this online?
Yes. Open the terminal playground to run
git submodule in a real shell in your browser - nothing to install. Coddy's free interactive Git course also covers repository setup step by step.Related resources
More Git commands
