使用子树拆分将变更推送回上游

Subtree is not just for pulling code in. One of its strengths is the ability to contribute changes back to the original project. This makes subtree a genuine two-way integration tool.

The key command is git subtree push, powered internally by git subtree split.

git subtree split walks your history and produces a synthetic branch containing only the commits that touched the subtree's prefix, rewritten as if that folder were the repo root.

This is what makes the changes mergeable back upstream.

Assume you added an upstream library under vendor/widget earlier. Now you have made improvements there and want to share them.

Run split to create a branch with just the subtree's history rebased to the prefix root.

Check out the split branch and confirm its files live at the root, not under vendor/widget. This proves the rewrite worked.

You can split and push in a single command. git subtree push does the split internally and pushes the result to the upstream remote and branch.

Push to a feature branch on a fork you control, then open a pull request upstream. Your subtree commits appear as ordinary commits on that project, ready for review.

On large histories, split can be slow because it re-walks commits. Subtree caches rewrites; passing --rejoin writes a merge commit so future splits start from there.

Split works cleanly only when commits are scoped. A commit touching both the subtree and unrelated app code becomes awkward upstream. Keep subtree changes in their own focused commits.

Push upstream when your fixes are general-purpose and the maintainers accept contributions. For private, repo-specific tweaks, keep them local and never push them back.

After upstream merges your contribution, pull it back into the subtree so your superproject and the original project converge again, closing the round trip.

Test your understanding of subtree split and push.

You learned the two-way subtree workflow: split isolates subtree commits into a prefix-rooted branch, push sends them upstream in one step, --rejoin speeds up repeated splits, and keeping commits focused makes upstream contribution clean.