Git Submodules: The Proper Way to Incorporate Third-Party Code into Your Project

When developing projects, you often need to reuse third-party code libraries (such as utility classes, UI components, or open-source frameworks). Directly copying third-party code into your project can lead to issues like: difficulty tracking third-party updates, version chaos, and challenges in code reuse during team collaboration. This is where Git Submodules come in handy.

Why Use Submodules?¶

Suppose you have a project and want to integrate a third-party carousel library. Directly copying the third-party code into your project causes problems:

Version Control Failure: When the third-party library updates with new features or bug fixes, you must manually download the new version and overwrite the existing code, which is error-prone.
Collaboration Difficulties: When other team members clone the project, third-party code modifications cannot be uniformly managed, leading to “everyone copying different versions” chaos.
Poor Reusability: If multiple projects need the same third-party library, copying leads to code duplication and wasted storage space.

The core role of Git Submodules is to embed a third-party repository within the parent project and track its version information, enabling the parent project to reuse the third-party code while independently tracking and updating its version.

What Are Git Submodules?¶

In simple terms, a submodule is like embedding a small independent repository within your project. This small repository (submodule) can independently manage its code, branches, and versions, while the main project (parent repository) only needs to record the submodule’s location and current version information (e.g., a commit hash).

For example:
- Parent Project: Your website project, responsible for business logic and page structure.
- Submodule: The third-party carousel library, maintained independently. You only need to tell Git in the parent project: “This carousel library is embedded here, version 1.0.0.”

Basic Steps for Using Submodules¶

1. Create Parent Project and Add Submodule¶

Suppose you are developing a website project and want to introduce a third-party carousel library named carousel as a submodule:

(1) Initialize Parent Project Repository¶

# Create and enter the parent project directory
mkdir my-website && cd my-website
git init
# You can first create basic project files, e.g., README
echo "My Website Project" > README.md
git add README.md
git commit -m "Initial commit"

(2) Add Third-Party Submodule¶

Use the git submodule add command to add the third-party repository as a submodule. The format is: git submodule add <third-party repository URL> <submodule path in parent project>.

Assume the third-party carousel library’s repository URL is https://github.com/example/carousel.git, and you want to place it in the lib/carousel directory of the parent project:

git submodule add https://github.com/example/carousel.git lib/carousel

After execution, Git will:
- Generate a .gitmodules file in the parent project (recording submodule configuration).
- Create the lib/carousel directory in the parent project and initialize an independent Git repository (submodule).

(3) Commit Submodule Configuration¶

git add .gitmodules lib/carousel/.git
git commit -m "Add carousel submodule (version: 1.0.0)"

2. Clone a Parent Project with Submodules¶

When others clone your parent project, Git does not automatically pull submodule code (only the parent project framework is pulled by default). You need to manually initialize the submodule or use the --recursive parameter to pull all submodules at once.

(1) Regular Clone (Requires Manual Submodule Initialization)¶

git clone https://github.com/your-username/my-website.git
cd my-website
# Initialize submodules (tell Git to track submodules)
git submodule init
# Update submodules to the version recorded in the parent project
git submodule update

(2) One-Click Clone (Recommended)¶

Use the --recursive parameter to directly clone the parent project and recursively pull all submodules:

git clone --recursive https://github.com/your-username/my-website.git

3. Operate Submodule Internal Code¶

The submodule itself is an independent Git repository. You can modify, pull, and commit it like a regular repository:

# Enter the submodule directory
cd lib/carousel
# Check current branch
git branch
# Switch to the main branch of the third-party repository (if needed)
git checkout main
# Pull the latest updates from the third-party repository
git pull origin main
# (Optional) After modifying code, commit to the submodule repository
git add .
git commit -m "Fix carousel bug" -m "Add new animation effect"
git push origin main
# Return to the parent project
cd ..

Modifications to the submodule directly affect the third-party repository, and the parent project will record the submodule’s latest version (the commit hash you just pushed to the third-party repository).

4. Update Submodule Code¶

If the third-party repository has updates (e.g., new commits are pulled), the parent project needs to manually update the submodule reference:

# Enter the submodule directory to pull updates
cd lib/carousel
git pull origin main
# Return to the parent project and commit the new submodule reference
cd ..
git add lib/carousel
git commit -m "Update carousel to latest commit" -m "Fix: carousel crash on mobile"
git push

At this point, the parent project’s commit history will update the submodule version number, ensuring others can obtain the latest third-party code when cloning.

5. Handle the .gitmodules File¶

The .gitmodules file is the submodule configuration file, recording the submodule’s URL and path. Its format is:

[submodule "lib/carousel"]
    path = lib/carousel
    url = https://github.com/example/carousel.git

This file is committed to the parent project repository to ensure everyone on the team can access the correct submodule address during collaboration.

Common Questions and Notes¶

1. What if the Submodule Directory is Empty?¶

If the submodule directory (e.g., lib/carousel) is empty after cloning the parent project, it means the submodule was not initialized. The solution is:

git submodule update --init

The --init flag initializes submodules, and --recursive can handle nested submodules.

2. Do Submodules Automatically Update?¶

No! The parent project only records the submodule’s version (commit hash) and does not automatically pull submodule code. You must manually execute git submodule update or enter the submodule directory to run git pull.

3. How to Ensure Submodule Version Consistency During Multi-Person Collaboration?¶

The .gitmodules file and submodule references (commit hashes) in the parent project must be shared with everyone to ensure consistent submodule paths and versions.
After the third-party repository is updated, the parent project must commit the new submodule reference, and team members can run git submodule update to synchronize.

4. Difference Between Submodule and Subtree?¶

Submodule: An independent repository. The parent project only records the submodule’s version reference, suitable for reusing independently maintained third-party libraries.
Subtree: Merges third-party code into the parent project, meaning the parent project directly contains modified third-party code. Suitable for scenarios with minimal code reuse and full integration of third-party code into the parent project.

Summary¶

Git Submodules are a powerful tool for managing third-party code, with the core principle of independent maintenance between the parent project and submodules. This avoids code redundancy while enabling version tracking of third-party libraries. Key usage points:

Add submodules with git submodule add and commit the parent project’s configuration files.
Use --recursive when cloning to automatically pull submodules, or manually run git submodule update.
Submodule internal modifications require separate handling; the parent project only records version references, which must be manually updated and committed.

By using submodules, you can easily reuse third-party code while maintaining a clear project structure, version control, and efficient collaboration.