What you can do after this lesson
You will be able to recognise a submodule when you meet one, add one, clone a project that uses them, and update them without confusing yourself. This is a brief look at an advanced feature. Many projects never need submodules, and the lesson ends with alternatives you may prefer. The commands here were run in a temporary folder using local bare repositories; paths in the output are generic.
The idea
Sometimes your project depends on code that lives in another Git repository, such as a shared widget library, and you want to keep it separate but pinned to a known version. A submodule does that. In your repository there is a folder, say vendor/widgets, which is a full clone of the other repository. Your repository does not copy the other repository's files into its history. It records one thing: "this folder is repository X at commit Y".
Adding a submodule
We set up a fictional widgets repository and an app repository that depends on it. Inside app:
git -c protocol.file.allow=always submodule add ../widgets.git vendor/widgets
git status -sCloning into '/home/you/sm/app/vendor/widgets'...
done.
A .gitmodules
A vendor/widgets(The -c protocol.file.allow=always option is needed here only because the example uses a local path as the source. Git blocks local file paths for submodules by default as a safety measure. With an https:// or SSH address you do not need it, and you should not enable it globally.)
Two things were staged: a new .gitmodules file and an entry for the submodule path. Look at the file:
cat .gitmodules[submodule "vendor/widgets"]
path = vendor/widgets
url = ../widgets.gitCommit them like any change. Then examine what the parent really stores:
git commit -m "Add widgets submodule"
git ls-files -s vendor/widgets[main 6e6e2a7] Add widgets submodule
2 files changed, 4 insertions(+)
create mode 100644 .gitmodules
create mode 160000 vendor/widgets
160000 68d1c3ae3201f7e1b84406463400a5f7f7267320 0 vendor/widgetsThe mode 160000 is Git's marker for "this is a commit in another repository", and the hash is the exact widgets commit the parent points at. Hashes differ in your own run.
Cloning a project that has submodules
When someone else clones app, the submodule folder arrives empty:
git clone app app-clone
ls app-clone/vendor/widgetsThe listing prints nothing because the folder exists but has no files. Fetch them with:
git submodule update --init
ls vendor/widgets
git submodule statusSubmodule 'vendor/widgets' (/home/you/sm/widgets.git) registered for path 'vendor/widgets'
Cloning into '/home/you/sm/app-clone/vendor/widgets'...
done.
Submodule path 'vendor/widgets': checked out '68d1c3ae3201f7e1b84406463400a5f7f7267320'
widget.txt
68d1c3ae3201f7e1b84406463400a5f7f7267320 vendor/widgets (heads/main)(In the practice run the clone needed the same -c protocol.file.allow=always option because of the local path.) To do everything in one step, clone with git clone --recurse-submodules <url>. A teammate who forgets either of these will see an empty folder and wonder why the build is missing files.
Updating a submodule
Say the widgets project publishes a new commit. The submodule folder is a normal repository, so you move it forward inside:
cd vendor/widgets
git pull origin main
cd ../..
git status -sUpdating 68d1c3a..858ebbb
Fast-forward
widget.txt | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
M vendor/widgetsThe parent now reports M vendor/widgets: the pointer is out of date compared with what is checked out. Record the new version in the parent so teammates get it:
git add vendor/widgets
git commit -m "Update widgets to v2"
git submodule status 858ebbb37c3ba7346034484ab9fb3b348c507fa3 vendor/widgets (heads/main)Teammates then run git pull followed by git submodule update to move their copy to the new commit. A shortcut for pulling new upstream commits in all submodules is git submodule update --remote, which follows the branch configured for the submodule.
Pitfalls
- Detached HEAD inside the submodule. After
git submodule updatethe submodule is checked out at a specific commit, not on a branch. If you edit there and commit, create a branch first, or the commit is easy to lose. - Forgetting to push the submodule. If you commit in the submodule and update the parent pointer but never push the submodule's own commits, teammates cannot fetch that commit.
- Forgetting to commit the pointer. Updating the submodule is invisible to others until the parent records it.
- Empty folders after clone. Remember
--recurse-submodulesorsubmodule update --init. - Removing one. Deleting a submodule has several steps (deinit, remove the entry and the
.gitmoduleslines); followgit help submodulerather than deleting the folder by hand.
Alternatives
Before adding a submodule, consider whether something simpler fits:
- A package manager (Composer for PHP, npm for JavaScript) records versions of libraries in a lock file, with no extra Git concepts.
- Copying the files in, if they rarely change and the licence allows it.
- A monorepo, one repository containing both projects.
- A subtree merge, an alternative Git feature that copies another project's history in; its documentation is in the Git manual.
Submodules suit cases where you need an exact pinned commit of an external repository, perhaps your own shared code that is developed separately.
Common mistakes
- Assuming a normal clone gets submodule files. It does not.
- Editing inside the submodule without a branch. Work can be lost.
- Changing the submodule but not committing the pointer. The parent thinks nothing changed.
- Using local path URLs in a shared project. Use a URL others can reach.
- Adding submodules casually. The team pays the cost every day.
Exercise
- Create a bare repository
lib.gitwith one commit, and a separate repositoryapp. - Add
lib.gittoappas a submodule (you will need theprotocol.file.allowoption for a local path), and commit. - Clone
appand fill the submodule folder. - Commit a change in
lib.git, update the submodule inapp, and commit the new pointer.
Show one possible answer
git -c protocol.file.allow=always submodule add ../lib.git vendor/lib
git commit -m "Add lib submodule"
git -c protocol.file.allow=always clone app app-clone
cd app-clone && git -c protocol.file.allow=always submodule update --init
cd ../app/vendor/lib && git pull origin main
cd ../.. && git add vendor/lib && git commit -m "Update lib"git submodule status shows the new commit hash after each step.
Key points
- A submodule embeds another repository inside yours at a fixed path, pinned to one specific commit.
- The parent stores the submodule's URL in .gitmodules and its commit hash in the tree; it does not store the submodule's files.
- A plain git clone leaves submodule folders empty; run git submodule update --init (or clone with --recurse-submodules).
- To update a submodule, move it to a newer commit inside its folder, then commit the new pointer in the parent.
- Submodules add complexity; consider a package manager or a plain copy first, and use them when you really need a pinned external repository.