]>
Commit | Line | Data |
---|---|---|
e75d1da3 AP |
1 | git-subtree(1) |
2 | ============== | |
3 | ||
4 | NAME | |
5 | ---- | |
7f86ff0f | 6 | git-subtree - Merge subtrees together and split repository into subtrees |
e75d1da3 AP |
7 | |
8 | ||
9 | SYNOPSIS | |
10 | -------- | |
11 | [verse] | |
1c3e0f00 AB |
12 | 'git subtree' add -P <prefix> <commit> |
13 | 'git subtree' add -P <prefix> <repository> <ref> | |
14 | 'git subtree' pull -P <prefix> <repository> <ref> | |
15 | 'git subtree' push -P <prefix> <repository> <ref> | |
9a40fcc2 AP |
16 | 'git subtree' merge -P <prefix> <commit> |
17 | 'git subtree' split -P <prefix> [OPTIONS] [<commit>] | |
7f86ff0f | 18 | |
e75d1da3 AP |
19 | |
20 | DESCRIPTION | |
21 | ----------- | |
7f86ff0f JY |
22 | Subtrees allow subprojects to be included within a subdirectory |
23 | of the main project, optionally including the subproject's | |
24 | entire history. | |
e75d1da3 | 25 | |
7f86ff0f JY |
26 | For example, you could include the source code for a library |
27 | as a subdirectory of your application. | |
28 | ||
29 | Subtrees are not to be confused with submodules, which are meant for | |
30 | the same task. Unlike submodules, subtrees do not need any special | |
5aea9fe6 | 31 | constructions (like .gitmodules files or gitlinks) be present in |
7f86ff0f JY |
32 | your repository, and do not force end-users of your |
33 | repository to do anything special or to understand how subtrees | |
34 | work. A subtree is just a subdirectory that can be | |
35 | committed to, branched, and merged along with your project in | |
36 | any way you want. | |
37 | ||
9a40fcc2 | 38 | They are also not to be confused with using the subtree merge |
7f86ff0f | 39 | strategy. The main difference is that, besides merging |
9a40fcc2 | 40 | the other project as a subdirectory, you can also extract the |
7f86ff0f JY |
41 | entire history of a subdirectory from your project and make it |
42 | into a standalone project. Unlike the subtree merge strategy | |
43 | you can alternate back and forth between these | |
44 | two operations. If the standalone library gets updated, you can | |
e75d1da3 AP |
45 | automatically merge the changes into your project; if you |
46 | update the library inside your project, you can "split" the | |
47 | changes back out again and merge them back into the library | |
48 | project. | |
49 | ||
7f86ff0f JY |
50 | For example, if a library you made for one application ends up being |
51 | useful elsewhere, you can extract its entire history and publish | |
52 | that as its own git repository, without accidentally | |
53 | intermingling the history of your application project. | |
e75d1da3 | 54 | |
7f86ff0f | 55 | [TIP] |
e75d1da3 AP |
56 | In order to keep your commit messages clean, we recommend that |
57 | people split their commits between the subtrees and the main | |
58 | project as much as possible. That is, if you make a change that | |
59 | affects both the library and the main application, commit it in | |
60 | two pieces. That way, when you split the library commits out | |
61 | later, their descriptions will still make sense. But if this | |
62 | isn't important to you, it's not *necessary*. git subtree will | |
63 | simply leave out the non-library-related parts of the commit | |
64 | when it splits it out into the subproject later. | |
65 | ||
66 | ||
67 | COMMANDS | |
68 | -------- | |
69 | add:: | |
70 | Create the <prefix> subtree by importing its contents | |
1c3e0f00 | 71 | from the given <commit> or <repository> and remote <ref>. |
c00d1d11 WW |
72 | A new commit is created automatically, joining the imported |
73 | project's history with your own. With '--squash', imports | |
74 | only a single commit from the subproject, rather than its | |
75 | entire history. | |
e75d1da3 AP |
76 | |
77 | merge:: | |
78 | Merge recent changes up to <commit> into the <prefix> | |
79 | subtree. As with normal 'git merge', this doesn't | |
80 | remove your own local changes; it just merges those | |
81 | changes into the latest <commit>. With '--squash', | |
82 | creates only one commit that contains all the changes, | |
83 | rather than merging in the entire history. | |
e0a1f093 SP |
84 | + |
85 | If you use '--squash', the merge direction doesn't always have to be | |
86 | forward; you can use this command to go back in time from v2.5 to v2.4, | |
87 | for example. If your merge introduces a conflict, you can resolve it in | |
88 | the usual ways. | |
e75d1da3 AP |
89 | |
90 | pull:: | |
91 | Exactly like 'merge', but parallels 'git pull' in that | |
1c3e0f00 | 92 | it fetches the given ref from the specified remote |
e75d1da3 | 93 | repository. |
c00d1d11 WW |
94 | |
95 | push:: | |
248a8849 | 96 | Does a 'split' (see below) using the <prefix> supplied |
c00d1d11 | 97 | and then does a 'git push' to push the result to the |
1c3e0f00 | 98 | repository and ref. This can be used to push your |
c00d1d11 | 99 | subtree to different branches of the remote repository. |
e75d1da3 AP |
100 | |
101 | split:: | |
102 | Extract a new, synthetic project history from the | |
103 | history of the <prefix> subtree. The new history | |
104 | includes only the commits (including merges) that | |
105 | affected <prefix>, and each of those commits now has the | |
106 | contents of <prefix> at the root of the project instead | |
107 | of in a subdirectory. Thus, the newly created history | |
108 | is suitable for export as a separate git repository. | |
e0a1f093 SP |
109 | + |
110 | After splitting successfully, a single commit id is printed to stdout. | |
111 | This corresponds to the HEAD of the newly created tree, which you can | |
112 | manipulate however you want. | |
113 | + | |
114 | Repeated splits of exactly the same history are guaranteed to be | |
115 | identical (i.e. to produce the same commit ids). Because of this, if | |
116 | you add new commits and then re-split, the new commits will be attached | |
117 | as commits on top of the history you generated last time, so 'git merge' | |
118 | and friends will work as expected. | |
119 | + | |
120 | Note that if you use '--squash' when you merge, you should usually not | |
121 | just '--rejoin' when you split. | |
e75d1da3 AP |
122 | |
123 | ||
124 | OPTIONS | |
125 | ------- | |
126 | -q:: | |
127 | --quiet:: | |
128 | Suppress unnecessary output messages on stderr. | |
129 | ||
130 | -d:: | |
131 | --debug:: | |
132 | Produce even more unnecessary output messages on stderr. | |
133 | ||
7f86ff0f | 134 | -P <prefix>:: |
e75d1da3 AP |
135 | --prefix=<prefix>:: |
136 | Specify the path in the repository to the subtree you | |
7f86ff0f | 137 | want to manipulate. This option is mandatory |
e75d1da3 AP |
138 | for all commands. |
139 | ||
7f86ff0f JY |
140 | -m <message>:: |
141 | --message=<message>:: | |
f99c0c99 | 142 | This option is only valid for add, merge, pull, and split --rejoin. |
7f86ff0f | 143 | Specify <message> as the commit message for the merge commit. |
e75d1da3 | 144 | |
7f86ff0f | 145 | |
ce820cbd DL |
146 | OPTIONS FOR add, merge, and pull |
147 | -------------------------------- | |
e75d1da3 | 148 | --squash:: |
6ccc71a9 | 149 | This option is only valid for add, merge, and pull |
7f86ff0f | 150 | commands. |
e0a1f093 SP |
151 | + |
152 | Instead of merging the entire history from the subtree project, produce | |
153 | only a single commit that contains all the differences you want to | |
154 | merge, and then merge that new commit into your project. | |
155 | + | |
156 | Using this option helps to reduce log clutter. People rarely want to see | |
157 | every change that happened between v1.0 and v1.1 of the library they're | |
158 | using, since none of the interim versions were ever included in their | |
159 | application. | |
160 | + | |
161 | Using '--squash' also helps avoid problems when the same subproject is | |
162 | included multiple times in the same project, or is removed and then | |
163 | re-added. In such a case, it doesn't make sense to combine the | |
164 | histories anyway, since it's unclear which part of the history belongs | |
165 | to which subtree. | |
166 | + | |
167 | Furthermore, with '--squash', you can switch back and forth between | |
168 | different versions of a subtree, rather than strictly forward. 'git | |
169 | subtree merge --squash' always adjusts the subtree to match the exactly | |
170 | specified commit, even if getting to that commit would require undoing | |
171 | some changes that were added earlier. | |
172 | + | |
173 | Whether or not you use '--squash', changes made in your local repository | |
174 | remain intact and can be later split and send upstream to the | |
175 | subproject. | |
e75d1da3 AP |
176 | |
177 | ||
178 | OPTIONS FOR split | |
179 | ----------------- | |
180 | --annotate=<annotation>:: | |
7f86ff0f | 181 | This option is only valid for the split command. |
e0a1f093 SP |
182 | + |
183 | When generating synthetic history, add <annotation> as a prefix to each | |
184 | commit message. Since we're creating new commits with the same commit | |
185 | message, but possibly different content, from the original commits, this | |
186 | can help to differentiate them and avoid confusion. | |
187 | + | |
188 | Whenever you split, you need to use the same <annotation>, or else you | |
189 | don't have a guarantee that the new re-created history will be identical | |
190 | to the old one. That will prevent merging from working correctly. git | |
191 | subtree tries to make it work anyway, particularly if you use --rejoin, | |
192 | but it may not always be effective. | |
e75d1da3 AP |
193 | |
194 | -b <branch>:: | |
195 | --branch=<branch>:: | |
7f86ff0f | 196 | This option is only valid for the split command. |
e0a1f093 SP |
197 | + |
198 | After generating the synthetic history, create a new branch called | |
199 | <branch> that contains the new history. This is suitable for immediate | |
200 | pushing upstream. <branch> must not already exist. | |
e75d1da3 AP |
201 | |
202 | --ignore-joins:: | |
7f86ff0f | 203 | This option is only valid for the split command. |
e0a1f093 SP |
204 | + |
205 | If you use '--rejoin', git subtree attempts to optimize its history | |
206 | reconstruction to generate only the new commits since the last | |
207 | '--rejoin'. '--ignore-join' disables this behaviour, forcing it to | |
208 | regenerate the entire history. In a large project, this can take a long | |
209 | time. | |
e75d1da3 AP |
210 | |
211 | --onto=<onto>:: | |
7f86ff0f | 212 | This option is only valid for the split command. |
e0a1f093 SP |
213 | + |
214 | If your subtree was originally imported using something other than git | |
215 | subtree, its history may not match what git subtree is expecting. In | |
216 | that case, you can specify the commit id <onto> that corresponds to the | |
217 | first revision of the subproject's history that was imported into your | |
218 | project, and git subtree will attempt to build its history from there. | |
219 | + | |
220 | If you used 'git subtree add', you should never need this option. | |
e75d1da3 AP |
221 | |
222 | --rejoin:: | |
7f86ff0f | 223 | This option is only valid for the split command. |
e0a1f093 SP |
224 | + |
225 | After splitting, merge the newly created synthetic history back into | |
226 | your main project. That way, future splits can search only the part of | |
227 | history that has been added since the most recent --rejoin. | |
228 | + | |
229 | If your split commits end up merged into the upstream subproject, and | |
230 | then you want to get the latest upstream version, this will allow git's | |
231 | merge algorithm to more intelligently avoid conflicts (since it knows | |
232 | these synthetic commits are already part of the upstream repository). | |
233 | + | |
234 | Unfortunately, using this option results in 'git log' showing an extra | |
235 | copy of every new commit that was created (the original, and the | |
236 | synthetic one). | |
237 | + | |
238 | If you do all your merges with '--squash', don't use '--rejoin' when you | |
239 | split, because you don't want the subproject's history to be part of | |
240 | your project anyway. | |
e75d1da3 AP |
241 | |
242 | ||
7f86ff0f JY |
243 | EXAMPLE 1. Add command |
244 | ---------------------- | |
c6ca48d4 DS |
245 | Let's assume that you have a local repository that you would like |
246 | to add an external vendor library to. In this case we will add the | |
247 | git-subtree repository as a subdirectory of your already existing | |
242b20dc | 248 | git-extensions repository in ~/git-extensions/: |
c6ca48d4 | 249 | |
242b20dc BL |
250 | $ git subtree add --prefix=git-subtree --squash \ |
251 | git://github.com/apenwarr/git-subtree.git master | |
c6ca48d4 DS |
252 | |
253 | 'master' needs to be a valid remote ref and can be a different branch | |
254 | name | |
255 | ||
c6ca48d4 | 256 | You can omit the --squash flag, but doing so will increase the number |
98e023de | 257 | of commits that are included in your local repository. |
c6ca48d4 | 258 | |
ae330187 DS |
259 | We now have a ~/git-extensions/git-subtree directory containing code |
260 | from the master branch of git://github.com/apenwarr/git-subtree.git | |
261 | in our git-extensions repository. | |
c6ca48d4 | 262 | |
7f86ff0f JY |
263 | EXAMPLE 2. Extract a subtree using commit, merge and pull |
264 | --------------------------------------------------------- | |
c6ca48d4 | 265 | Let's use the repository for the git source code as an example. |
dd079062 AP |
266 | First, get your own copy of the git.git repository: |
267 | ||
268 | $ git clone git://git.kernel.org/pub/scm/git/git.git test-git | |
269 | $ cd test-git | |
270 | ||
271 | gitweb (commit 1130ef3) was merged into git as of commit | |
272 | 0a8f4f0, after which it was no longer maintained separately. | |
273 | But imagine it had been maintained separately, and we wanted to | |
274 | extract git's changes to gitweb since that time, to share with | |
275 | the upstream. You could do this: | |
276 | ||
277 | $ git subtree split --prefix=gitweb --annotate='(split) ' \ | |
278 | 0a8f4f0^.. --onto=1130ef3 --rejoin \ | |
279 | --branch gitweb-latest | |
280 | $ gitk gitweb-latest | |
b64a7aa2 | 281 | $ git push git@github.com:whatever/gitweb.git gitweb-latest:master |
dd079062 AP |
282 | |
283 | (We use '0a8f4f0^..' because that means "all the changes from | |
284 | 0a8f4f0 to the current version, including 0a8f4f0 itself.") | |
285 | ||
286 | If gitweb had originally been merged using 'git subtree add' (or | |
287 | a previous split had already been done with --rejoin specified) | |
288 | then you can do all your splits without having to remember any | |
289 | weird commit ids: | |
290 | ||
291 | $ git subtree split --prefix=gitweb --annotate='(split) ' --rejoin \ | |
292 | --branch gitweb-latest2 | |
293 | ||
294 | And you can merge changes back in from the upstream project just | |
295 | as easily: | |
296 | ||
297 | $ git subtree pull --prefix=gitweb \ | |
e1ce417d | 298 | git@github.com:whatever/gitweb.git master |
dd079062 AP |
299 | |
300 | Or, using '--squash', you can actually rewind to an earlier | |
301 | version of gitweb: | |
302 | ||
303 | $ git subtree merge --prefix=gitweb --squash gitweb-latest~10 | |
304 | ||
305 | Then make some changes: | |
306 | ||
307 | $ date >gitweb/myfile | |
308 | $ git add gitweb/myfile | |
309 | $ git commit -m 'created myfile' | |
310 | ||
311 | And fast forward again: | |
312 | ||
313 | $ git subtree merge --prefix=gitweb --squash gitweb-latest | |
314 | ||
315 | And notice that your change is still intact: | |
316 | ||
317 | $ ls -l gitweb/myfile | |
318 | ||
319 | And you can split it out and look at your changes versus | |
320 | the standard gitweb: | |
321 | ||
322 | git log gitweb-latest..$(git subtree split --prefix=gitweb) | |
323 | ||
7f86ff0f JY |
324 | EXAMPLE 3. Extract a subtree using branch |
325 | ----------------------------------------- | |
37668a13 WT |
326 | Suppose you have a source directory with many files and |
327 | subdirectories, and you want to extract the lib directory to its own | |
328 | git project. Here's a short way to do it: | |
329 | ||
330 | First, make the new repository wherever you want: | |
7f86ff0f JY |
331 | |
332 | $ <go to the new location> | |
333 | $ git init --bare | |
37668a13 WT |
334 | |
335 | Back in your original directory: | |
7f86ff0f JY |
336 | |
337 | $ git subtree split --prefix=lib --annotate="(split)" -b split | |
37668a13 WT |
338 | |
339 | Then push the new branch onto the new empty repository: | |
37668a13 | 340 | |
7f86ff0f | 341 | $ git push <new-repo> split:master |
37668a13 | 342 | |
dd079062 | 343 | |
e75d1da3 AP |
344 | AUTHOR |
345 | ------ | |
346 | Written by Avery Pennarun <apenwarr@gmail.com> | |
347 | ||
348 | ||
349 | GIT | |
350 | --- | |
351 | Part of the linkgit:git[1] suite |