git replace

Local-only object aliasing. Niche, occasionally lifesaving.

🎯 What & why

git replace lets you swap one object for another at lookup time, without rewriting history. It's the surgical alternative to filter-branch.

🧠 Mental model

A replacement is a local-only redirect stored in refs/replace/<sha>. When Git looks up <sha>, it transparently returns the replacement instead. Original objects stay; SHAs don't change.

🛠️ Synopsis

git replace [-f] <object> <replacement>
git replace --edit [-f] <object>
git replace --graft <commit> [<parent>...]
git replace --convert-graft-file
git replace -d <object>...
git replace -l [<pattern>]

🎚️ Switches & options

Flag	What it does
`--edit`	Open the object in your editor; the edited result becomes the replacement. Best UX for fixing one bad commit message in deep history.
`--graft <c> [<p>...]`	Rewrite a commit's parents only. The killer feature: stitch a shallow clone to historical archive.
`--convert-graft-file`	Migrate the legacy `.git/info/grafts` file (deprecated) into proper replace refs.
`-l / --list`	List existing replacements, optionally matching a glob.
`-d / --delete`	Remove a replacement, restoring the original lookup.
`-f / --force`	⚠️ Overwrite an existing replacement without complaining. Easy to clobber a teammate's grafts on a shared repo.
`--raw`	On `--edit`, present the raw object bytes instead of the parsed form.

📦 Subcommands

--edit — Edit an object in place to produce its replacement.

git replace --edit deadbeef

--graft — Replace a commit with a copy that has different parents.

git replace --graft HEAD~5 abc1234

--convert-graft-file — One-shot migration from the old grafts mechanism.

git replace --convert-graft-file

--list — Show all replacements.

git replace -l

--delete — Drop a replacement.

git replace -d deadbeef

💡 Use cases

Stitching an imported shallow history onto an older archive without rewriting SHAs.
Locally fixing a commit message or author in deep history for personal sanity, without breaking everyone's clones.
Migrating from the deprecated .git/info/grafts file to a supported mechanism.
Experimenting with alternate histories — bisecting against a what-if parent — without committing to a rewrite.

🧪 Examples

Reparent a commit (graft)

git replace --graft 1a2b3c4 deadbeef cafef00d

Edit an object

git replace --edit 1a2b3c4

List replacements

git replace -l

Remove a replacement

git replace -d 1a2b3c4

🎓 Recommendations

Use --graft when joining histories; it's the cleanest way to bridge a --depth=1 clone with a legacy archive.
Push replacements explicitly with git push origin 'refs/replace/*' if you want collaborators to see them — they don't propagate by default.
Document any active replacements in the repo README. Future you, debugging a SHA mismatch, will thank present you.

🪤 Common pitfalls

Replacements don't propagate via push by default. Your local fix is invisible to everyone else unless you also push refs/replace/*.
Tools that walk the object graph directly (some signing/verification scripts) bypass replace refs and see the original.
Forgetting an active replacement causes 'why does this commit show different parents than yesterday?' confusion. Always git replace -l when debugging weird history.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.