Are Git Submodules a Good Idea?

This post may contain affiliate links. If you click one, I may earn a commission at no cost to you. As an Amazon Associate, I earn from qualifying purchases.

Key Takeaways:

  • Git submodules allow you to embed a Git repository inside another Git repository.
  • They can help manage large codebases and share common code between projects.
  • However, submodules have a complex workflow and can be difficult to use.
  • Submodules make it harder to share changes to the shared code.
  • Subtrees offer an alternative way to share code between repositories.
  • The decision depends on your specific use case and preferences. There are pros and cons to submodules.


Git submodules allow you to nest external repositories inside a parent repository as subdirectories. This allows you to keep a large codebase organized by separating logically distinct components into their own repositories, while still maintaining the ability to pull them together as a cohesive project. However, submodules have received mixed reviews from developers. Some find them indispensable while others argue they are overly complex and problematic. This comprehensive guide will analyze the key benefits and drawbacks of Git submodules so you can evaluate whether they are a good fit for your use case.

By providing an in-depth look at how submodules work, their intended purpose, essential workflows, and alternatives, you will gain a nuanced understanding of this Git feature. You will also learn configuration tips and best practices if you do opt to utilize submodules. With the exponential growth and complexity of modern codebases, submodules offer one potential solution – but also come with their own challenges. This guide aims to illuminate the practical realities of using submodules so you can make an informed decision about managing your repository architecture.

How Do Git Submodules Work?

Git submodules allow you to keep a Git repository as a subdirectory of another Git repository. The submodule maintains its own history, allowing you to clone a repository and get all its submodules at the same time. Some key properties of submodules include:

  • They are their own complete Git repositories, nested within a parent repo.
  • Changes must be committed to the submodule repo separately from the parent repo.
  • The parent repo stores a specific commit SHA reference to the submodule.
  • Running git submodule update will check out the correct commit as referenced by the parent.
  • They are cloned recursively – the parent repository clone will contain the submodule contents too.
  • Changes across repos can be pushed together in one command with git push --recurse-submodules=on-demand.

Under the hood, a submodule is really just a gitlink entry – a 40-character SHA-1 hash that references a specific commit in the submodule repository. The parent repo stores this gitlink in a .gitmodules file to keep track of the submodule configuration.

What is the Intended Purpose of Submodules?

Submodules were designed to allow multiple related repositories to be used together in the same project. The main use case was for allowing large projects to be divided up for easier management.

Some example use cases where submodules could be useful include:

  • Splitting up a large monolithic code repository into logical components.
  • Sharing common code and libraries between related projects.
  • Managing dependencies that need to be tracked in their own repos.
  • Adding third party libraries or frameworks your code relies on.

In these scenarios, submodules allow you to break a mammoth repo into smaller sub-repos that can be independently maintained, while still bringing them together as a unified project.

Sharing code via submodules can be an alternative to more manual solutions like copying files or symlinks. It allows you to leverage the power of Git for managing and tracking the shared components.

Overall, submodules aim to solve the code organization and sharing challenges that arise on large, complex projects with many moving parts.

What is the Basic Workflow for Using Git Submodules?

The workflow for using Git submodules involves a few key steps:

  1. Add a submodule to your repository with git submodule add <url> <path>
  2. Clone the parent repository (recursively clones submodules too).
  3. Make changes within the submodule locally and commit.
  4. Go back to parent repo and commit to save new submodule reference.
  5. Push commits from submodule repo.
  6. Push from parent repo to update submodule references.

For example:

# Add a submodule git submodule add components/library # Clone parent repository git clone <parent-repo-url> –recursive # Make changes in submodule cd components/library # Edit files git add . git commit -m “Update library” # Commit in parent to save new submodule reference cd ../.. git add . git commit -m “Use updated library” # Push changes from both repositories git push –recurse-submodules=on-demand

This workflow allows you to make changes in the submodule independently but integrate them into the parent project with specific commit references.

Some other useful commands include updating submodules with git submodule update, removing with git submodule deinit, and fetching updates from the submodule remote with git submodule update --remote.

Overall, while not overly complex, submodule workflows introduce additional steps compared to normal Git commands.

What are the Main Benefits of Using Git Submodules?

Some of the main benefits of Git submodules include:

Logical Separation of Code

Submodules allow you to break a large codebase into smaller, logically organized repositories. This can help improve version control, componentization, and modularization of the code.

Code Sharing and Reuse

Submodules make it easy to share and reuse common code across multiple different projects. The shared module remains in its own repo but is nested under all consumers.

Independent Development

The nested submodule repositories can be developed and maintained independently with their own workflows. The parent repo just references specific commits.

Simultaneous Updates

Commit references allow you to push updates to submodules and parent repo together in a single command. This helps coordinate simultaneous changes across repos.


Submodules enable you to structure your repository architecture in a more modular fashion, with discrete components that can be managed individually.

Dependency Management

For projects with lots of third-party dependencies, submodules provide a built-in way to organize and manage them via Git.


