| Junio C Hamano | 7d06a8a | 2008-10-20 05:42:33 | [diff] [blame] | 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" |
| 2 | "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> |
| 3 | <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> |
| 4 | <head> |
| 5 | <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> |
| 6 | <meta name="generator" content="AsciiDoc 8.2.5" /> |
| 7 | <style type="text/css"> |
| 8 | /* Debug borders */ |
| 9 | p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 { |
| 10 | /* |
| 11 | border: 1px solid red; |
| 12 | */ |
| 13 | } |
| 14 | |
| 15 | body { |
| 16 | margin: 1em 5% 1em 5%; |
| 17 | } |
| 18 | |
| 19 | a { |
| 20 | color: blue; |
| 21 | text-decoration: underline; |
| 22 | } |
| 23 | a:visited { |
| 24 | color: fuchsia; |
| 25 | } |
| 26 | |
| 27 | em { |
| 28 | font-style: italic; |
| 29 | } |
| 30 | |
| 31 | strong { |
| 32 | font-weight: bold; |
| 33 | } |
| 34 | |
| 35 | tt { |
| 36 | color: navy; |
| 37 | } |
| 38 | |
| 39 | h1, h2, h3, h4, h5, h6 { |
| 40 | color: #527bbd; |
| 41 | font-family: sans-serif; |
| 42 | margin-top: 1.2em; |
| 43 | margin-bottom: 0.5em; |
| 44 | line-height: 1.3; |
| 45 | } |
| 46 | |
| 47 | h1, h2, h3 { |
| 48 | border-bottom: 2px solid silver; |
| 49 | } |
| 50 | h2 { |
| 51 | padding-top: 0.5em; |
| 52 | } |
| 53 | h3 { |
| 54 | float: left; |
| 55 | } |
| 56 | h3 + * { |
| 57 | clear: left; |
| 58 | } |
| 59 | |
| 60 | div.sectionbody { |
| 61 | font-family: serif; |
| 62 | margin-left: 0; |
| 63 | } |
| 64 | |
| 65 | hr { |
| 66 | border: 1px solid silver; |
| 67 | } |
| 68 | |
| 69 | p { |
| 70 | margin-top: 0.5em; |
| 71 | margin-bottom: 0.5em; |
| 72 | } |
| 73 | |
| 74 | pre { |
| 75 | padding: 0; |
| 76 | margin: 0; |
| 77 | } |
| 78 | |
| 79 | span#author { |
| 80 | color: #527bbd; |
| 81 | font-family: sans-serif; |
| 82 | font-weight: bold; |
| 83 | font-size: 1.1em; |
| 84 | } |
| 85 | span#email { |
| 86 | } |
| 87 | span#revision { |
| 88 | font-family: sans-serif; |
| 89 | } |
| 90 | |
| 91 | div#footer { |
| 92 | font-family: sans-serif; |
| 93 | font-size: small; |
| 94 | border-top: 2px solid silver; |
| 95 | padding-top: 0.5em; |
| 96 | margin-top: 4.0em; |
| 97 | } |
| 98 | div#footer-text { |
| 99 | float: left; |
| 100 | padding-bottom: 0.5em; |
| 101 | } |
| 102 | div#footer-badges { |
| 103 | float: right; |
| 104 | padding-bottom: 0.5em; |
| 105 | } |
| 106 | |
| 107 | div#preamble, |
| 108 | div.tableblock, div.imageblock, div.exampleblock, div.verseblock, |
| 109 | div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock, |
| 110 | div.admonitionblock { |
| 111 | margin-right: 10%; |
| 112 | margin-top: 1.5em; |
| 113 | margin-bottom: 1.5em; |
| 114 | } |
| 115 | div.admonitionblock { |
| 116 | margin-top: 2.5em; |
| 117 | margin-bottom: 2.5em; |
| 118 | } |
| 119 | |
| 120 | div.content { /* Block element content. */ |
| 121 | padding: 0; |
| 122 | } |
| 123 | |
| 124 | /* Block element titles. */ |
| 125 | div.title, caption.title { |
| 126 | font-family: sans-serif; |
| 127 | font-weight: bold; |
| 128 | text-align: left; |
| 129 | margin-top: 1.0em; |
| 130 | margin-bottom: 0.5em; |
| 131 | } |
| 132 | div.title + * { |
| 133 | margin-top: 0; |
| 134 | } |
| 135 | |
| 136 | td div.title:first-child { |
| 137 | margin-top: 0.0em; |
| 138 | } |
| 139 | div.content div.title:first-child { |
| 140 | margin-top: 0.0em; |
| 141 | } |
| 142 | div.content + div.title { |
| 143 | margin-top: 0.0em; |
| 144 | } |
| 145 | |
| 146 | div.sidebarblock > div.content { |
| 147 | background: #ffffee; |
| 148 | border: 1px solid silver; |
| 149 | padding: 0.5em; |
| 150 | } |
| 151 | |
| 152 | div.listingblock { |
| 153 | margin-right: 0%; |
| 154 | } |
| 155 | div.listingblock > div.content { |
| 156 | border: 1px solid silver; |
| 157 | background: #f4f4f4; |
| 158 | padding: 0.5em; |
| 159 | } |
| 160 | |
| 161 | div.quoteblock > div.content { |
| 162 | padding-left: 2.0em; |
| 163 | } |
| 164 | |
| 165 | div.attribution { |
| 166 | text-align: right; |
| 167 | } |
| 168 | div.verseblock + div.attribution { |
| 169 | text-align: left; |
| 170 | } |
| 171 | |
| 172 | div.admonitionblock .icon { |
| 173 | vertical-align: top; |
| 174 | font-size: 1.1em; |
| 175 | font-weight: bold; |
| 176 | text-decoration: underline; |
| 177 | color: #527bbd; |
| 178 | padding-right: 0.5em; |
| 179 | } |
| 180 | div.admonitionblock td.content { |
| 181 | padding-left: 0.5em; |
| 182 | border-left: 2px solid silver; |
| 183 | } |
| 184 | |
| 185 | div.exampleblock > div.content { |
| 186 | border-left: 2px solid silver; |
| 187 | padding: 0.5em; |
| 188 | } |
| 189 | |
| 190 | div.verseblock div.content { |
| 191 | white-space: pre; |
| 192 | } |
| 193 | |
| 194 | div.imageblock div.content { padding-left: 0; } |
| 195 | div.imageblock img { border: 1px solid silver; } |
| 196 | span.image img { border-style: none; } |
| 197 | |
| 198 | dl { |
| 199 | margin-top: 0.8em; |
| 200 | margin-bottom: 0.8em; |
| 201 | } |
| 202 | dt { |
| 203 | margin-top: 0.5em; |
| 204 | margin-bottom: 0; |
| 205 | font-style: italic; |
| 206 | } |
| 207 | dd > *:first-child { |
| 208 | margin-top: 0; |
| 209 | } |
| 210 | |
| 211 | ul, ol { |
| 212 | list-style-position: outside; |
| 213 | } |
| 214 | div.olist2 ol { |
| 215 | list-style-type: lower-alpha; |
| 216 | } |
| 217 | |
| 218 | div.tableblock > table { |
| 219 | border: 3px solid #527bbd; |
| 220 | } |
| 221 | thead { |
| 222 | font-family: sans-serif; |
| 223 | font-weight: bold; |
| 224 | } |
| 225 | tfoot { |
| 226 | font-weight: bold; |
| 227 | } |
| 228 | |
| 229 | div.hlist { |
| 230 | margin-top: 0.8em; |
| 231 | margin-bottom: 0.8em; |
| 232 | } |
| 233 | div.hlist td { |
| 234 | padding-bottom: 5px; |
| 235 | } |
| 236 | td.hlist1 { |
| 237 | vertical-align: top; |
| 238 | font-style: italic; |
| 239 | padding-right: 0.8em; |
| 240 | } |
| 241 | td.hlist2 { |
| 242 | vertical-align: top; |
| 243 | } |
| 244 | |
| 245 | @media print { |
| 246 | div#footer-badges { display: none; } |
| 247 | } |
| 248 | |
| 249 | div#toctitle { |
| 250 | color: #527bbd; |
| 251 | font-family: sans-serif; |
| 252 | font-size: 1.1em; |
| 253 | font-weight: bold; |
| 254 | margin-top: 1.0em; |
| 255 | margin-bottom: 0.1em; |
| 256 | } |
| 257 | |
| 258 | div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 { |
| 259 | margin-top: 0; |
| 260 | margin-bottom: 0; |
| 261 | } |
| 262 | div.toclevel2 { |
| 263 | margin-left: 2em; |
| 264 | font-size: 0.9em; |
| 265 | } |
| 266 | div.toclevel3 { |
| 267 | margin-left: 4em; |
| 268 | font-size: 0.9em; |
| 269 | } |
| 270 | div.toclevel4 { |
| 271 | margin-left: 6em; |
| 272 | font-size: 0.9em; |
| 273 | } |
| 274 | include1::./stylesheets/xhtml11-manpage.css[] |
| 275 | /* Workarounds for IE6's broken and incomplete CSS2. */ |
| 276 | |
| 277 | div.sidebar-content { |
| 278 | background: #ffffee; |
| 279 | border: 1px solid silver; |
| 280 | padding: 0.5em; |
| 281 | } |
| 282 | div.sidebar-title, div.image-title { |
| 283 | font-family: sans-serif; |
| 284 | font-weight: bold; |
| 285 | margin-top: 0.0em; |
| 286 | margin-bottom: 0.5em; |
| 287 | } |
| 288 | |
| 289 | div.listingblock div.content { |
| 290 | border: 1px solid silver; |
| 291 | background: #f4f4f4; |
| 292 | padding: 0.5em; |
| 293 | } |
| 294 | |
| 295 | div.quoteblock-content { |
| 296 | padding-left: 2.0em; |
| 297 | } |
| 298 | |
| 299 | div.exampleblock-content { |
| 300 | border-left: 2px solid silver; |
| 301 | padding-left: 0.5em; |
| 302 | } |
| 303 | |
| 304 | /* IE6 sets dynamically generated links as visited. */ |
| 305 | div#toc a:visited { color: blue; } |
| 306 | </style> |
| 307 | <title>gitworkflows(7)</title> |
| 308 | </head> |
| 309 | <body> |
| 310 | <div id="header"> |
| 311 | <h1> |
| 312 | gitworkflows(7) Manual Page |
| 313 | </h1> |
| 314 | <h2>NAME</h2> |
| 315 | <div class="sectionbody"> |
| 316 | <p>gitworkflows - |
| 317 | An overview of recommended workflows with git |
| 318 | </p> |
| 319 | </div> |
| 320 | </div> |
| 321 | <h2>SYNOPSIS</h2> |
| 322 | <div class="sectionbody"> |
| 323 | <div class="para"><p>git *</p></div> |
| 324 | </div> |
| 325 | <h2 id="_description">DESCRIPTION</h2> |
| 326 | <div class="sectionbody"> |
| 327 | <div class="para"><p>This document attempts to write down and motivate some of the workflow |
| 328 | elements used for <tt>git.git</tt> itself. Many ideas apply in general, |
| 329 | though the full workflow is rarely required for smaller projects with |
| 330 | fewer people involved.</p></div> |
| 331 | <div class="para"><p>We formulate a set of <em>rules</em> for quick reference, while the prose |
| 332 | tries to motivate each of them. Do not always take them literally; |
| 333 | you should value good reasons for your actions higher than manpages |
| 334 | such as this one.</p></div> |
| 335 | </div> |
| 336 | <h2 id="_separate_changes">SEPARATE CHANGES</h2> |
| 337 | <div class="sectionbody"> |
| 338 | <div class="para"><p>As a general rule, you should try to split your changes into small |
| 339 | logical steps, and commit each of them. They should be consistent, |
| 340 | working independently of any later commits, pass the test suite, etc. |
| 341 | This makes the review process much easier, and the history much more |
| 342 | useful for later inspection and analysis, for example with |
| 343 | <a href="git-blame.html">git-blame(1)</a> and <a href="git-bisect.html">git-bisect(1)</a>.</p></div> |
| 344 | <div class="para"><p>To achieve this, try to split your work into small steps from the very |
| 345 | beginning. It is always easier to squash a few commits together than |
| 346 | to split one big commit into several. Don't be afraid of making too |
| 347 | small or imperfect steps along the way. You can always go back later |
| 348 | and edit the commits with <tt>git rebase --interactive</tt> before you |
| 349 | publish them. You can use <tt>git stash save --keep-index</tt> to run the |
| 350 | test suite independent of other uncommitted changes; see the EXAMPLES |
| 351 | section of <a href="git-stash.html">git-stash(1)</a>.</p></div> |
| 352 | </div> |
| 353 | <h2 id="_managing_branches">MANAGING BRANCHES</h2> |
| 354 | <div class="sectionbody"> |
| 355 | <div class="para"><p>There are two main tools that can be used to include changes from one |
| 356 | branch on another: <a href="git-merge.html">git-merge(1)</a> and |
| 357 | <a href="git-cherry-pick.html">git-cherry-pick(1)</a>.</p></div> |
| 358 | <div class="para"><p>Merges have many advantages, so we try to solve as many problems as |
| 359 | possible with merges alone. Cherry-picking is still occasionally |
| 360 | useful; see "Merging upwards" below for an example.</p></div> |
| 361 | <div class="para"><p>Most importantly, merging works at the branch level, while |
| 362 | cherry-picking works at the commit level. This means that a merge can |
| 363 | carry over the changes from 1, 10, or 1000 commits with equal ease, |
| 364 | which in turn means the workflow scales much better to a large number |
| 365 | of contributors (and contributions). Merges are also easier to |
| 366 | understand because a merge commit is a "promise" that all changes from |
| 367 | all its parents are now included.</p></div> |
| 368 | <div class="para"><p>There is a tradeoff of course: merges require a more careful branch |
| 369 | management. The following subsections discuss the important points.</p></div> |
| 370 | <h3 id="_graduation">Graduation</h3><div style="clear:left"></div> |
| 371 | <div class="para"><p>As a given feature goes from experimental to stable, it also |
| 372 | "graduates" between the corresponding branches of the software. |
| 373 | <tt>git.git</tt> uses the following <em>integration branches</em>:</p></div> |
| 374 | <div class="ilist"><ul> |
| 375 | <li> |
| 376 | <p> |
| 377 | <em>maint</em> tracks the commits that should go into the next "maintenance |
| 378 | release", i.e., update of the last released stable version; |
| 379 | </p> |
| 380 | </li> |
| 381 | <li> |
| 382 | <p> |
| 383 | <em>master</em> tracks the commits that should go into the next release; |
| 384 | </p> |
| 385 | </li> |
| 386 | <li> |
| 387 | <p> |
| 388 | <em>next</em> is intended as a testing branch for topics being tested for |
| 389 | stability for master. |
| 390 | </p> |
| 391 | </li> |
| 392 | </ul></div> |
| 393 | <div class="para"><p>There is a fourth official branch that is used slightly differently:</p></div> |
| 394 | <div class="ilist"><ul> |
| 395 | <li> |
| 396 | <p> |
| 397 | <em>pu</em> (proposed updates) is an integration branch for things that are |
| 398 | not quite ready for inclusion yet (see "Integration Branches" |
| 399 | below). |
| 400 | </p> |
| 401 | </li> |
| 402 | </ul></div> |
| 403 | <div class="para"><p>Each of the four branches is usually a direct descendant of the one |
| 404 | above it.</p></div> |
| 405 | <div class="para"><p>Conceptually, the feature enters at an unstable branch (usually <em>next</em> |
| 406 | or <em>pu</em>), and "graduates" to <em>master</em> for the next release once it is |
| 407 | considered stable enough.</p></div> |
| 408 | <h3 id="_merging_upwards">Merging upwards</h3><div style="clear:left"></div> |
| 409 | <div class="para"><p>The "downwards graduation" discussed above cannot be done by actually |
| 410 | merging downwards, however, since that would merge <em>all</em> changes on |
| 411 | the unstable branch into the stable one. Hence the following:</p></div> |
| 412 | <div class="exampleblock"> |
| 413 | <div class="title">Rule: Merge upwards</div> |
| 414 | <div class="exampleblock-content"> |
| 415 | <div class="para"><p>Always commit your fixes to the oldest supported branch that require |
| 416 | them. Then (periodically) merge the integration branches upwards into each |
| 417 | other.</p></div> |
| 418 | </div></div> |
| 419 | <div class="para"><p>This gives a very controlled flow of fixes. If you notice that you |
| 420 | have applied a fix to e.g. <em>master</em> that is also required in <em>maint</em>, |
| 421 | you will need to cherry-pick it (using <a href="git-cherry-pick.html">git-cherry-pick(1)</a>) |
| 422 | downwards. This will happen a few times and is nothing to worry about |
| 423 | unless you do it very frequently.</p></div> |
| 424 | <h3 id="_topic_branches">Topic branches</h3><div style="clear:left"></div> |
| 425 | <div class="para"><p>Any nontrivial feature will require several patches to implement, and |
| 426 | may get extra bugfixes or improvements during its lifetime.</p></div> |
| 427 | <div class="para"><p>Committing everything directly on the integration branches leads to many |
| 428 | problems: Bad commits cannot be undone, so they must be reverted one |
| 429 | by one, which creates confusing histories and further error potential |
| 430 | when you forget to revert part of a group of changes. Working in |
| 431 | parallel mixes up the changes, creating further confusion.</p></div> |
| 432 | <div class="para"><p>Use of "topic branches" solves these problems. The name is pretty |
| 433 | self explanatory, with a caveat that comes from the "merge upwards" |
| 434 | rule above:</p></div> |
| 435 | <div class="exampleblock"> |
| 436 | <div class="title">Rule: Topic branches</div> |
| 437 | <div class="exampleblock-content"> |
| 438 | <div class="para"><p>Make a side branch for every topic (feature, bugfix, …). Fork it off |
| 439 | at the oldest integration branch that you will eventually want to merge it |
| 440 | into.</p></div> |
| 441 | </div></div> |
| 442 | <div class="para"><p>Many things can then be done very naturally:</p></div> |
| 443 | <div class="ilist"><ul> |
| 444 | <li> |
| 445 | <p> |
| 446 | To get the feature/bugfix into an integration branch, simply merge |
| 447 | it. If the topic has evolved further in the meantime, merge again. |
| 448 | (Note that you do not necessarily have to merge it to the oldest |
| 449 | integration branch first. For example, you can first merge a bugfix |
| 450 | to <em>next</em>, give it some testing time, and merge to <em>maint</em> when you |
| 451 | know it is stable.) |
| 452 | </p> |
| 453 | </li> |
| 454 | <li> |
| 455 | <p> |
| 456 | If you find you need new features from the branch <em>other</em> to continue |
| 457 | working on your topic, merge <em>other</em> to <em>topic</em>. (However, do not |
| 458 | do this "just habitually", see below.) |
| 459 | </p> |
| 460 | </li> |
| 461 | <li> |
| 462 | <p> |
| 463 | If you find you forked off the wrong branch and want to move it |
| 464 | "back in time", use <a href="git-rebase.html">git-rebase(1)</a>. |
| 465 | </p> |
| 466 | </li> |
| 467 | </ul></div> |
| 468 | <div class="para"><p>Note that the last point clashes with the other two: a topic that has |
| 469 | been merged elsewhere should not be rebased. See the section on |
| 470 | RECOVERING FROM UPSTREAM REBASE in <a href="git-rebase.html">git-rebase(1)</a>.</p></div> |
| 471 | <div class="para"><p>We should point out that "habitually" (regularly for no real reason) |
| 472 | merging an integration branch into your topics — and by extension, |
| 473 | merging anything upstream into anything downstream on a regular basis |
| 474 | — is frowned upon:</p></div> |
| 475 | <div class="exampleblock"> |
| 476 | <div class="title">Rule: Merge to downstream only at well-defined points</div> |
| 477 | <div class="exampleblock-content"> |
| 478 | <div class="para"><p>Do not merge to downstream except with a good reason: upstream API |
| 479 | changes affect your branch; your branch no longer merges to upstream |
| 480 | cleanly; etc.</p></div> |
| 481 | </div></div> |
| 482 | <div class="para"><p>Otherwise, the topic that was merged to suddenly contains more than a |
| 483 | single (well-separated) change. The many resulting small merges will |
| 484 | greatly clutter up history. Anyone who later investigates the history |
| 485 | of a file will have to find out whether that merge affected the topic |
| 486 | in development. An upstream might even inadvertently be merged into a |
| 487 | "more stable" branch. And so on.</p></div> |
| 488 | <h3 id="_throw_away_integration">Throw-away integration</h3><div style="clear:left"></div> |
| 489 | <div class="para"><p>If you followed the last paragraph, you will now have many small topic |
| 490 | branches, and occasionally wonder how they interact. Perhaps the |
| 491 | result of merging them does not even work? But on the other hand, we |
| 492 | want to avoid merging them anywhere "stable" because such merges |
| 493 | cannot easily be undone.</p></div> |
| 494 | <div class="para"><p>The solution, of course, is to make a merge that we can undo: merge |
| 495 | into a throw-away branch.</p></div> |
| 496 | <div class="exampleblock"> |
| 497 | <div class="title">Rule: Throw-away integration branches</div> |
| 498 | <div class="exampleblock-content"> |
| 499 | <div class="para"><p>To test the interaction of several topics, merge them into a |
| 500 | throw-away branch. You must never base any work on such a branch!</p></div> |
| 501 | </div></div> |
| 502 | <div class="para"><p>If you make it (very) clear that this branch is going to be deleted |
| 503 | right after the testing, you can even publish this branch, for example |
| 504 | to give the testers a chance to work with it, or other developers a |
| 505 | chance to see if their in-progress work will be compatible. <tt>git.git</tt> |
| 506 | has such an official throw-away integration branch called <em>pu</em>.</p></div> |
| 507 | </div> |
| 508 | <h2 id="_distributed_workflows">DISTRIBUTED WORKFLOWS</h2> |
| 509 | <div class="sectionbody"> |
| 510 | <div class="para"><p>After the last section, you should know how to manage topics. In |
| 511 | general, you will not be the only person working on the project, so |
| 512 | you will have to share your work.</p></div> |
| 513 | <div class="para"><p>Roughly speaking, there are two important workflows: merge and patch. |
| 514 | The important difference is that the merge workflow can propagate full |
| 515 | history, including merges, while patches cannot. Both workflows can |
| 516 | be used in parallel: in <tt>git.git</tt>, only subsystem maintainers use |
| 517 | the merge workflow, while everyone else sends patches.</p></div> |
| 518 | <div class="para"><p>Note that the maintainer(s) may impose restrictions, such as |
| 519 | "Signed-off-by" requirements, that all commits/patches submitted for |
| 520 | inclusion must adhere to. Consult your project's documentation for |
| 521 | more information.</p></div> |
| 522 | <h3 id="_merge_workflow">Merge workflow</h3><div style="clear:left"></div> |
| 523 | <div class="para"><p>The merge workflow works by copying branches between upstream and |
| 524 | downstream. Upstream can merge contributions into the official |
| 525 | history; downstream base their work on the official history.</p></div> |
| 526 | <div class="para"><p>There are three main tools that can be used for this:</p></div> |
| 527 | <div class="ilist"><ul> |
| 528 | <li> |
| 529 | <p> |
| 530 | <a href="git-push.html">git-push(1)</a> copies your branches to a remote repository, |
| 531 | usually to one that can be read by all involved parties; |
| 532 | </p> |
| 533 | </li> |
| 534 | <li> |
| 535 | <p> |
| 536 | <a href="git-fetch.html">git-fetch(1)</a> that copies remote branches to your repository; |
| 537 | and |
| 538 | </p> |
| 539 | </li> |
| 540 | <li> |
| 541 | <p> |
| 542 | <a href="git-pull.html">git-pull(1)</a> that does fetch and merge in one go. |
| 543 | </p> |
| 544 | </li> |
| 545 | </ul></div> |
| 546 | <div class="para"><p>Note the last point. Do <em>not</em> use <em>git-pull</em> unless you actually want |
| 547 | to merge the remote branch.</p></div> |
| 548 | <div class="para"><p>Getting changes out is easy:</p></div> |
| 549 | <div class="exampleblock"> |
| 550 | <div class="title">Recipe: Push/pull: Publishing branches/topics</div> |
| 551 | <div class="exampleblock-content"> |
| 552 | <div class="para"><p><tt>git push <remote> <branch></tt> and tell everyone where they can fetch |
| 553 | from.</p></div> |
| 554 | </div></div> |
| 555 | <div class="para"><p>You will still have to tell people by other means, such as mail. (Git |
| Junio C Hamano | 845880c | 2008-10-21 19:04:45 | [diff] [blame] | 556 | provides the <a href="git-request-pull.html">git-request-pull(1)</a> to send preformatted pull |
| Junio C Hamano | 7d06a8a | 2008-10-20 05:42:33 | [diff] [blame] | 557 | requests to upstream maintainers to simplify this task.)</p></div> |
| 558 | <div class="para"><p>If you just want to get the newest copies of the integration branches, |
| 559 | staying up to date is easy too:</p></div> |
| 560 | <div class="exampleblock"> |
| 561 | <div class="title">Recipe: Push/pull: Staying up to date</div> |
| 562 | <div class="exampleblock-content"> |
| 563 | <div class="para"><p>Use <tt>git fetch <remote></tt> or <tt>git remote update</tt> to stay up to date.</p></div> |
| 564 | </div></div> |
| 565 | <div class="para"><p>Then simply fork your topic branches from the stable remotes as |
| 566 | explained earlier.</p></div> |
| 567 | <div class="para"><p>If you are a maintainer and would like to merge other people's topic |
| 568 | branches to the integration branches, they will typically send a |
| 569 | request to do so by mail. Such a request looks like</p></div> |
| 570 | <div class="listingblock"> |
| 571 | <div class="content"> |
| 572 | <pre><tt>Please pull from |
| 573 | <url> <branch></tt></pre> |
| 574 | </div></div> |
| 575 | <div class="para"><p>In that case, <em>git-pull</em> can do the fetch and merge in one go, as |
| 576 | follows.</p></div> |
| 577 | <div class="exampleblock"> |
| 578 | <div class="title">Recipe: Push/pull: Merging remote topics</div> |
| 579 | <div class="exampleblock-content"> |
| 580 | <div class="para"><p><tt>git pull <url> <branch></tt></p></div> |
| 581 | </div></div> |
| 582 | <div class="para"><p>Occasionally, the maintainer may get merge conflicts when he tries to |
| 583 | pull changes from downstream. In this case, he can ask downstream to |
| 584 | do the merge and resolve the conflicts themselves (perhaps they will |
| 585 | know better how to resolve them). It is one of the rare cases where |
| 586 | downstream <em>should</em> merge from upstream.</p></div> |
| 587 | <h3 id="_patch_workflow">Patch workflow</h3><div style="clear:left"></div> |
| 588 | <div class="para"><p>If you are a contributor that sends changes upstream in the form of |
| 589 | emails, you should use topic branches as usual (see above). Then use |
| 590 | <a href="git-format-patch.html">git-format-patch(1)</a> to generate the corresponding emails |
| 591 | (highly recommended over manually formatting them because it makes the |
| 592 | maintainer's life easier).</p></div> |
| 593 | <div class="exampleblock"> |
| 594 | <div class="title">Recipe: format-patch/am: Publishing branches/topics</div> |
| 595 | <div class="exampleblock-content"> |
| 596 | <div class="ilist"><ul> |
| 597 | <li> |
| 598 | <p> |
| 599 | <tt>git format-patch -M upstream..topic</tt> to turn them into preformatted |
| 600 | patch files |
| 601 | </p> |
| 602 | </li> |
| 603 | <li> |
| 604 | <p> |
| 605 | <tt>git send-email --to=<recipient> <patches></tt> |
| 606 | </p> |
| 607 | </li> |
| 608 | </ul></div> |
| 609 | </div></div> |
| 610 | <div class="para"><p>See the <a href="git-format-patch.html">git-format-patch(1)</a> and <a href="git-send-email.html">git-send-email(1)</a> |
| 611 | manpages for further usage notes.</p></div> |
| 612 | <div class="para"><p>If the maintainer tells you that your patch no longer applies to the |
| 613 | current upstream, you will have to rebase your topic (you cannot use a |
| 614 | merge because you cannot format-patch merges):</p></div> |
| 615 | <div class="exampleblock"> |
| 616 | <div class="title">Recipe: format-patch/am: Keeping topics up to date</div> |
| 617 | <div class="exampleblock-content"> |
| 618 | <div class="para"><p><tt>git pull --rebase <url> <branch></tt></p></div> |
| 619 | </div></div> |
| 620 | <div class="para"><p>You can then fix the conflicts during the rebase. Presumably you have |
| 621 | not published your topic other than by mail, so rebasing it is not a |
| 622 | problem.</p></div> |
| 623 | <div class="para"><p>If you receive such a patch series (as maintainer, or perhaps as a |
| 624 | reader of the mailing list it was sent to), save the mails to files, |
| 625 | create a new topic branch and use <em>git-am</em> to import the commits:</p></div> |
| 626 | <div class="exampleblock"> |
| 627 | <div class="title">Recipe: format-patch/am: Importing patches</div> |
| 628 | <div class="exampleblock-content"> |
| 629 | <div class="para"><p><tt>git am < patch</tt></p></div> |
| 630 | </div></div> |
| 631 | <div class="para"><p>One feature worth pointing out is the three-way merge, which can help |
| 632 | if you get conflicts: <tt>git am -3</tt> will use index information contained |
| 633 | in patches to figure out the merge base. See <a href="git-am.html">git-am(1)</a> for |
| 634 | other options.</p></div> |
| 635 | </div> |
| 636 | <h2 id="_see_also">SEE ALSO</h2> |
| 637 | <div class="sectionbody"> |
| 638 | <div class="para"><p><a href="gittutorial.html">gittutorial(7)</a>, |
| 639 | <a href="git-push.html">git-push(1)</a>, |
| 640 | <a href="git-pull.html">git-pull(1)</a>, |
| 641 | <a href="git-merge.html">git-merge(1)</a>, |
| 642 | <a href="git-rebase.html">git-rebase(1)</a>, |
| 643 | <a href="git-format-patch.html">git-format-patch(1)</a>, |
| 644 | <a href="git-send-email.html">git-send-email(1)</a>, |
| 645 | <a href="git-am.html">git-am(1)</a></p></div> |
| 646 | </div> |
| 647 | <h2 id="_git">GIT</h2> |
| 648 | <div class="sectionbody"> |
| 649 | <div class="para"><p>Part of the <a href="git.html">git(1)</a> suite.</p></div> |
| 650 | </div> |
| 651 | <div id="footer"> |
| 652 | <div id="footer-text"> |
| Junio C Hamano | 9572e92 | 2009-04-02 06:52:03 | [diff] [blame] | 653 | Last updated 2009-04-02 06:50:12 UTC |
| Junio C Hamano | 7d06a8a | 2008-10-20 05:42:33 | [diff] [blame] | 654 | </div> |
| 655 | </div> |
| 656 | </body> |
| 657 | </html> |
