| 1 | git-subtree(1) |
| 2 | ============== |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | git-subtree - Merge subtrees together and split repository into subtrees |
| 7 | |
| 8 | |
| 9 | SYNOPSIS |
| 10 | -------- |
| 11 | [verse] |
| 12 | 'git subtree' [<options>] -P <prefix> [-S[<keyid>]] add <local-commit> |
| 13 | 'git subtree' [<options>] -P <prefix> [-S[<keyid>]] add <repository> <remote-ref> |
| 14 | 'git subtree' [<options>] -P <prefix> [-S[<keyid>]] merge <local-commit> [<repository>] |
| 15 | 'git subtree' [<options>] -P <prefix> [-S[<keyid>]] split [<local-commit>] |
| 16 | |
| 17 | [verse] |
| 18 | 'git subtree' [<options>] -P <prefix> [-S[<keyid>]] pull <repository> <remote-ref> |
| 19 | 'git subtree' [<options>] -P <prefix> [-S[<keyid>]] push <repository> <refspec> |
| 20 | |
| 21 | DESCRIPTION |
| 22 | ----------- |
| 23 | Subtrees allow subprojects to be included within a subdirectory |
| 24 | of the main project, optionally including the subproject's |
| 25 | entire history. |
| 26 | |
| 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 |
| 32 | constructions (like '.gitmodules' files or gitlinks) be present in |
| 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 | |
| 39 | They are also not to be confused with using the subtree merge |
| 40 | strategy. The main difference is that, besides merging |
| 41 | the other project as a subdirectory, you can also extract the |
| 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 |
| 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 | |
| 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. |
| 55 | |
| 56 | [TIP] |
| 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 |
| 63 | isn't important to you, it's not *necessary*. 'git subtree' will |
| 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 | -------- |
| 70 | add <local-commit>:: |
| 71 | add <repository> <remote-ref>:: |
| 72 | Create the <prefix> subtree by importing its contents |
| 73 | from the given <local-commit> or <repository> and <remote-ref>. |
| 74 | A new commit is created automatically, joining the imported |
| 75 | project's history with your own. With '--squash', import |
| 76 | only a single commit from the subproject, rather than its |
| 77 | entire history. |
| 78 | |
| 79 | merge <local-commit> [<repository>]:: |
| 80 | Merge recent changes up to <local-commit> into the <prefix> |
| 81 | subtree. As with normal 'git merge', this doesn't |
| 82 | remove your own local changes; it just merges those |
| 83 | changes into the latest <local-commit>. With '--squash', |
| 84 | create only one commit that contains all the changes, |
| 85 | rather than merging in the entire history. |
| 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. |
| 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. |
| 96 | |
| 97 | split [<local-commit>] [<repository>]:: |
| 98 | Extract a new, synthetic project history from the |
| 99 | history of the <prefix> subtree of <local-commit>, or of |
| 100 | HEAD if no <local-commit> is given. The new history |
| 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. |
| 106 | + |
| 107 | After splitting successfully, a single commit ID is printed to stdout. |
| 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 |
| 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. |
| 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. |
| 122 | |
| 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 | |
| 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. |
| 135 | |
| 136 | OPTIONS FOR ALL COMMANDS |
| 137 | ------------------------ |
| 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 | |
| 146 | -P <prefix>:: |
| 147 | --prefix=<prefix>:: |
| 148 | Specify the path in the repository to the subtree you |
| 149 | want to manipulate. This option is mandatory |
| 150 | for all commands. |
| 151 | |
| 152 | -S[<keyid>]:: |
| 153 | --gpg-sign[=<keyid>]:: |
| 154 | --no-gpg-sign:: |
| 155 | GPG-sign commits. The `keyid` argument is optional and |
| 156 | defaults to the committer identity; `--no-gpg-sign` is useful to |
| 157 | countermand a `--gpg-sign` option given earlier on the command line. |
| 158 | |
| 159 | OPTIONS FOR 'add' AND 'merge' (ALSO: 'pull', 'split --rejoin', AND 'push --rejoin') |
| 160 | ----------------------------------------------------------------------------------- |
| 161 | These options for 'add' and 'merge' may also be given to 'pull' (which |
| 162 | wraps 'merge'), 'split --rejoin' (which wraps either 'add' or 'merge' |
| 163 | as appropriate), and 'push --rejoin' (which wraps 'split --rejoin'). |
| 164 | |
| 165 | --squash:: |
| 166 | Instead of merging the entire history from the subtree project, produce |
| 167 | only a single commit that contains all the differences you want to |
| 168 | merge, and then merge that new commit into your project. |
| 169 | + |
| 170 | Using this option helps to reduce log clutter. People rarely want to see |
| 171 | every change that happened between v1.0 and v1.1 of the library they're |
| 172 | using, since none of the interim versions were ever included in their |
| 173 | application. |
| 174 | + |
| 175 | Using '--squash' also helps avoid problems when the same subproject is |
| 176 | included multiple times in the same project, or is removed and then |
| 177 | re-added. In such a case, it doesn't make sense to combine the |
| 178 | histories anyway, since it's unclear which part of the history belongs |
| 179 | to which subtree. |
| 180 | + |
| 181 | Furthermore, with '--squash', you can switch back and forth between |
| 182 | different versions of a subtree, rather than strictly forward. 'git |
| 183 | subtree merge --squash' always adjusts the subtree to match the exactly |
| 184 | specified commit, even if getting to that commit would require undoing |
| 185 | some changes that were added earlier. |
| 186 | + |
| 187 | Whether or not you use '--squash', changes made in your local repository |
| 188 | remain intact and can be later split and send upstream to the |
| 189 | subproject. |
| 190 | |
| 191 | -m <message>:: |
| 192 | --message=<message>:: |
| 193 | Specify <message> as the commit message for the merge commit. |
| 194 | |
| 195 | OPTIONS FOR 'split' (ALSO: 'push') |
| 196 | ---------------------------------- |
| 197 | These options for 'split' may also be given to 'push' (which wraps |
| 198 | 'split'). |
| 199 | |
| 200 | --annotate=<annotation>:: |
| 201 | When generating synthetic history, add <annotation> as a prefix to each |
| 202 | commit message. Since we're creating new commits with the same commit |
| 203 | message, but possibly different content, from the original commits, this |
| 204 | can help to differentiate them and avoid confusion. |
| 205 | + |
| 206 | Whenever you split, you need to use the same <annotation>, or else you |
| 207 | don't have a guarantee that the new re-created history will be identical |
| 208 | to the old one. That will prevent merging from working correctly. git |
| 209 | subtree tries to make it work anyway, particularly if you use '--rejoin', |
| 210 | but it may not always be effective. |
| 211 | |
| 212 | -b <branch>:: |
| 213 | --branch=<branch>:: |
| 214 | After generating the synthetic history, create a new branch called |
| 215 | <branch> that contains the new history. This is suitable for immediate |
| 216 | pushing upstream. <branch> must not already exist. |
| 217 | |
| 218 | --ignore-joins:: |
| 219 | If you use '--rejoin', git subtree attempts to optimize its history |
| 220 | reconstruction to generate only the new commits since the last |
| 221 | '--rejoin'. '--ignore-joins' disables this behavior, forcing it to |
| 222 | regenerate the entire history. In a large project, this can take a long |
| 223 | time. |
| 224 | |
| 225 | --onto=<onto>:: |
| 226 | If your subtree was originally imported using something other than git |
| 227 | subtree, its history may not match what git subtree is expecting. In |
| 228 | that case, you can specify the commit ID <onto> that corresponds to the |
| 229 | first revision of the subproject's history that was imported into your |
| 230 | project, and git subtree will attempt to build its history from there. |
| 231 | + |
| 232 | If you used 'git subtree add', you should never need this option. |
| 233 | |
| 234 | --rejoin:: |
| 235 | After splitting, merge the newly created synthetic history back into |
| 236 | your main project. That way, future splits can search only the part of |
| 237 | history that has been added since the most recent '--rejoin'. |
| 238 | + |
| 239 | If your split commits end up merged into the upstream subproject, and |
| 240 | then you want to get the latest upstream version, this will allow git's |
| 241 | merge algorithm to more intelligently avoid conflicts (since it knows |
| 242 | these synthetic commits are already part of the upstream repository). |
| 243 | + |
| 244 | Unfortunately, using this option results in 'git log' showing an extra |
| 245 | copy of every new commit that was created (the original, and the |
| 246 | synthetic one). |
| 247 | + |
| 248 | If you do all your merges with '--squash', make sure you also use |
| 249 | '--squash' when you 'split --rejoin'. |
| 250 | |
| 251 | |
| 252 | EXAMPLE 1. 'add' command |
| 253 | ------------------------ |
| 254 | Let's assume that you have a local repository that you would like |
| 255 | to add an external vendor library to. In this case we will add the |
| 256 | git-subtree repository as a subdirectory of your already existing |
| 257 | git-extensions repository in ~/git-extensions/: |
| 258 | |
| 259 | $ git subtree add --prefix=git-subtree --squash \ |
| 260 | git://github.com/apenwarr/git-subtree.git master |
| 261 | |
| 262 | 'master' needs to be a valid remote ref and can be a different branch |
| 263 | name |
| 264 | |
| 265 | You can omit the '--squash' flag, but doing so will increase the number |
| 266 | of commits that are included in your local repository. |
| 267 | |
| 268 | We now have a ~/git-extensions/git-subtree directory containing code |
| 269 | from the master branch of git://github.com/apenwarr/git-subtree.git |
| 270 | in our git-extensions repository. |
| 271 | |
| 272 | EXAMPLE 2. Extract a subtree using 'commit', 'merge' and 'pull' |
| 273 | --------------------------------------------------------------- |
| 274 | Let's use the repository for the git source code as an example. |
| 275 | First, get your own copy of the git.git repository: |
| 276 | |
| 277 | $ git clone git://git.kernel.org/pub/scm/git/git.git test-git |
| 278 | $ cd test-git |
| 279 | |
| 280 | gitweb (commit 1130ef3) was merged into git as of commit |
| 281 | 0a8f4f0, after which it was no longer maintained separately. |
| 282 | But imagine it had been maintained separately, and we wanted to |
| 283 | extract git's changes to gitweb since that time, to share with |
| 284 | the upstream. You could do this: |
| 285 | |
| 286 | $ git subtree split --prefix=gitweb --annotate='(split) ' \ |
| 287 | 0a8f4f0^.. --onto=1130ef3 --rejoin \ |
| 288 | --branch gitweb-latest |
| 289 | $ gitk gitweb-latest |
| 290 | $ git push git@github.com:whatever/gitweb.git gitweb-latest:master |
| 291 | |
| 292 | (We use '0a8f4f0^..' because that means "all the changes from |
| 293 | 0a8f4f0 to the current version, including 0a8f4f0 itself.") |
| 294 | |
| 295 | If gitweb had originally been merged using 'git subtree add' (or |
| 296 | a previous split had already been done with '--rejoin' specified) |
| 297 | then you can do all your splits without having to remember any |
| 298 | weird commit IDs: |
| 299 | |
| 300 | $ git subtree split --prefix=gitweb --annotate='(split) ' --rejoin \ |
| 301 | --branch gitweb-latest2 |
| 302 | |
| 303 | And you can merge changes back in from the upstream project just |
| 304 | as easily: |
| 305 | |
| 306 | $ git subtree pull --prefix=gitweb \ |
| 307 | git@github.com:whatever/gitweb.git master |
| 308 | |
| 309 | Or, using '--squash', you can actually rewind to an earlier |
| 310 | version of gitweb: |
| 311 | |
| 312 | $ git subtree merge --prefix=gitweb --squash gitweb-latest~10 |
| 313 | |
| 314 | Then make some changes: |
| 315 | |
| 316 | $ date >gitweb/myfile |
| 317 | $ git add gitweb/myfile |
| 318 | $ git commit -m 'created myfile' |
| 319 | |
| 320 | And fast forward again: |
| 321 | |
| 322 | $ git subtree merge --prefix=gitweb --squash gitweb-latest |
| 323 | |
| 324 | And notice that your change is still intact: |
| 325 | |
| 326 | $ ls -l gitweb/myfile |
| 327 | |
| 328 | And you can split it out and look at your changes versus |
| 329 | the standard gitweb: |
| 330 | |
| 331 | git log gitweb-latest..$(git subtree split --prefix=gitweb) |
| 332 | |
| 333 | EXAMPLE 3. Extract a subtree using a branch |
| 334 | ------------------------------------------- |
| 335 | Suppose you have a source directory with many files and |
| 336 | subdirectories, and you want to extract the lib directory to its own |
| 337 | git project. Here's a short way to do it: |
| 338 | |
| 339 | First, make the new repository wherever you want: |
| 340 | |
| 341 | $ <go to the new location> |
| 342 | $ git init --bare |
| 343 | |
| 344 | Back in your original directory: |
| 345 | |
| 346 | $ git subtree split --prefix=lib --annotate="(split)" -b split |
| 347 | |
| 348 | Then push the new branch onto the new empty repository: |
| 349 | |
| 350 | $ git push <new-repo> split:master |
| 351 | |
| 352 | |
| 353 | AUTHOR |
| 354 | ------ |
| 355 | Written by Avery Pennarun <apenwarr@gmail.com> |
| 356 | |
| 357 | |
| 358 | GIT |
| 359 | --- |
| 360 | Part of the linkgit:git[1] suite |