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