Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
git replace <object> <replacement>
git replace --graft <commit> [<parent>...]
git replace -l
git replace -d <object>

Try it

Bash Graft new parents onto a commit

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 Replace a blob, list and delete

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 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 normal git clone or git fetch does not transfer them; fetch them explicitly with git fetch origin 'refs/replace/*:refs/replace/*'.
  • Everything honours them unless you opt out: use git --no-replace-objects <command> or set GIT_NO_REPLACE_OBJECTS=1 to see the real objects.
  • Replacing a commit does not change its ID. Child commits still name the original parent, so git log shows 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 log may not match what others see.
  • --graft is the modern grafts file. Grafts in .git/info/grafts are deprecated; the replace mechanism is the portable equivalent.
  • To make a replacement permanent, rewrite the history with git filter-branch or 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.