Hook (1-2 sentences): You have a large monorepo and someone needs access to exactly one subfolder — not the whole thing. Giving them the entire repository isn't an option, but you also don't want to manually sync changes into a separate copy forever.
Why It Matters (2-4 sentences): Without a structured approach, you're stuck choosing between granting overly broad repository access or maintaining a manually-synced copy that inevitably drifts. Git subtree filtering lets you carve out a subfolder into its own standalone repository while preserving a clean path to pull updates from the source. This pattern is particularly useful for security reviews, open-sourcing a subset of private code, or sharing utilities with external teams — without coupling them to your entire codebase.
What You'll Learn
- Understand the three-branch strategy that keeps your filtered repo in sync with the source
- Clone a source repository and rewrite its history down to a single subfolder using
git filter-branch - Wire the filtered content as a remote into a new standalone repository
- Pull upstream changes into the filtered branch and merge selectively into your own work
- Recognize when this approach beats alternatives like git submodules or manual copying
Three-Branch Strategy for Clean Subfolder Extraction
The core insight here is maintaining three named branches that each serve a distinct role:
upstream-repo— a full clone of the source repository, no modificationsupstream-filter— the same source, but withgit filter-branch --subdirectory-filter <path>applied to rewrite history so only the target subfolder remainsmain— your working branch, rebased or merged fromupstream-filter
The setup starts by cloning the source repo into a new directory named after your target project. From there, you create the upstream-repo branch to track the original, then derive upstream-filter by running the subdirectory filter — this rewrites the entire commit history so the subfolder appears as the repo root.
The new standalone repository then adds the filtered branch as a remote. When the source team pushes updates, your workflow is: pull into upstream-repo, re-apply the subdirectory filter to get an updated upstream-filter, then merge or rebase upstream-filter into main.
A few things worth knowing before you use this in production: git filter-branch is considered legacy — the Git project now recommends git-filter-repo for the same job, and it's significantly faster on large histories. Also, the subdirectory filter rewrites commit SHAs, so anyone else working off filtered branches will need to re-clone after you re-filter. This is a one-way, one-maintainer workflow — it doesn't work well if multiple people are re-filtering independently.
The original StackOverflow thread that inspired the video is worth reading for edge cases: it covers how to handle the case where the subfolder path has changed over time in the source repo.
