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