Working with Submodules and Sub-Trees in Git

Git is a powerful version control system that allows developers to track changes, collaborate, and manage their projects efficiently. Among its many features, Git provides two useful mechanisms called submodules and sub-trees that enable the inclusion of external repositories within a main repository. These features are particularly beneficial when working on larger projects that depend on multiple external dependencies. This article takes a closer look at submodules and sub-trees in Git, discussing their concepts, usage, and advantages.


A submodule is a separate Git repository that exists within another Git project as a subdirectory. It allows you to include an external repository's content into your main project, while each repository remains separate and retains its own history. Submodules are linked to specific revisions of the external repository, ensuring that the main project always uses a known, tested version.

Adding a Submodule

To add a submodule to your project, you can use the git submodule add command followed by the URL of the external repository. This command creates a connection between the main repository and the submodule, and the submodule's files are cloned to a subdirectory within the main project.

git submodule add <URL>

Using a Submodule

Once you have added a submodule, you need to initialize and update it by executing the following commands:

git submodule init
git submodule update

These commands will clone the submodule's contents and update it to the specific revision specified in the main repository.

Updating Submodules

To update a submodule to the latest revision from its upstream repository, you can navigate to the submodule's directory and run the following command:

git submodule update --remote

This command updates the submodule to the latest commit in its repository, allowing you to keep your project up-to-date with external changes.

Advantages of Submodules

Submodules offer several advantages when working with Git:

  1. Separate repositories: Each submodule is an independent repository, which means it can have its history, branches, and releases. This separation allows for better organization and management of external dependencies.
  2. Version control: Submodules enable you to link to specific versions of external repositories, ensuring consistent behavior and avoiding compatibility issues.
  3. Collaboration: When collaborating with other developers, submodules simplify the handling of shared dependencies. Each developer can work independently on their submodule, making it easier to merge changes later.
  4. Code reusability: Submodules facilitate code reuse by providing a way to share common components across multiple projects without duplicating code.


Similar to submodules, sub-trees also allow the inclusion of external repositories within a main repository. However, unlike submodules, sub-trees do not maintain a separate history. Instead, they merge the contents of the external repository into a subtree directory in the main repository, treating it as any other directory.

Adding a Sub-Tree

To add a sub-tree to your project, you can use the git subtree add command, followed by the external repository's URL and the subdirectory path where the sub-tree will reside.

git subtree add --prefix=<subdirectory_path> <URL> <branch>

Using a Sub-Tree

Once you have added a sub-tree, you can work with it like any other directory in your project. You can perform typical Git operations within the sub-directory, such as committing changes, switching branches, and merging.

Updating Sub-Trees

To update a sub-tree to the latest changes from its upstream repository, you need to execute the following command:

git subtree pull --prefix=<subdirectory_path> <URL> <branch>

This command fetches the latest changes from the specified branch in the original repository and merges them into your sub-tree directory.

Advantages of Sub-Trees

Sub-trees offer several benefits in Git projects:

  1. Ease of use: Sub-trees don't require additional steps for initialization and referencing specific commits like submodules.
  2. Simple operations: As sub-trees become part of the main repository, standard Git operations can be performed directly on the sub-directory, making it easier to work with.
  3. History integration: The commit history within a sub-tree is merged into the main repository's history, providing a consolidated view of the entire project.
  4. Flexibility: Sub-trees can be shared across different repositories or even moved and copied like any other directory, enabling greater flexibility in managing external dependencies.


Git provides two powerful mechanisms, submodules and sub-trees, to include external repositories within a main repository. While submodules maintain separate histories and offer version control benefits, sub-trees merge the contents of external repositories into the main project's history. Both mechanisms have their advantages and can be used depending on the specific needs of your project. By leveraging submodules and sub-trees, you can simplify dependency management, enhance collaboration, and improve code reusability in your Git projects.

© NoobToMaster - A 10xcoder company