Why and how to use Git submodules

Git submodules let you manage dependencies across repositories cleanly and efficiently. Learn how and when to use them effectively in infrastructure projects.

I. Introduction to Git Submodules  

Git submodules are a built-in feature that lets you include one Git repository inside another. This approach is useful when you need to manage dependencies between different codebases while keeping them autonomous.

Submodules point to a specific commit of an external repository. This ensures that every version of the main project uses exactly the same revision of its submodules, providing consistency and reproducibility.

Submodules help you compose a project from multiple repositories, each evolving independently but tracked together in a unified, coherent state.

Why and How to Use Git Submodules  

When working on complex projects, you often need to include other Git projects as dependencies. Git provides a feature called submodules that lets you embed one repository inside another. This is especially useful for shared libraries, reusable components, or any external code.

Why use submodules?  

• Clear dependency management: Each submodule points to a specific revision of the external repo, ensuring your project uses exactly the version you intend.
• Project independence: Submodules remain standalone Git repositories, making updates and maintenance easier.
• Precise control: You choose when and how to update submodules, avoiding unwanted automatic updates.

II. How to Set Up a Git Submodule  

How to add a submodule?  

To add a submodule to your project, run:

git submodule add <repository-url> <path/in/your/project>

For example:

git submodule add https://github.com/my-user/my-library.git libs/my-library

This command will:

• Clone the external repo into libs/my-library.
• Add an entry to the .gitmodules file describing the submodule.
• Stage the submodule in your project’s index.

Don’t forget to commit these changes:

git commit -am "Add my-library submodule"

Cloning a project with submodules  

When cloning a project that contains submodules, you must initialize and fetch them separately:

git clone <project-url>
git submodule init
git submodule update

Or more simply:

git clone --recurse-submodules <project-url>

Updating a submodule  

To update a submodule to the latest version on its main branch (e.g., main), do:

cd <path/to/submodule>
git checkout main
git pull
cd ../
git add <path/to/submodule>
git commit -m "Update submodule"

Important: always commit in the parent project after modifying a submodule, because it tracks a specific SHA-1, not a branch.

Removing a submodule  

To remove a submodule, you need to:

1. Remove its entry from .gitmodules.
2. Remove its entry from .git/config.
3. Delete the submodule directory.
4. Remove it from the Git index.

Commands:

git submodule deinit -f <path/to/submodule>
rm -rf .git/modules/<path/to/submodule>
git rm -f <path/to/submodule>
git commit -m "Remove submodule"

Conclusion  

Git submodules are a powerful tool for managing dependencies in your projects. They allow you to maintain precise control over the versions in use and facilitate modular code organization. However, they require disciplined management to avoid conflicts and synchronization issues.

Feel free to use them whenever you need to include external projects while keeping your codebase clean and clearly organized.

III. When to Use (or Avoid) Git Submodules  

Knowing the right use cases helps you avoid unnecessary complexity.

✅ Recommended Use Cases  

❌ Use Cases to Avoid  

• Situations needing automatic dependency updates (consider subtrees or package managers).
• Simple or single-use projects where multiple repos are overkill.
• Development environments that require an instant, seamless clone experience.

Summary: Submodules excel when you need strict integration of independently maintained components without sacrificing version control precision.

IV. Managing Submodules in Practice  

Best Practices  

• Always run git submodule update --init --recursive after cloning.
• Document submodules in your README.md.
• Avoid pointing to moving branches; prefer tags or fixed commits.
• For speed, use shallow submodules (--depth=1).

Bulk Update  

git submodule foreach git pull origin main

Updates all submodules in one command.

V. Alternatives to Git Submodules  

Git Subtree  

• Embeds the external repo’s contents into the main project tree
• Simpler to use, no dependency on .gitmodules
• Less suitable if you need to keep histories strictly separate

Package Managers (npm, pip, etc.)  

• Ideal for dependencies tied to a specific ecosystem
• Semantic versioning and easy updates
• Less fine-grained control; not suited for infrastructure code

VI. Common Errors  

1. Cloning a Project Without Initializing Submodules  

Using:

git clone <repo>

Symptoms : Submodule folders appear empty or incomplete

Solution :

Clone with:

git clone --recurse-submodules

Or afterward:

git submodule update --init --recursive

2. Updating a Submodule Without Committing in the Parent Repo  

Developers often run ‘git pull’inside a submodule but forget to commit the updated SHA in the parent project.

Symptoms:

• Other developers do not get the correct version
• CI fails due to outdated SHA

Solution : After update :

git add path/to/submodule
git commit -m "Update submodule"

Git does not point to a branch but to a specific commit → you must commit the update."

3. Working in a Detached HEAD Without Realizing It  

By default, submodules checkout a detached HEAD.

Symptoms

• Work done on no real branch
• Changes disappear because no branch was created

Solution : Always checkout

git checkout main

4. Modifying a Submodule Without Intending to Version It  

Developers often edit a submodule thinking they are editing the parent project.

Symptoms:

• Lost changes
• Rejected commits (the submodule is read-only or external)

Best practice:

• Only modify a submodule if you are allowed to contribute to it
• Otherwise, create a fork or apply a patch in the parent project

5. Conflicts in .gitmodules and .git/config  

Renaming submodule paths or changing URLs can desynchronize configuration files.

Symptoms:

• Git cannot locate the submodule
• Cryptic errors such as “No submodule mapping found”

Solution: Always update both files:

git mv old/path new/path
git add .gitmodules new/path
git commit -m "Fix submodule path"

6. Submodules Not Initialized in CI/CD  

Very common: pipelines don’t load submodules.

Symptoms:

• Tests or builds fail
• Submodule folder is empty in CI

Solution :

In GitHub Actions (example) :

- name: Checkout repository
  uses: actions/checkout@v4
  with:
    submodules: recursive

Or universally:

git submodule update --init --recursive

7. Using a Submodule on a Moving Branch (“Tracking Branch”)  

Mistake:
Pointing the submodule to main or develop and expecting Git to auto-update it.

Git will never auto-update a submodule.

Symptoms:

• Diverging versions across developers
• Environment inconsistencies (local, CI, production)

Solution:
Always point to a tag or a fixed commit. This is the very principle behind how submodules work."

8. Incorrectly Removing a Submodule  

Manually deleting the submodule folder corrupts internal Git metadata.

Symptoms:

• Git still lists the submodule as present
• CI still references old paths

Safe removal procedure:

git submodule deinit -f path/to/module
rm -rf .git/modules/path/to/module
git rm -f path/to/module
git commit -m "Remove submodule"

VII. Conclusion  

Git submodules are a powerful tool when used with care. They fit modular architectures, DevOps environments, and projects requiring precise versioning.

Evaluate whether the complexity is justified. Used properly, submodules let you build a project from autonomous building blocks while maintaining clean version control.

🔗 Useful Resources  

• Official Git Documentation
• Submodule vs Subtree Comparison