summaryrefslogtreecommitdiff
path: root/Documentation/git-replace.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/git-replace.txt')
-rw-r--r--Documentation/git-replace.txt91
1 files changed, 81 insertions, 10 deletions
diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt
index 17df525275..8fff598fd6 100644
--- a/Documentation/git-replace.txt
+++ b/Documentation/git-replace.txt
@@ -9,21 +9,28 @@ SYNOPSIS
--------
[verse]
'git replace' [-f] <object> <replacement>
+'git replace' [-f] --edit <object>
+'git replace' [-f] --graft <commit> [<parent>...]
'git replace' -d <object>...
-'git replace' -l [<pattern>]
+'git replace' [--format=<format>] [-l [<pattern>]]
DESCRIPTION
-----------
-Adds a 'replace' reference in `.git/refs/replace/`
+Adds a 'replace' reference in `refs/replace/` namespace.
-The name of the 'replace' reference is the SHA1 of the object that is
-replaced. The content of the 'replace' reference is the SHA1 of the
+The name of the 'replace' reference is the SHA-1 of the object that is
+replaced. The content of the 'replace' reference is the SHA-1 of the
replacement object.
-Unless `-f` is given, the 'replace' reference must not yet exist in
-`.git/refs/replace/` directory.
+The replaced object and the replacement object must be of the same type.
+This restriction can be bypassed using `-f`.
-Replacement references will be used by default by all git commands
+Unless `-f` is given, the 'replace' reference must not yet exist.
+
+There is no other restriction on the replaced and replacement objects.
+Merge commits can be replaced by non-merge commits and vice versa.
+
+Replacement references will be used by default by all Git commands
except those doing reachability traversal (prune, pack transfer and
fsck).
@@ -50,18 +57,79 @@ achieve the same effect as the `--no-replace-objects` option.
OPTIONS
-------
-f::
+--force::
If an existing replace ref for the same object exists, it will
be overwritten (instead of failing).
-d::
+--delete::
Delete existing replace refs for the given objects.
+--edit <object>::
+ Edit an object's content interactively. The existing content
+ for <object> is pretty-printed into a temporary file, an
+ editor is launched on the file, and the result is parsed to
+ create a new object of the same type as <object>. A
+ replacement ref is then created to replace <object> with the
+ newly created object. See linkgit:git-var[1] for details about
+ how the editor will be chosen.
+
+--raw::
+ When editing, provide the raw object contents rather than
+ pretty-printed ones. Currently this only affects trees, which
+ will be shown in their binary form. This is harder to work with,
+ but can help when repairing a tree that is so corrupted it
+ cannot be pretty-printed. Note that you may need to configure
+ your editor to cleanly read and write binary data.
+
+--graft <commit> [<parent>...]::
+ Create a graft commit. A new commit is created with the same
+ content as <commit> except that its parents will be
+ [<parent>...] instead of <commit>'s parents. A replacement ref
+ is then created to replace <commit> with the newly created
+ commit. See contrib/convert-grafts-to-replace-refs.sh for an
+ example script based on this option that can convert grafts to
+ replace refs.
+
-l <pattern>::
+--list <pattern>::
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.
+--format=<format>::
+ When listing, use the specified <format>, which can be one of
+ 'short', 'medium' and 'long'. When omitted, the format
+ defaults to 'short'.
+
+FORMATS
+-------
+
+The following format are available:
+
+* 'short':
+ <replaced sha1>
+* 'medium':
+ <replaced sha1> -> <replacement sha1>
+* 'long':
+ <replaced sha1> (<replaced type>) -> <replacement sha1> (<replacement type>)
+
+CREATING REPLACEMENT OBJECTS
+----------------------------
+
+linkgit:git-filter-branch[1], linkgit:git-hash-object[1] and
+linkgit:git-rebase[1], among other git commands, can be used to create
+replacement objects from existing objects. The `--edit` option can
+also be used with 'git replace' to create a replacement object by
+editing an existing object.
+
+If you want to replace many blobs, trees or commits that are part of a
+string of commits, you may just want to create a replacement string of
+commits and then only replace the commit at the tip of the target
+string of commits with the commit at the tip of the replacement string
+of commits.
+
BUGS
----
Comparing blobs or trees that have been replaced with those that
@@ -70,14 +138,17 @@ go back to a replaced commit will move the branch to the replacement
commit instead of the replaced commit.
There may be other problems when using 'git rev-list' 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).
+pending objects.
SEE ALSO
--------
+linkgit:git-hash-object[1]
+linkgit:git-filter-branch[1]
+linkgit:git-rebase[1]
linkgit:git-tag[1]
linkgit:git-branch[1]
+linkgit:git-commit[1]
+linkgit:git-var[1]
linkgit:git[1]
GIT