git replace

Patching & Rewriting

Replace an object with another one, without rewriting history


The 'git replace' command tells Git to use one object instead of another wherever it appears — for example to graft an old history onto a new one, or to hide a broken commit — without rewriting any commit. Replacements are stored as refs under refs/replace/ and can be shared or removed. Most commands follow them; git log marks replaced commits.

Synopsis

git replace [-f] <object> <replacement>
git replace --graft <commit> [<parent>...]
git replace -d <object>...
git replace -l
[ ] optional| or<arg> placeholder... repeatable--flag option

Examples

Graft a history

git replace --graft <first-new-commit> <last-old-commit>

Connect an imported old history.


List

git replace -l

Replaced objects.


Undo

git replace -d <object>

Remove a replacement.

Workflow Examples

1
git fetch old-repo

Get the old commits

2
git replace --graft <new-root> old/main

Make the new root continue the old history

Troubleshooting

Replacement not visible for others

Cause: refs/replace is not pushed by default

git push origin "refs/replace/*"

Tips & Pitfalls

Best Practices

  • ✓Use --graft for joining histories; avoid replacements for everyday fixes.

Common Mistakes

  • ✗Forgetting replacements are local unless you push refs/replace/*.

FAQ

A:

Yes: git --no-replace-objects <command>.