Space
The intelligent code collaboration platform
Space and SpaceCode will be discontinued on June 1, 2025. Learn more → →
Introducing the Space Git Subtree
Does your workflow include any external dependencies? If it does, then you may be interested in using Git subtree to embed the contents of external repositories into your own production repository to be used as a dependency. While the functionality itself is very useful when you need to share or outsource a part of your code, it does come with a few caveats.
To streamline this process, we’re introducing the Space Git subtree with instant bidirectional server-side synchronization and complete automation, so that you can focus on actually coding instead of having to keep everything in sync manually.
In this blog post, we’ll go over the intricacies of the vanilla Git subtree, its pros and cons, and explore how the Space Git subtree improves on this functionality with automation and when to use it.
What is Git subtree?
Git subtree is a native Git functionality that represents a convenient way of embedding multiple Git repositories into a single one as subfolders. It allows you to manage dependencies and incorporate external codebases with their entire history, all while keeping them as separate Git repositories.
Let’s delve into the advantages and disadvantages of using Git subtree to gain a better understanding of its potential benefits and limitations.
Pros of Git subtree
- Ability to include external dependencies or libraries within your project’s repository.
- Manage updates and changes across multiple projects more efficiently and in a unified way.
- Synchronizing forked repos with the original repository’s changes via a simple pull command.
Cons of Git subtree
- Merging changes from the subtree can be tricky, particularly when multiple contributors are working on the same subtree. Resolving conflicts between the main project and the subtree can be challenging.
- Users must be mindful of the required styles for commit messages (e.g. mandatory mentioning issue), GPG signatures, file sizes, and other OS compatibility-related factors that can lead to errors and conflicts.
- Embedding a complete repository branch history into another repository can lead to a cluttered commit history, making it more challenging to track changes and understand the project’s history.
- Including multiple subprojects as subtrees can significantly increase the size of your Git repository, which can make cloning and fetching the repository slower.
- You have to manually manage subtree updates, which can be tedious if you have multiple subprojects.
While Git subtree is undoubtedly a powerful tool, it has a learning curve to it, can be complicated to use, and does require manual oversight. With this in mind, we at Space have decided to streamline and elevate its core functionality, simplifying your daily workflow while keeping subtrees effortlessly in sync.
Introducing the Space Git subtree with instant bidirectional server-side synchronization
Our implementation of Git subtree brings its essential functionality to Space with the added benefit of seamless bidirectional server-side synchronization without having to run a single Git command. You get the perks of using nested repositories while automating the associated manual labor, essentially removing any complexity from your workflow. You can sync any type of folder, whether it’s a subfolder or the root directory that contains the entire repository.
When to use the Space Git subtree
Let’s take a look at two use cases that would greatly benefit from utilizing the Space Git subtree.
Use case 1: Monorepo with an open-source subtree
You have a private monorepo with part of its codebase shared as an open source. Any changes to the source code that touch this subtree should be pushed to the open-source side (i.e. GitHub repository). Occasionally, changes from the open-source code might need to be delivered to the source monorepo in accordance with its existing privacy settings. In this scenario, the main direction of code flowing is from the monorepo to the open-source repository.
Vanilla Git subtree approach
For an open-source repository commit history to make sense, all commits to the subtree repository must be done separately from the updates to the rest of monorepo’s codebase. Then you need to manually push from subtree to the open-source repository to update it.
Due to privacy settings, if you want to bring changes from the open-source side, they’ll have to be extracted as a patch first and then applied to the source codebase. Then, you’ll be able to propagate these changes back to the open-source repository.
The Space Git subtree approach
When this subtree is updated as part of a bigger atomic change of the monorepo, Space detects commits relevant only to the subtree and automatically pushes them to the open-source repository. Since everything is under the security umbrella of the same project, this synchronization will work both ways. You’ll be able to pull the open-source changes directly into your source repository and only have to resolve any conflicts that occur.
Use case 2: Monorepo with an outsourced subtree
Let’s say you have outsourced a part of the code and have added that external repository as a subtree into their private monorepo. The majority of changes come from external sources, which are occasionally amended with quick internal fixes by the company.
A company is using an outsourced code as a dependency subtree within its private monorepo. Even though the bulk of changes comes from the external team, the internal team still has authoritative rights to occasionally amend dependencies with quick-fixes that have to be delivered to the external repository.
Vanilla Git subtree approach
In this scenario, every update on the outsourced repository and any amendments on monorepo’s subtree side will have to be manually propagated back and forth to keep the code as actualized as possible.
The Space Git subtree approach
Any changes on the outsourced side are automatically synchronized with monorepo’s subtree. When a quick-fix is applied by the internal team, it will be immediately synchronized with the outsource side to allow the external team to adjust to the new data.
As you can see, the Space Git subtree offers instant and automatic synchronization, which can be used in projects of various complexity. Regardless of where the changes occur, the server will make sure the changes are synchronized between both ends.
How to use the Space Git subtree
Setting up the Space Git subtree does not require you to run any Git commands and is done on a repository level with just a few clicks. See our help guide section for all available setup options.
The main condition for using the Space Git subtree in a project is that repositories must be under the same project to comply with its security and access settings. In case you need to link an external repository hosted outside of Space, you can do so by creating its mirror first and then linking that mirror to your main project repo using our subtree.
Note that while the Space Git subtree offers two-way synchronization, it’s best utilized for projects that don’t involve regular simultaneous updates of the synced repos, as it could potentially lead to conflicts. Git subtree is best suited for scenarios where you are actively updating one source only.
We hope that this functionality will eliminate the redundancy of manually maintaining Git subtree structure and help your team to be more focused on the code itself.
Subscribe to Space Blog updates
