'\" t
.\"     Title: git-replace
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: 01/13/2026
.\"    Manual: Git Manual
.\"    Source: Git 1.8.3.1
.\"  Language: English
.\"
.TH "GIT\-REPLACE" "1" "01/13/2026" "Git 1\&.8\&.3\&.1" "Git Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
git-replace \- Create, list, delete refs to replace objects
.SH "SYNOPSIS"
.sp
.nf
\fIgit replace\fR [\-f] <object> <replacement>
\fIgit replace\fR \-d <object>\&...
\fIgit replace\fR \-l [<pattern>]
.fi
.sp
.SH "DESCRIPTION"
.sp
Adds a \fIreplace\fR reference in refs/replace/ namespace\&.
.sp
The name of the \fIreplace\fR reference is the SHA\-1 of the object that is replaced\&. The content of the \fIreplace\fR reference is the SHA\-1 of the replacement object\&.
.sp
Unless \-f is given, the \fIreplace\fR reference must not yet exist\&.
.sp
Replacement references will be used by default by all Git commands except those doing reachability traversal (prune, pack transfer and fsck)\&.
.sp
It is possible to disable use of replacement references for any command using the \-\-no\-replace\-objects option just after \fIgit\fR\&.
.sp
For example if commit \fIfoo\fR has been replaced by commit \fIbar\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
$ git \-\-no\-replace\-objects cat\-file commit foo
.fi
.if n \{\
.RE
.\}
.sp
.sp
shows information about commit \fIfoo\fR, while:
.sp
.if n \{\
.RS 4
.\}
.nf
$ git cat\-file commit foo
.fi
.if n \{\
.RE
.\}
.sp
.sp
shows information about commit \fIbar\fR\&.
.sp
The \fIGIT_NO_REPLACE_OBJECTS\fR environment variable can be set to achieve the same effect as the \-\-no\-replace\-objects option\&.
.SH "OPTIONS"
.PP
\-f
.RS 4
If an existing replace ref for the same object exists, it will be overwritten (instead of failing)\&.
.RE
.PP
\-d
.RS 4
Delete existing replace refs for the given objects\&.
.RE
.PP
\-l <pattern>
.RS 4
List replace refs for objects that match the given pattern (or all if no pattern is given)\&. Typing "git replace" without arguments, also lists all replace refs\&.
.RE
.SH "BUGS"
.sp
Comparing blobs or trees that have been replaced with those that replace them will not work properly\&. And using git reset \-\-hard to go back to a replaced commit will move the branch to the replacement commit instead of the replaced commit\&.
.sp
There may be other problems when using \fIgit rev\-list\fR related to pending objects\&. And of course things may break if an object of one type is replaced by an object of another type (for example a blob replaced by a commit)\&.
.SH "SEE ALSO"
.sp
\fBgit-tag\fR(1) \fBgit-branch\fR(1) \fBgit\fR(1)
.SH "GIT"
.sp
Part of the \fBgit\fR(1) suite
