Git Submodules
This article belongs to the Git Basics to Advanced course, which is currently being revisited with updated architectural patterns and content. Content may be refined shortly.
Table of Contents
4 sections
A Git submodule allows you to keep one Git repository as a subdirectory of another Git repository. This lets you clone another repository into your project and keep your commits separate.
Submodules are useful when your project depends on shared libraries, internal micro-packages, or third-party repositories that maintain their own release cycles.
Git Submodules Architecture
Step 1 of 2: Embed External Project via git submodule add
$ git submodule add https://github.com/org/shared-ui.git lib/shared-ui Clones the external repo into lib/shared-ui and creates .gitmodules mapping file.
How Submodules Work
Unlike standard folders in your working tree, a submodule directory is not tracked as a collection of individual files by the parent repository.
Instead, the parent repository records only:
- The remote URL and local path mapping in a
.gitmodulesconfiguration file. - A gitlink pointing to one specific commit SHA in the child repository.
This guarantees that every developer and CI runner checking out your repository uses the exact tested revision of the submodule dependency.
Adding a Submodule
To add an external repository as a submodule:
git submodule add https://github.com/example/shared-ui.git libs/shared-ui
This creates or updates the .gitmodules file:
[submodule "libs/shared-ui"]
path = libs/shared-ui
url = https://github.com/example/shared-ui.git
Stage and commit both .gitmodules and the new submodule pointer:
git add .gitmodules libs/shared-ui
git commit -m "chore: add shared-ui submodule dependency"
Cloning a Project Containing Submodules
When you clone a repository that contains submodules, the submodule directories are initially empty.
To clone the repository and initialize all submodules in one step:
git clone --recurse-submodules https://github.com/example/main-app.git
If you already cloned the project without the --recurse-submodules flag:
# Initialize local configuration and clone submodule contents
git submodule update --init --recursive
Updating Submodules
To pull the latest commits from the upstream submodule remote:
git submodule update --remote libs/shared-ui
Because the submodule pointer in your parent repo moves to a new commit hash, record the update in your parent repository:
git add libs/shared-ui
git commit -m "chore: update shared-ui submodule to latest release"