Git Submodules & Subtrees: Managing Nested Repositories & Shared Libraries

In large enterprise projects, software applications rarely exist in isolation. You might build an e-commerce platform that shares a common payment library, custom UI components, or encryption module with five other internal applications. Git Submodules let you keep a Git repository as a subdirectory of another Git repository while preserving separate commit histories.

Adding a Submodule to a Project

To include an external repository as a submodule inside your project:

# Add a submodule into the 'libs/payment-sdk' folder:
$ git submodule add https://github.com/company/payment-sdk.git libs/payment-sdk

When you run this command, Git creates two critical artifacts:

1. .gitmodules file: A plain text configuration mapping the submodule's local path to its remote repository URL:

   [submodule "libs/payment-sdk"]
       path = libs/payment-sdk
       url = https://github.com/company/payment-sdk.git

2. A gitlink entry: Git does not track the submodule's individual files in the main repository's tree. Instead, it records a special 160000 mode entry pointing to a single commit hash of the submodule.

Cloning a Repository with Submodules

If you run a standard git clone on a repository containing submodules, the submodule directories will be cloned as empty folders! To initialize and download their contents:

# Recommended: Clone and initialize all submodules in one command:
$ git clone --recurse-submodules https://github.com/company/main-app.git

# If you already cloned normally without the flag, run:
$ git submodule update --init --recursive

Updating Submodules to Latest Remote Commits

Because submodules are pinned to exact commit hashes, they do not update automatically when new commits are pushed upstream. To update them:

# Fetch and merge new commits for all submodules:
$ git submodule update --remote --merge

# Commit the updated commit pointer in the parent repository:
$ git commit -am "chore: update payment-sdk submodule to latest release"

Submodules vs Git Subtree

While submodules store external links, Git Subtree merges the external project's files and commit history directly into your parent repository's tree. Subtrees avoid empty folder issues for colleagues, but require more complex merge commands.