diff options
Diffstat (limited to 'Documentation/git-replace.txt')
| -rw-r--r-- | Documentation/git-replace.txt | 93 |
1 files changed, 82 insertions, 11 deletions
diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt index 17df525275..e5c57ae6ef 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). @@ -44,24 +51,85 @@ $ git cat-file commit foo shows information about commit 'bar'. -The 'GIT_NO_REPLACE_OBJECTS' environment variable can be set to +The `GIT_NO_REPLACE_OBJECTS` environment variable can be set to 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 |