git-replace

Replace any commit with a different one, leaving other commits unchanged

$ git replace [object] [replacement]

$ git replace [[-d|--delete]] [object]

$ git replace --edit [object]

git replace [-f] [-m <message>] <object> <replacement>
git replace -d <object>...
git replace -l [<pattern>]
git replace --edit <object>

-f, --force
    Overwrite existing replacement ref if present

-m <message>, --message <message>
    Set custom message for the replacement ref

-d, --delete
    Delete replacement refs for specified objects

-l [<pattern>], --list [<pattern>]
    List refs/replace/ refs matching glob pattern (default: all)

-e, --edit
    Interactively edit existing replacement ref

git replace creates, lists, deletes, or edits replacement refs in the refs/replace/ namespace. These refs substitute one Git object (commit, tree, blob, or tag) with another during most Git operations, enabling local history experiments without rewriting the actual repository.

For instance, replace a buggy commit with a fixed one: git replace <bad-commit> <good-commit>. Commands like git log, git show, and git merge-base then treat the replacement as the original, transparently.

Unlike grafts (now deprecated), replace refs are refs, queryable via git for-each-ref and shareable via push. They bypass object storage checks, so use cautiously. Edit refs with --edit to tweak messages or targets interactively. List with -l, delete with -d. Ideal for testing rewrites, simulating shallow histories, or prototyping filters before full application.

Replacements are local by default; push with git push <remote> 'refs/replace/*:refs/replace/*'. Bypassed by --no-replace-objects. Ignored by git fsck and git gc; may confuse shared repos. Objects must exist.

Use SHA-1, ref names, or rev-parse expressions for <object> and <replacement>. Supports commits, trees, blobs, tags.

Introduced in Git 1.6.0 (2008) to replace deprecated grafts mechanism, fully removing grafts in Git 2.23.0 (2019). Enhanced with edit support in later versions for better usability.

git(1), gitnotes(1), git-update-ref(1)