Git subtree

Git's git subtree command is a versatile tool that empowers developers to manage subprojects within a larger repository efficiently. This command enables you to include external repositories as subdirectories in your project, simplifying collaboration and dependency management. We'll explore various ways to use the git subtree command, providing you with a comprehensive guide to enhance your Git workflow.

1. Adding a Subtree:

To include an external repository as a subtree in your project, use the following command: 

bash
git subtree add --prefix=<prefix> <repository> <branch>
  • Replace <prefix> with the subdirectory where you want to add the subtree.
  • Replace <repository> with the URL of the external repository.
  • Replace <branch> with the branch of the external repository you want to include.

For example:

bash
git subtree add --prefix=vendor/library https://github.com/example/library.git main
2. Pulling Updates from the Subtree Repository:

To fetch and merge updates from the subtree repository into your project, use:

bash
git subtree pull --prefix=<prefix> <repository> <branch> --squash
  • Replace <prefix> with the subdirectory where the subtree is located.
  • Replace <repository> with the URL of the external repository.
  • Replace <branch> with the branch of the external repository you want to pull updates from.

For example:

bash
git subtree pull --prefix=vendor/library https://github.com/example/library.git main --squash
3. Pushing Changes to the Subtree Repository:

To push changes from your project to the subtree repository, use:

bash
git subtree push --prefix=<prefix> <repository> <branch>
  • Replace <prefix> with the subdirectory where the subtree is located.
  • Replace <repository> with the URL of the external repository.
  • Replace <branch> with the branch of the external repository where changes should be pushed.

For example:

bash
git subtree push --prefix=vendor/library https://github.com/example/library.git main
4. Splitting a Subdirectory into a Separate Repository:

If you decide to split a subdirectory into its own repository, you can use:

bash
git subtree split --prefix=<prefix> --branch <branch>
  • Replace <prefix> with the subdirectory you want to split.
  • Replace <branch> with the name of the branch for the new repository.

For example:

bash
git subtree split --prefix=vendor/library --branch library-split
5. Merging Changes from the Subtree Repository:

To merge changes from the subtree repository into your project, use:

bash
git subtree merge --prefix=<prefix> <repository> <branch> --squash
  • Replace <prefix> with the subdirectory where the subtree is located.
  • Replace <repository> with the URL of the external repository.
  • Replace <branch> with the branch of the external repository you want to merge.

For example:

bash
git subtree merge --prefix=vendor/library https://github.com/example/library.git main --squash
6. Removing the Subtree:

To remove the subtree from your project, use:

bash
git subtree remove --prefix=<prefix> <repository> <branch>
  • Replace <prefix> with the subdirectory where the subtree is located.
  • Replace <repository> with the URL of the external repository.
  • Replace <branch> with the branch of the external repository.

For example:

bash
git subtree remove --prefix=vendor/library https://github.com/example/library.git main
7. Listing Subtrees:

To list all subtrees in your project, you can use:

bash
git log --graph --oneline --all

Subtrees are typically marked with a prefix, such as (prefix: <prefix>).

8. Customizing Subtree Merging Strategy:

You can customize the subtree merging strategy by specifying the strategy option. For example:

bash
git subtree merge --prefix=<prefix> <repository> <branch> --strategy=subtree --squash

This allows you to choose different strategies for subtree merging.

9. Fetching and Merging Latest Changes:

To fetch and merge the latest changes from the subtree repository, you can use:

bash
git fetch <repository> <branch> && git merge -s subtree --squash <repository>/<branch>

Replace <repository> with the URL of the external repository and <branch> with the branch of the external repository.

10. Working with Subtree as a Remote:

You can treat a subtree as a remote repository by adding it as a remote and fetching changes: 

bash
git remote add -f <subtree-remote> <repository>
git subtree pull --prefix=<prefix> <subtree-remote> <branch> --squash

Replace <subtree-remote> with the name you want to give to the subtree remote.