Git Subtree: Managing Subprojects Within Your Git Repository

What is Git Subtree ? 🔗

Git subtree is a powerful Git technique that allows you to include an entire separate Git repository as a subdirectory within your main project’s repository. This is useful when:

• You have a library or component that’s developed independently.
• You want to contribute to an external project while keeping your main project’s history clean.
• You need to manage multiple versions of a subproject within your main project.
• Manage project dependencies as subprojects.

Key Features of git subtree 🔗

• Independent History: Subtree preserves the complete history of the subproject within your main repository.
• Flexible Updates: You can easily update the subproject to the latest version by merging or cherry-picking commits.
• Clean Integration: Subtree avoids the complexities of submodules, making it easier to work with.

How to Use Git Subtree? 🔗

Add a subtree 🔗

Add a Git repository as a subtree:

git subtree add --prefix=path/to/subproject git://url/of/subproject.git main

or

git subtree add --prefix=path/to/directory/ --squash repository_url/subproject.git branch_name

• --prefix: Specifies the path where the subproject will be added within your main repository.
• git://url/of/subproject.git: The URL of the subproject’s repository.
• repository_url/subproject.git: The URL of the subproject’s repository.
• main: The branch of the subproject to add.

Update the Subtree 🔗

Update subtree repository to its latest commit:

git subtree pull --prefix=path/to/subproject git://url/of/subproject.git main

Push Changes to the Subtree 🔗

Push commits to a subtree repository:

git subtree push --prefix=path/to/subproject git://url/of/subproject.git main

Merge recent changes into subtree (advanced) 🔗

Merge recent changes up to the latest subtree commit into the subtree:

git subtree merge --prefix=path/to/directory/ --squash repository_url branch_name

Extract project history from a subtree (advanced) 🔗

Extract a new project history from the history of a subtree:

git subtree split --prefix=path/to/directory/ repository_url -b branch_name

Advantages of git subtree 🔗

• Simpler than Submodules: Easier to understand and manage compared to Git submodules.
• Clean History: Maintains a clear and linear history for both the main project and the subproject.
• Flexible Integration: Allows for more granular control over which commits from the subproject are included.

Disadvantages of git subtree 🔗

• Can become complex for frequent updates.
• May require more manual intervention than some other techniques.

For more information, check out its Debian manpage .

I hope this post helps you. If you know a person who can benefit from this information, send them a link of this post. If you want to get notified about new posts, follow me on YouTube , Twitter (x) , LinkedIn , and GitHub .