Introduction to Git Subtree

Welcome! In this lesson, we'll explore Git Subtree. It's a way to embed another Git repository inside your own, essentially merging its history and files into a subdirectory.

Think of it as an alternative to Git Submodules for managing external dependencies or shared code within a single project.

The core difference between Subtree and Submodule lies in how they integrate external code:

• Submodules: Store a reference (a specific commit hash) to an external repository. The external code lives separately, managed as a distinct repository.
• Subtree: Integrates the external repository's code and its history directly into your main repository. It's like a deep copy with the ability to link back to the original.

When you add a subtree, Git performs a specialized merge operation. It takes the history of the external repository and 'rewrites' it to appear as if it always existed within a specific subdirectory of your main project.

This means you can treat the subtree's files just like any other files in your repository, using standard Git commands.

One major advantage of Git Subtree is its simplicity. There are no special .gitmodules files to track, nor do you need to initialize or update submodules after cloning.

Your entire project, including the subtree's content, is managed with standard Git commands like git clone and git pull.

With Git Subtree, all your code lives in a single repository. This can simplify several aspects of development:

• Cloning: A single git clone command fetches everything.
• Branching: Changes across your main project and the subtree can be made on one branch.
• CI/CD: Builds and tests typically don't need to fetch separate repositories.

Many developers find subtrees easier to work with. Collaborators don't need to learn new Git commands specific to submodules or deal with their unique quirks.

The external code is simply part of the main repository, reducing potential friction when setting up development environments or fetching updates.

To add a new external project as a subtree, you use the git subtree add command. You'll specify:

• The prefix (the subdirectory where it will live).
• The URL of the external repository.
• The branch you want to pull from (e.g., main or master).

Let's say you want to add a common utility library from GitHub into a vendor/utils directory in your project:

Notice the --squash option in the previous example. This is very useful when adding a subtree!

It takes all the commits from the external repository's history and condenses them into a single commit when adding them to your main project. This prevents your main repository's history from being cluttered with potentially hundreds of commits from the external project.

Git Subtree offers distinct advantages over submodules in certain scenarios. Let's test your understanding.

Great job! In this lesson, we introduced Git Subtree, a powerful alternative to submodules for integrating external projects. You learned that subtrees merge external code directly into your repository, simplifying workflows and keeping all code in one place.

We also covered the git subtree add command and the benefit of the --squash option for cleaner history.