1git-replace(1) 2============== 3 4NAME 5---- 6git-replace - Create, list, delete refs to replace objects 7 8SYNOPSIS 9-------- 10[verse] 11'git replace' [-f] <object> <replacement> 12'git replace' [-f] --edit <object> 13'git replace' [-f] --graft <commit> [<parent>...] 14'git replace' -d <object>... 15'git replace' [--format=<format>] [-l [<pattern>]] 16 17DESCRIPTION 18----------- 19Adds a 'replace' reference in `refs/replace/` namespace. 20 21The name of the 'replace' reference is the SHA-1 of the object that is 22replaced. The content of the 'replace' reference is the SHA-1 of the 23replacement object. 24 25The replaced object and the replacement object must be of the same type. 26This restriction can be bypassed using `-f`. 27 28Unless `-f` is given, the 'replace' reference must not yet exist. 29 30There is no other restriction on the replaced and replacement objects. 31Merge commits can be replaced by non-merge commits and vice versa. 32 33Replacement references will be used by default by all Git commands 34except those doing reachability traversal (prune, pack transfer and 35fsck). 36 37It is possible to disable use of replacement references for any 38command using the `--no-replace-objects` option just after 'git'. 39 40For example if commit 'foo' has been replaced by commit 'bar': 41 42------------------------------------------------ 43$ git --no-replace-objects cat-file commit foo 44------------------------------------------------ 45 46shows information about commit 'foo', while: 47 48------------------------------------------------ 49$ git cat-file commit foo 50------------------------------------------------ 51 52shows information about commit 'bar'. 53 54The 'GIT_NO_REPLACE_OBJECTS' environment variable can be set to 55achieve the same effect as the `--no-replace-objects` option. 56 57OPTIONS 58------- 59-f:: 60--force:: 61 If an existing replace ref for the same object exists, it will 62 be overwritten (instead of failing). 63 64-d:: 65--delete:: 66 Delete existing replace refs for the given objects. 67 68--edit <object>:: 69 Edit an object's content interactively. The existing content 70 for <object> is pretty-printed into a temporary file, an 71 editor is launched on the file, and the result is parsed to 72 create a new object of the same type as <object>. A 73 replacement ref is then created to replace <object> with the 74 newly created object. See linkgit:git-var[1] for details about 75 how the editor will be chosen. 76 77--raw:: 78 When editing, provide the raw object contents rather than 79 pretty-printed ones. Currently this only affects trees, which 80 will be shown in their binary form. This is harder to work with, 81 but can help when repairing a tree that is so corrupted it 82 cannot be pretty-printed. Note that you may need to configure 83 your editor to cleanly read and write binary data. 84 85--graft <commit> [<parent>...]:: 86 Create a graft commit. A new commit is created with the same 87 content as <commit> except that its parents will be 88 [<parent>...] instead of <commit>'s parents. A replacement ref 89 is then created to replace <commit> with the newly created 90 commit. See contrib/convert-grafts-to-replace-refs.sh for an 91 example script based on this option that can convert grafts to 92 replace refs. 93 94-l <pattern>:: 95--list <pattern>:: 96 List replace refs for objects that match the given pattern (or 97 all if no pattern is given). 98 Typing "git replace" without arguments, also lists all replace 99 refs. 100 101--format=<format>:: 102 When listing, use the specified <format>, which can be one of 103 'short', 'medium' and 'long'. When omitted, the format 104 defaults to 'short'. 105 106FORMATS 107------- 108 109The following format are available: 110 111* 'short': 112 <replaced sha1> 113* 'medium': 114 <replaced sha1> -> <replacement sha1> 115* 'long': 116 <replaced sha1> (<replaced type>) -> <replacement sha1> (<replacement type>) 117 118CREATING REPLACEMENT OBJECTS 119---------------------------- 120 121linkgit:git-filter-branch[1], linkgit:git-hash-object[1] and 122linkgit:git-rebase[1], among other git commands, can be used to create 123replacement objects from existing objects. The `--edit` option can 124also be used with 'git replace' to create a replacement object by 125editing an existing object. 126 127If you want to replace many blobs, trees or commits that are part of a 128string of commits, you may just want to create a replacement string of 129commits and then only replace the commit at the tip of the target 130string of commits with the commit at the tip of the replacement string 131of commits. 132 133BUGS 134---- 135Comparing blobs or trees that have been replaced with those that 136replace them will not work properly. And using `git reset --hard` to 137go back to a replaced commit will move the branch to the replacement 138commit instead of the replaced commit. 139 140There may be other problems when using 'git rev-list' related to 141pending objects. 142 143SEE ALSO 144-------- 145linkgit:git-hash-object[1] 146linkgit:git-filter-branch[1] 147linkgit:git-rebase[1] 148linkgit:git-tag[1] 149linkgit:git-branch[1] 150linkgit:git-commit[1] 151linkgit:git-var[1] 152linkgit:git[1] 153 154GIT 155--- 156Part of the linkgit:git[1] suite