Adding and Merging with Subtree

Welcome! In this lesson, we'll dive into Git Subtree, a powerful way to integrate another Git repository directly into your project.

Unlike submodules, subtree merges the external repository's history into your own, making it feel like a native part of your project.

Subtree offers a simpler workflow than submodules for many cases. Here are a few benefits:

• No special commands: Once added, you work with subtree content like regular files.
• Single repository: No separate .git directories or complex submodule initializations.
• Easier for consumers: Others cloning your project don't need to learn special submodule commands.

Before adding a subtree, ensure your main repository is in a clean state (no uncommitted changes). You'll need:

• The URL of the external repository.
• The branch or commit you want to integrate (e.g., main or master).
• A chosen path within your main repository for the subtree.

To add an external repository as a subtree, you use the git subtree add command. It looks like this:

git subtree add --prefix=<path> <repository> <ref>

• --prefix=<path>: The directory in your project where the subtree will reside.
• <repository>: The URL of the external Git repository.
• <ref>: The branch (e.g., main) or commit hash from the external repo.

Let's say you want to add a shared utility-library from a separate Git repository into a src/shared folder in your current project. You would use:

git subtree add --prefix=src/shared/utility-library https://github.com/myorg/utility-library.git main

This command fetches the utility-library's main branch and integrates its history into your src/shared/utility-library directory.

When adding a subtree, you'll often see the --squash option:

git subtree add --prefix=path repo_url main --squash

The --squash flag combines all commits from the external repository's history into a single commit in your main project. This keeps your main project's history cleaner, but you lose the individual commit details from the subtree's original history.

After you've added a subtree, the original external repository might receive new updates. To keep your integrated code current with the upstream source, you'll need to pull those changes.

This ensures your project always has the latest versions of the shared components or libraries you've included as a subtree.

To pull updates from an upstream subtree, you use a similar command structure:

git subtree pull --prefix=<path> <repository> <ref>

Notice it uses the same --prefix, <repository>, and <ref> as when you added it. Git uses these to identify the correct upstream source for your subtree.

Let's continue with our utility-library example. To pull the latest changes from its main branch into your project, you'd run:

git subtree pull --prefix=src/shared/utility-library https://github.com/myorg/utility-library.git main

This command fetches and merges any new commits from the utility-library's main branch into your local src/shared/utility-library directory.

Which command is used to initially incorporate an external repository as a subtree into your project, creating a new directory for it?

You've learned how to integrate external repositories using Git Subtree!

• Use git subtree add with --prefix, repository URL, and branch to bring external code into your project.
• The --squash option helps keep your main project's history clean.
• Use git subtree pull with the same parameters to fetch and merge upstream updates into your subtree.

Subtree provides a powerful, integrated alternative to submodules for managing shared code!