Introduction

git subtree push does not push your whole branch. It pushes the split history of one subdirectory as if that subdirectory were its own repository. That is why the subtree can look “up to date” from one point of view while the push still fails or does nothing useful. The command only cares about commits that affect the subtree prefix and how that split history relates to the target remote branch.

What git subtree push Actually Does

When you run a command such as this:

git subtree push --prefix=vendor/lib lib-remote main

Git effectively performs a subtree split for vendor/lib and then tries to push that split commit history to lib-remote/main.

So the key questions are not “is my main branch up to date” but these:

• did I make any commits that touched the subtree prefix
• does the remote branch accept the split history being pushed
• does the remote branch already contain that subtree split

A Common Reason Nothing Happens

If you made commits in the main repository but none of them changed files under the subtree prefix, then the subtree split may be identical to the last one. In that case, git subtree push has nothing new to send even though your main branch itself has moved forward.

That is expected behavior.

You can inspect subtree-relevant history directly:

git log --oneline -- vendor/lib

If there are no new commits affecting that path, a subtree push will not produce a new split commit.

Another Common Problem: Remote History Diverged

The target remote branch may not be a fast-forward descendant of the split history you are trying to push. That happens if someone pushed directly to the subtree repository or if the subtree was imported in a different way.

A useful diagnostic step is to generate the split commit explicitly:

git subtree split --prefix=vendor/lib -b subtree-temp

Then inspect or push it manually:

git log --oneline subtree-temp

git push lib-remote subtree-temp:main

That makes it clearer whether the problem is with the split itself or with the shorthand subtree command.

Make Sure the Prefix Is Exactly Right

git subtree is strict about the prefix. If the path is wrong, or if you renamed the subtree directory without updating your commands, Git will split the wrong history or no useful history at all.

Check the exact path in the repository and reuse the same prefix consistently across add, pull, split, and push operations.

When the Subtree Repository Was Updated Elsewhere

If the standalone subtree repository received new commits directly, you may need to pull those changes back into the main repository before trying to push again.

That usually looks like this:

git subtree pull --prefix=vendor/lib lib-remote main --squash

After reconciling the subtree history locally, the next push is much more likely to work cleanly.

Common Pitfalls

A common mistake is assuming “my branch is up to date” means “my subtree split is up to date.” Those are different histories.

Another mistake is forgetting that only commits touching the subtree prefix matter for git subtree push.

A third issue is debugging the push without first inspecting the split commit explicitly. git subtree split often makes the actual state much easier to understand.

Summary

• 'git subtree push pushes the split history of one directory, not the whole branch'
• A main branch can move forward without creating any new subtree history
• Remote divergence can block the push even when the local branch feels current
• Use git log -- <prefix> and git subtree split to see what Git is really trying to push
• Keep the subtree prefix and workflow consistent across add, pull, split, and push operations