What are the trade-offs of git subtree versus git submodule for someone who only clones your repo?

## Two ways to depend on another repository Git offers two built-in mechanisms for keeping another project's code inside yours, and they sit at opposite ends of one trade-off. **Submodule**: your tree contains a special entry — a *gitlink* — that records the path plus one commit SHA of the other repository, with the URL stored in a tracked `.gitmodules` file. The other project's objects live in their own repository, fetched separately. **Subtree**: the other project's files are copied into a directory of your repository as ordinary blobs and trees, imported by `git subtree add --prefix=<dir>` and refreshed by `git subtree pull --prefix=<dir>`. ## What the consumer experiences This is the axis interviewers care about, because it is where teams get burned. With a subtree, someone who runs `git clone <your-repo>` has a complete, buildable checkout. So does `git archive`, so does a downloaded snapshot, so does a CI job that does a plain checkout, and so does a colleague who has never heard of subtree. Nothing can be forgotten because there is nothing to remember. With a submodule, a plain clone produces an empty directory where the dependency should be. The consumer needs `git clone --recurse-submodules`, or `git submodule update --init` after the fact. Every tool in the chain — CI checkout steps, release tarball generation, IDE clone helpers — must also be taught to recurse. Once inside a submodule the working tree sits at a detached HEAD by default, which reliably confuses people who edit there. ## What each costs the maintainer Subtree costs you repository weight and history clarity: - The dependency's bytes are in your object database forever, and every clone of your repository pays for them. - Imported without `--squash`, the upstream project's commits become ancestors of yours, so `git log`, `git shortlog` and even `git bisect` traverse someone else's work. - The pinned version is not visible in the tree. It exists only in the `git-subtree-split: <sha>` line of import commits, so "which version of this library are we on?" is a history question, not a file question. - Sending local fixes upstream needs a deliberate `git subtree split` / `git subtree push`, not a normal push. Submodules cost you consumer friction, but buy clarity: - The pinned SHA is an object in your tree, so a diff literally shows the version bump as a one-line change. - Your repository stays small; the dependency's history is never yours. - Working *in* the dependency is natural, because it really is a separate repository with its own branches. ## Choosing Prefer subtree when the population of consumers is large or uncontrolled: open-source projects that want `git clone && make` to work, teams whose CI or release process only ever does a plain checkout, code that ships as a source tarball, or a small vendored dependency you rarely update. Prefer submodules when the dependency is big, actively co-developed by the same people, or needs an obvious auditable version pin — and when you can guarantee everyone's tooling recurses. A useful decision heuristic: subtree moves the pain to the maintainer, submodule moves it to the consumer. Count consumers. ## Switching between them Going from submodule to subtree is straightforward: remove the submodule and its `.gitmodules` entry, commit, then `git subtree add --prefix=<same-dir>` the same URL and ref. Going the other way means deleting the vendored directory, committing, then `git submodule add`. Neither direction is free — both rewrite what the tree looks like at that path, and both mean everyone with an existing checkout does a cleanup step, so the switch is a decision you want to make once. ## What weak answers miss The answer "subtree is easier" is not enough on its own. The complete answer names *who* it is easier for and what that ease is paid for with: plain clones work, at the price of a heavier repository, a mixed history, and a version pin visible only from commit metadata. And it names the failure mode on the other side by its symptom — an empty directory after a plain clone, followed by a build that cannot find the dependency.