Git Reference ยท Files and Formats
The shallow file and grafts
Reference for .git/shallow (shallow-clone boundary commits), the retired info/grafts file, and git replace as the modern way to change how history is connected.
Git normally assumes that every commit's parents exist locally. Two mechanisms let a repository pretend otherwise. The shallow file records commits whose parents were deliberately not downloaded; it is how git clone --depth and git fetch --depth work. The grafts file (.git/info/grafts) was the old way to fake a different parent list; it has been replaced by git replace.
Understanding both helps when a shallow clone behaves oddly, when you see "shallow update not allowed", or when you want to stitch two histories together.
git clone --depth 1 <url> # creates .git/shallow git fetch --unshallow # removes it git replace --graft <commit> [<new-parent>...]
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
# .git/shallow: one full commit ID per line <commit-id>
| Item | Description |
|---|---|
.git/shallow |
Commits that are shallow boundaries: Git treats them as having no parents, even though the original did. |
--depth=<n> |
Clone or fetch only n commits of history from each tip. |
--shallow-since=<date>, --shallow-exclude=<ref> |
Limit history by date or by excluding what a ref already reaches. |
--deepen=<n> |
Extend history by n more commits. |
--unshallow |
Fetch everything missing and delete .git/shallow. |
.git/info/grafts |
Old format: <commit> <parent1> <parent2>... per line, replacing that commit's parents. Deprecated since Git 2.18; may still be read if present. |
git replace --graft <commit> [<parent>...] |
Creates a replacement commit under refs/replace/ with the given parents. |
git replace --convert-graft-file |
Turn an old grafts file into replace refs. |
Edge cases: a shallow repository cannot always push or serve clones to others (older servers refuse). Pushing from one is allowed with modern Git. Operations that walk full history (git log --all, merge-base across the cut) see only what exists.
Usage notes
- CI uses it for speed.
--depth 1is much faster for build jobs. Anything that needs history (git describe, version-from-tags scripts,git logsince a tag) may break, so fetch more or unshallow. git rev-parse --is-shallow-repositorytells scripts whether the history is truncated.- Merge bases are unreliable near the boundary, so shallow-then-merge can fail with "refusing to merge unrelated histories".
- Replace refs are normal refs. They are fetched and pushed only if you ask (
refs/replace/*).GIT_NO_REPLACE_OBJECTS=1or--no-replace-objectsturns them off, which is the quick test for whether they are the problem. - Do not use grafts in new work. They were local-only, easy to forget, and ignored by many tools. Use
git replace, or rewrite history properly withgit filter-repo/rebase --onto. - Do not edit
.git/shallowby hand. An incorrect entry leads to "bad object" errors. Use--unshallow. - Partial clone is different.
--filter=blob:nonekeeps all commits but skips file contents; it needs no shallow file.