What does git subtree add --prefix do to your repository's files and history?

## What the command is for `git subtree` is a way to *vendor* another repository — to keep a copy of its code inside your own repository, under a directory you choose, while still being able to pull newer upstream versions later. The command ships with Git in its `contrib` area and is present in most distributions' Git packages. The entry point is: `git subtree add --prefix=<dir> <repository> <ref>` `--prefix` (short form `-P`) names the directory the foreign code will live in. `<repository>` is a URL or the name of a remote you have already configured. `<ref>` is the branch or tag in that repository you want to import. The command insists on being run from the top level of the working tree, and it refuses to run if `<dir>` already exists or if you have uncommitted changes. ## What happens to your files Git fetches the requested ref, takes the tree of that commit, and grafts it into your tree at `<dir>`. Afterwards those files are ordinary tracked files: `git status` sees them, `git grep` finds them, your build reads them straight off disk. There is no special object type involved and nothing that a later `git clone` has to be told to resolve. That is the entire point of the technique — a consumer who does nothing but `git clone` gets a working checkout. ## What happens to your history This is where people are surprised. Two shapes are possible. **Without `--squash`**, the import is a **merge commit with two parents**: your previous `HEAD` and the fetched upstream commit. Because the upstream commit is now an ancestor of yours, every commit from that other project becomes part of your repository's history. `git log` will show them interleaved with your own work, and their file paths are the paths that project used — usually *not* prefixed by `<dir>` — because those old commits are not rewritten. Only the merge places the content at the prefix. **With `--squash`**, Git collapses the upstream history into a single synthetic commit whose message reads like `Squashed '<dir>/' content from commit <short-sha>`, and merges that. Your history gains one commit per import instead of hundreds, and the foreign project's commits are not reachable from your branch. ## The bookkeeping Git leaves behind Subtree commits carry machine-readable lines at the end of the commit message: `git-subtree-dir: <dir>` and `git-subtree-split: <upstream-sha>` These are how later `git subtree pull` and `git subtree split` invocations discover which prefix an import belongs to and which upstream commit was last imported. If someone rewrites or drops those commit messages, subtree loses its memory of the relationship and later operations get confused. There is no separate config file recording the link — unlike `.gitmodules` for submodules, the relationship lives only in commit messages, so you cannot see at a glance from a working tree which directories are vendored. ## Everyday consequences - Updates are deliberate: `git subtree pull --prefix=<dir> <repo> <ref>` merges newer upstream code in and can conflict like any merge, which you resolve normally. - Local edits inside the prefix are just edits — nothing stops you making them, and nothing sends them upstream automatically. - Your repository grows by the size of the vendored content, and (without `--squash`) by the whole imported history. - Because file paths inside the prefix did not exist in the upstream commits, `git log <dir>` and `git blame` across the import boundary can look discontinuous. ## Common mistakes Running the command from a subdirectory fails outright. Forgetting `--prefix` and passing a bare path fails as well — the option is required. Adding into an existing directory fails; if you already copied the code in by hand you must remove it and commit that first. And choosing `--squash` on the initial add but omitting it on later pulls (or vice versa) produces awkward history, so pick one mode per prefix and keep to it.