Have you ever encountered a situation where you have a piece of code used in multiple places in a project, and you have to modify it everywhere, which is extremely tedious? Or you want to reuse a small tool written by someone else but don’t want to copy-paste the entire code into your own project? That’s where Git submodules come in handy!

What are Git Submodules?¶

In simple terms, Git submodules are like “embedding” a small repository within a large repository. The main repository only records the location and version of the sub-repository, while the actual code content resides in the sub-repository. For example, if you’re building a website and using a carousel component (Submodule A) and a statistics module (Submodule B) written by others, the main project (the website) only needs to “reference” specific versions of these two modules in its code without copying the entire carousel code into the website project.

Why Use Submodules?¶

The most common use of submodules is to manage dependencies and shared code:
- Team Collaboration: Multiple projects can share the same utility library (e.g., an internal company component library). Each project only needs to reference the submodule instead of duplicating code.
- Third-Party Dependencies: If a project depends on a fixed version of an open-source library, submodules allow independent maintenance of that library’s upgrades and version control.
- Code Isolation: Submodules can be developed, tested, and committed independently. The main project only cares about the “version” of the submodule, without affecting internal modifications to the submodule.

How to Update Submodules?¶

The core of updating submodules is to keep the submodule directory of the main project consistent with the latest code in the sub-repository. Here are the detailed steps:

1. Clone a Repository with Submodules¶

If someone provides you with a project containing submodules, first clone the entire repository using git clone. By default, submodule directories are empty (only the .gitmodules file records submodule information), so you need to initialize them manually:

git clone https://github.com/your-project.git
cd your-project  # Enter the main project directory

2. Initialize Submodules¶

Run git submodule init to tell Git, “I’m about to use these submodules; first, read their information.” However, a more common command is git submodule update --init to complete initialization and basic updates in one step:

git submodule update --init

If submodules have nested submodules (e.g., a submodule contains other submodules), you must add the --recursive parameter; otherwise, internal submodules may not update:

git submodule update --init --recursive  # Recursively update all nested submodules

3. Basic Update: Sync Submodules to the Latest Version¶

If the submodule’s repository has new code (e.g., the remote repository has a new version), the main project can directly use git submodule update to pull the latest version. Adding --recursive is safer:

git submodule update --recursive

This synchronizes the local version of all submodules with the latest version in the remote repository.

4. After Modifying Submodule Internals, How to Sync Back to the Main Project?¶

If you modify the code in a submodule (e.g., the carousel component), you must first commit the changes in the submodule, then let the main project “remember” the new version reference of the submodule:

# Enter the submodule directory
cd submodule-directory  

# Commit changes like a regular Git repository
git add .
git commit -m "Fix carousel bug"
git push  # Push to the remote submodule repository if needed (optional, depending on project settings)

# Return to the main project and update the submodule reference
cd ..  # Go back to the main project directory
git add submodule-directory  # The main project will record the new submodule reference
git commit -m "Update submodule to latest version"
git push  # Push to the main project repository so others can get the update

5. How to Pull When Someone Else Updates the Submodule Reference?¶

If a team member modifies the submodule reference in the main project (e.g., changing the submodule version from v1.0 to v1.1), you need to first pull the main project’s updates, then update the submodules:

git pull  # Pull the latest commits from the main project (including submodule reference updates)
git submodule update --init --recursive  # Sync submodules to the new referenced versions

Common Issues & Solutions¶

• Submodule directory is empty?
  You may have forgotten to run --init or --recursive. Simply execute git submodule update --init --recursive.
• Submodule version is incorrect?
  Check if --recursive was omitted. For nested submodules, recursive updates are required to ensure all versions are correct.
• Modifications to submodules not synced to the main project?
  Always remember to return to the main project and execute git add submodule-directory and git commit. Otherwise, the main project will still use the old submodule version.

Summary¶

Git submodules are like Lego blocks: the main project is the “big model,” and submodules are the “parts.” Each part can be modified and upgraded independently while being reused by multiple big models. Key takeaways: Add --recursive when cloning, use git submodule update --init --recursive for updates, and sync references after modifications. Practice with hands-on examples, and you’ll master it quickly!