Git Reference ยท Merging and Rebasing
git replace command
Reference for git replace: make Git use a different object in place of another, graft new parents onto a commit, list and delete replacements, and know the risks.
git replace tells Git: whenever you are asked for object A, give me object B instead. It stores that rule as a ref under refs/replace/, named after the ID of the object being replaced, and pointing at the substitute. Nothing in the object database is rewritten: the original object is still there and still has the same ID, and all other commits that refer to it keep working.
The classic uses are repairing or reshaping history without rewriting it. You can stitch two histories together (for example an imported archive and the modern repository), hide a bad commit from git log, or temporarily test a fix before doing a real rewrite with git filter-branch. Because the rules are ordinary refs, they are local until you push them.
git replace <object> <replacement> git replace --graft <commit> [<parent>...] git replace -l git replace -d <object>
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 replace [-f] <object> <replacement> git replace [-f] --edit <object> git replace [-f] --graft <commit> [<parent>...] git replace [-f] --convert-graft-file git replace -d <object>... git replace [--format=<format>] [-l [<pattern>]]
| Name | Description |
|---|---|
<object> |
The object to hide. It can be a blob, tree, commit or tag. |
<replacement> |
The object to show instead. It must have the same type as <object>, unless -f is given. |
-f, --force |
Overwrite an existing replacement, or allow replacing with an object of a different type. |
--edit <object> |
Open the object in your editor, write the edited version as a new object and replace the original with it. |
--graft <commit> [<parent>...] |
Create a copy of <commit> with the listed parents and replace the original with it. With no parent, the copy has none (it becomes a root). |
--convert-graft-file |
Turn each entry of the legacy .git/info/grafts file into a replacement and delete the file. |
-d <object>... |
Delete the replacement for each object. |
-l [<pattern>], --list |
List replaced objects, optionally filtered by a glob pattern. This is the default when no other action is given. |
--format=short|medium|long |
With --list: only the replaced ID (short, default), replaced -> replacement (medium), or the same with object types (long). |
Errors: Git refuses to replace when a replacement already exists (use -f), when the types differ, or when <object> and <replacement> are the same object.
Usage notes
- Replacements are refs. They live in
refs/replace/and can be pushed, fetched or deleted like any other ref. A normalgit cloneorgit fetchdoes not transfer them; fetch them explicitly withgit fetch origin 'refs/replace/*:refs/replace/*'. - Everything honours them unless you opt out: use
git --no-replace-objects <command>or setGIT_NO_REPLACE_OBJECTS=1to see the real objects. - Replacing a commit does not change its ID. Child commits still name the original parent, so
git logshows the substitute's content under the old ID. Tools that look at raw objects (git cat-file, many servers) may disagree with what you see. - Servers ignore them. Hosting sites do not apply your local replacements, so what you see in
git logmay not match what others see. --graftis the modern grafts file. Grafts in.git/info/graftsare deprecated; the replace mechanism is the portable equivalent.- To make a replacement permanent, rewrite the history with
git filter-branchor a similar tool, then delete the replacement. - Be careful with garbage collection: a replacement ref keeps its substitute object alive, which is usually what you want.