Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
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

Bash What git subtree add does, by hand

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.

Bash Merging later updates with the subtree strategy

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):

Terminal
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 .gitmodules exists. With --squash, git subtree records 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.
  • split is slow on big histories because it walks every commit. --rejoin and caching in the split trailers help.
  • Edit freely. You can change the files under the prefix in normal commits and later push them upstream with git subtree push.
  • The manual route works anywhere: git read-tree --prefix=<dir>/ -u <commit> for the first import, then git merge -X subtree=<dir> <commit> for updates (the examples above). The subtree strategy 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.