Git Submodules

01 Min
🔁
Course Under Active Revision Re-visiting

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.

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
1 / 2
📦 Parent Repository (main-project) .gitmodules config file path = libs/shared-ui
Gitlink Pointer ──────▶ tracks exact SHA
🌐 Submodule Repo (shared-ui.git) Pinned commit revision commit #f9e8d7
$ 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:

  1. The remote URL and local path mapping in a .gitmodules configuration file.
  2. 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"