Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
git clone --depth 1 <url>        # creates .git/shallow
git fetch --unshallow            # removes it
git replace --graft <commit> [<new-parent>...]

Try it

Bash A shallow clone and its boundary file

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 Grafting with git replace

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

Terminal
# .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 1 is much faster for build jobs. Anything that needs history (git describe, version-from-tags scripts, git log since a tag) may break, so fetch more or unshallow.
  • git rev-parse --is-shallow-repository tells 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=1 or --no-replace-objects turns 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 with git filter-repo/rebase --onto.
  • Do not edit .git/shallow by hand. An incorrect entry leads to "bad object" errors. Use --unshallow.
  • Partial clone is different. --filter=blob:none keeps all commits but skips file contents; it needs no shallow file.