Open In App

Git Subtree vs. Git Submodule

Last Updated : 08 Apr, 2024
Like Article

Git Subtree and Git Submodule are both mechanisms in Git that allow you to incorporate external repositories into your own repository. They provide a way to manage dependencies and include code from other projects while keeping your repository organized and maintainable.

  • Git Subtree: Git Subtree allows you to insert a separate repository as a subdirectory within another repository, while still maintaining the ability to push and pull changes to and from the subtree’s repository.
  • Git Submodule: Git Submodule allows you to include a separate repository as a submodule within your repository. Submodules are essentially a reference to a specific commit in another repository.

Git Subtree

  • Add the remote repository as a remote in your local repository:
git remote add -f <remote-name> <repository-url>
  • Pull the remote repository into your project as a subtree:
git subtree add --prefix=<prefix> <remote-name> <branch> --squash
  • Make changes to the subtree as needed and commit them.
  • Push changes to the subtree’s repository:
git subtree push --prefix=<prefix> <remote-name> <branch>
  • Pull changes from the subtree’s repository:
git subtree pull --prefix=<prefix> <remote-name> <branch> --squash

Git Submodule

  • Add the submodule to your repository:
git submodule add <repository-url> <directory>
  • Initialize the submodule:
git submodule init
  • Update the submodule to fetch its contents:
git submodule update
  • Make changes within the submodule as needed, commit them, and push to the submodule’s repository.
  • To update the submodule in your main repository, navigate to the submodule directory and pull changes:
git pull origin master


Let’s say you have a project called “MainProject” and you want to include another project called “SubProject” using both Git Subtree and Git Submodule.

Git Subtree:

git remote add -f subproject-repo
git subtree add --prefix=subproject subproject-repo master --squash

Git Submodule:

git submodule add subproject
git submodule init
git submodule update

Shortcomings of git submodules

  • When cloning repositories with submodules, the submodules must be downloaded separately. If the source repository is moved or becomes unavailable, the submodule folders will be empty after cloning.
  • Git submodules have a few significant drawbacks. Firstly, they can lock the repository to a specific version of an external repository. Secondly, there is a lack of effective merge management. Thirdly, it is commonly assumed that the Git repository is not aware that it has become a multi-module repository.

Shortcomings of git subtrees

  • One must learn a new approach to merging.
  • Contributing code to the sub-projects upstream can be a bit challenging.
  • You must ensure that super and sub-project codes are not mixed in new commits.


What’s the main difference between Git Subtree and Git Submodule?

The main difference is in how they incorporate external repositories. Git Subtree embeds the external repository’s code into your own repository, while Git Submodule maintains a separate reference to the external repository.

When should I use Git Subtree over Git Submodule?

Git Subtree is preferred when you want to integrate external code into your repository and treat it as part of your project. It’s useful for cases where you need to make changes to the external code as part of your project’s development.

Can I track changes in the external repository with Git Submodule?

Yes, you can track changes in the external repository by navigating to the submodule directory and pulling changes from the submodule’s repository.

Is it possible to push changes directly to the external repository with Git Submodule?

No, Git Submodule only maintains a reference to the external repository and does not directly push changes to it. You need to navigate to the submodule directory and push changes from there.

Git Subtree and Git Submodule are both valuable tools for managing dependencies and integrating external repositories into your projects. Understanding their differences and use cases can help you make informed decisions when incorporating external code into your Git repositories. Choose the approach that best fits your project’s requirements and workflow.

Like Article
Suggest improvement
Share your thoughts in the comments

Similar Reads