Git Reference ยท Remotes and Collaboration
git subtree command
Reference for git subtree: add, pull, push, split and merge another project into a subdirectory, and the read-tree and merge -s subtree plumbing behind it.
git subtree keeps the history of another project inside a folder of your repository. Unlike a submodule, nothing is a pointer: the files and (optionally) the commits of the other project become ordinary content of your own history. Everyone who clones your repository gets everything, with no extra commands.
git subtree ships in Git's contrib area and is installed with most distributions, but it is a shell script outside the core. It is not available on this site's runner, so the live examples below use the plumbing it is built on: git read-tree --prefix and the subtree merge strategy. The git subtree commands themselves are shown as read-only snippets.
git subtree add --prefix=<dir> <repository> <ref> [--squash] git subtree pull --prefix=<dir> <repository> <ref> [--squash] git subtree push --prefix=<dir> <repository> <ref> git subtree split --prefix=<dir> [--branch=<name>] git subtree merge --prefix=<dir> <commit> [--squash]
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Syntax
Typical commands (read-only here, because the runner has no git subtree):
git subtree add --prefix=vendor/lib https://example.com/lib.git main --squash git subtree pull --prefix=vendor/lib https://example.com/lib.git main --squash git subtree push --prefix=vendor/lib https://example.com/lib.git fix-branch git subtree split --prefix=vendor/lib --branch=lib-only
| Option | Description |
|---|---|
-P <dir>, --prefix=<dir> |
The subdirectory, relative to the repository root. Required. |
--squash |
Collapse the other project's history into a single commit on each add or pull, keeping your log short. |
-m <message> |
Message for the merge commit. |
--branch=<name> |
For split: create a branch holding only the history that touched the prefix. |
--rejoin |
For split and push: merge the split history back so future splits are fast. |
--onto=<commit> |
For split: reuse earlier split work. |
Errors: add fails if the prefix already exists; pull and merge need a clean working tree; commands fail from a subdirectory because the prefix is relative to the top level.
Usage notes
- No metadata files. Nothing like
.gitmodulesexists. With--squash,git subtreerecords the upstream commit in the squash commit's message trailers (git-subtree-dir,git-subtree-split), and later commands read those trailers. - Do not mix squash and non-squash for the same prefix; the history it relies on will not line up.
splitis slow on big histories because it walks every commit.--rejoinand caching in the split trailers help.- Edit freely. You can change the files under the prefix in normal commits and later
pushthem upstream withgit subtree push. - The manual route works anywhere:
git read-tree --prefix=<dir>/ -u <commit>for the first import, thengit merge -X subtree=<dir> <commit>for updates (the examples above). Thesubtreestrategy is described in merge strategies. - Submodule or subtree? Choose a subtree when users should not need to learn extra commands and you accept a larger repository. Choose a submodule when you need exact pins and small history.