Commit | Line | Data |
---|---|---|
0f3a5bfd CC |
1 | git-replace(1) |
2 | ============== | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | git-replace - Create, list, delete refs to replace objects | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
10 | [verse] | |
11 | 'git replace' [-f] <object> <replacement> | |
4e4b125c | 12 | 'git replace' [-f] --edit <object> |
78024c4e | 13 | 'git replace' [-f] --graft <commit> [<parent>...] |
fb404291 | 14 | 'git replace' [-f] --convert-graft-file |
0f3a5bfd | 15 | 'git replace' -d <object>... |
34a33222 | 16 | 'git replace' [--format=<format>] [-l [<pattern>]] |
0f3a5bfd CC |
17 | |
18 | DESCRIPTION | |
19 | ----------- | |
831e61f8 | 20 | Adds a 'replace' reference in `refs/replace/` namespace. |
0f3a5bfd | 21 | |
d5fa1f1a TA |
22 | The name of the 'replace' reference is the SHA-1 of the object that is |
23 | replaced. The content of the 'replace' reference is the SHA-1 of the | |
0f3a5bfd CC |
24 | replacement object. |
25 | ||
160df71e CC |
26 | The replaced object and the replacement object must be of the same type. |
27 | This restriction can be bypassed using `-f`. | |
28 | ||
831e61f8 | 29 | Unless `-f` is given, the 'replace' reference must not yet exist. |
0f3a5bfd | 30 | |
160df71e | 31 | There is no other restriction on the replaced and replacement objects. |
90749253 | 32 | Merge commits can be replaced by non-merge commits and vice versa. |
160df71e | 33 | |
2de9b711 | 34 | Replacement references will be used by default by all Git commands |
ddae8ae8 CC |
35 | except those doing reachability traversal (prune, pack transfer and |
36 | fsck). | |
b0fa7ab5 | 37 | |
ddae8ae8 CC |
38 | It is possible to disable use of replacement references for any |
39 | command using the `--no-replace-objects` option just after 'git'. | |
b0fa7ab5 | 40 | |
ddae8ae8 | 41 | For example if commit 'foo' has been replaced by commit 'bar': |
b0fa7ab5 CC |
42 | |
43 | ------------------------------------------------ | |
ddae8ae8 | 44 | $ git --no-replace-objects cat-file commit foo |
b0fa7ab5 CC |
45 | ------------------------------------------------ |
46 | ||
ddae8ae8 | 47 | shows information about commit 'foo', while: |
b0fa7ab5 CC |
48 | |
49 | ------------------------------------------------ | |
50 | $ git cat-file commit foo | |
51 | ------------------------------------------------ | |
52 | ||
ddae8ae8 | 53 | shows information about commit 'bar'. |
b0fa7ab5 | 54 | |
eee7f4a2 | 55 | The `GIT_NO_REPLACE_OBJECTS` environment variable can be set to |
0de8b947 CC |
56 | achieve the same effect as the `--no-replace-objects` option. |
57 | ||
0f3a5bfd CC |
58 | OPTIONS |
59 | ------- | |
60 | -f:: | |
ed0ff809 | 61 | --force:: |
0f3a5bfd CC |
62 | If an existing replace ref for the same object exists, it will |
63 | be overwritten (instead of failing). | |
64 | ||
65 | -d:: | |
ed0ff809 | 66 | --delete:: |
0f3a5bfd CC |
67 | Delete existing replace refs for the given objects. |
68 | ||
4e4b125c CC |
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 | ||
2deda629 JK |
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 | ||
78024c4e CC |
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 | |
fb404291 JS |
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. | |
78024c4e | 98 | |
0f3a5bfd | 99 | -l <pattern>:: |
ed0ff809 | 100 | --list <pattern>:: |
0f3a5bfd CC |
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 | ||
34a33222 CC |
106 | --format=<format>:: |
107 | When listing, use the specified <format>, which can be one of | |
663a8566 | 108 | 'short', 'medium' and 'long'. When omitted, the format |
34a33222 CC |
109 | defaults to 'short'. |
110 | ||
111 | FORMATS | |
112 | ------- | |
113 | ||
114 | The following format are available: | |
115 | ||
116 | * 'short': | |
117 | <replaced sha1> | |
118 | * 'medium': | |
119 | <replaced sha1> -> <replacement sha1> | |
663a8566 | 120 | * 'long': |
34a33222 CC |
121 | <replaced sha1> (<replaced type>) -> <replacement sha1> (<replacement type>) |
122 | ||
b8fcce1e CC |
123 | CREATING REPLACEMENT OBJECTS |
124 | ---------------------------- | |
125 | ||
126 | linkgit:git-filter-branch[1], linkgit:git-hash-object[1] and | |
127 | linkgit:git-rebase[1], among other git commands, can be used to create | |
4e4b125c CC |
128 | replacement objects from existing objects. The `--edit` option can |
129 | also be used with 'git replace' to create a replacement object by | |
130 | editing an existing object. | |
b8fcce1e CC |
131 | |
132 | If you want to replace many blobs, trees or commits that are part of a | |
133 | string of commits, you may just want to create a replacement string of | |
134 | commits and then only replace the commit at the tip of the target | |
135 | string of commits with the commit at the tip of the replacement string | |
136 | of commits. | |
137 | ||
0f3a5bfd CC |
138 | BUGS |
139 | ---- | |
140 | Comparing blobs or trees that have been replaced with those that | |
ca768288 | 141 | replace them will not work properly. And using `git reset --hard` to |
0f3a5bfd CC |
142 | go back to a replaced commit will move the branch to the replacement |
143 | commit instead of the replaced commit. | |
144 | ||
145 | There may be other problems when using 'git rev-list' related to | |
160df71e | 146 | pending objects. |
0f3a5bfd CC |
147 | |
148 | SEE ALSO | |
149 | -------- | |
b8fcce1e CC |
150 | linkgit:git-hash-object[1] |
151 | linkgit:git-filter-branch[1] | |
152 | linkgit:git-rebase[1] | |
0f3a5bfd CC |
153 | linkgit:git-tag[1] |
154 | linkgit:git-branch[1] | |
4e4b125c CC |
155 | linkgit:git-commit[1] |
156 | linkgit:git-var[1] | |
b0fa7ab5 | 157 | linkgit:git[1] |
0f3a5bfd | 158 | |
0f3a5bfd CC |
159 | GIT |
160 | --- | |
161 | Part of the linkgit:git[1] suite |