What Are Git Subtrees?

In our article on Git Submodules, we discussed a way to embed an external repository into another. An alternative method for achieving this is using "Git Subtree". While the goal is similar, the approach is fundamentally different and offers its own unique set of advantages.

Unlike a submodule, which only links to another repository, a subtree merges the files and history of an external repository directly into your main project.

This makes your main repository a self-contained "super project".

When Should You Use git subtree?

Subtrees are an excellent choice when:

• You want the project to be simple for end-users to clone and use.
• The dependency does not change very often.
• You want to modify the dependency's code as part of your main project.

How git subtree Works

The git subtree command allows you to place another repository into a subdirectory of your main project. For anyone cloning your project, the subtree's files will look like any other folder. There are no extra steps or commands required for them, which is a significant advantage.

Adding a Subtree

You can add a subtree using the git subtree add command. It's recommended to use the --squash flag to condense the entire history of the external project into a single commit. This keeps your main project's history clean and manageable.

$ git subtree add --prefix=vendor/my-dependency https://github.com/some-user/some-lib.git main --squash

• --prefix: The subdirectory where the dependency will be placed.
• https://github.com/some-user/some-lib.git: The URL of the repository you want to add.
• main: The branch to pull from.

Pulling Updates from a Subtree

To update the dependency with the latest changes from its remote, you use git subtree pull.

$ git subtree pull --prefix=vendor/my-dependency https://github.com/some-user/some-lib.git main --squash

Subtrees vs. Submodules

Choosing between a subtree and a submodule depends on your project's needs. Here’s a comparison to help you decide: