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