Submodules allow combining together repositories implemented in different languages that don’t necessarily share the same tooling.

Overall, when used properly, submodules enable modularized code organization and sharing – especially beneficial on large projects.

What are the Main Drawbacks and Challenges with Git Submodules?

However, submodules also come with their own set of disadvantages:

Complex Workflow

Submodules require following a more complex workflow that involves moving between different repositories for commits and pushes.

Steep Learning Curve

The concept of commit SHA references and nested repositories can be difficult to grasp for some users.

Lack of Change Visibility

It’s not easy to see changes or diff submodule content from the parent repo. You have to go inside the submodule.

No Tracking of Uncommitted Changes

The parent repo only tracks specific submodule commits, not any intermediate local changes.

Cloning Can Be Slow

Cloning a repository with multiple levels of submodules results in a slower clone operation.

Harder to Update or Remove

Updating or removing submodules requires manually editing the .gitmodules file and commit references.

Submodule Repository Bloat

Using submodules can unnecessarily bloat the number of repositories for a project.

Constraints on Shared Code

Submodules impose constraints on updating shared code since changes must be committed back to the submodule repo first.

Overall, submodules trade simplicity for flexibility. They require diligence to use properly and may not be suitable for all use cases.

What are Some Best Practices for Working with Git Submodules?

If you do decide to use Git submodules, some best practices include:

  • Initialize submodules at the start with git submodule update --init --recursive
  • Understand how to move between submodule and parent repositories
  • Commit submodule changes before committing in parent repository
  • Use --recurse-submodules flag for unified commands
  • Update submodules regularly with git submodule update
  • Avoid altering submodule histories
  • Tag parent and submodules repos simultaneously
  • Document submodule architecture and purpose
  • Consider submodule repos complementary but separable
  • Carefully evaluate whether submodules provide the best architecture

Following these practices helps streamline submodule workflows. But overall, judicious use of submodules is recommended over adopting them by default.

Are There Any Alternatives to Manage Project Dependencies?

If submodules seem too complex for your use case, some alternatives to consider include:

Git Subtrees

Git subtrees allow embedding subdirectories of other repos in your project as a subtree merge instead of a submodule. The code is literally copied in your repo, so it can be managed like your own code. Changes are then contributed back upstream as needed.

Package Managers

Language-specific package managers like NPM, Maven, NuGet, etc can be used to manage third-party dependencies instead of tracking them directly in Git.

Git Clone in Code

Manually clone required repositories in your application code itself dynamically at runtime. Doesn’t provide same history tracking but simplifies workflow.

Periodic Vendoring

Maintain your own fork of third-party modules that you periodically sync and update rather than direct linking.

Dependency Link Files

Plain text files listing dependency Git URLs for cloning dynamically during build.

Evaluating these alternatives can help determine if submodules provide the best architecture for your systems.

When Are Git Submodules Most Appropriate to Use?

Based on their characteristics, some situations where Git submodules tend to provide the most value include:

  • Splitting monolithic repositories into component modules.
  • Sharing common code across a fixed ecosystem of projects.
  • Managing dependencies from their original repositories.
  • When commits in submodules need to be tightly coupled with the parent repo.
  • Projects where logically separate components require coordinated releases.
  • Access to the full history and source control of dependencies is important.

Conversely, if you need frequent changes to shared components from consumers, Git subtrees or occasional vendoring may be more appropriate.

Do Developers Recommend Using Git Submodules?

Overall, developer opinions on Git submodules are mixed:

Advocates Argue:

  • They serve their intended componentization purpose well.
  • Enable managing dependencies via Git instead of package managers.
  • Allow coordinated changes across repositories.
  • Provide essential architecture for large, complex projects.

Critics Counter:

  • Complexity outweighs benefits for most use cases.
  • Submodules aren’t intended for general code sharing between projects.
  • Better options exist unless you need to frequently change submodule code.
  • Most cons could be avoided with better architecture without submodules.
  • Hurdles like cloning and opaque diffs outweigh modularity benefits.

So in summary, while submodules have some benefits, many developers recommend avoiding them especially for more dynamic sharing use cases. They advise to only use submodules where appropriate after evaluating alternatives.


Git submodules allow embedding repositories inside other repositories in order to organize large codebases into modular components and share common code. While submodules aim to solve code architecture challenges, they also impose a more complex workflow that many developers find frustrating.

The decision whether to use Git submodules depends on your specific project and preferences. They can provide value in certain situations like closely tracking dependencies or coordinating commits across repositories for large projects. But features like opaque diffs and slower cloning may be dealbreakers for other use cases.

Alternatives like subtrees, package managers, or vendoring offer other ways to share code that may better suit your needs. Evaluating the pros and cons and development workflow with submodules can help determine if they are a good fit or if simpler approaches would be better. With a thorough understanding of how submodules work, their use cases, and alternatives, you can make an informed decision on the most effective architecture.

About The Author

Scroll to Top