| blob | cb219539f848ba347195c7adfd4e719148e553fe |
4 <head>
8 /* Debug borders */
10 /*
11 border: 1px solid red;
12 */
13 }
15 body {
17 }
19 a {
22 }
25 }
27 em {
29 }
31 strong {
33 }
35 tt {
37 }
45 }
49 }
50 h2 {
52 }
53 h3 {
55 }
56 h3 + * {
58 }
63 }
65 hr {
67 }
69 p {
72 }
74 pre {
77 }
79 span#author {
84 }
85 span#email {
86 }
87 span#revision {
89 }
91 div#footer {
97 }
98 div#footer-text {
101 }
102 div#footer-badges {
105 }
107 div#preamble,
114 }
118 }
122 }
124 /* Block element titles. */
131 }
134 }
138 }
141 }
144 }
150 }
154 }
159 }
163 }
167 }
170 }
179 }
183 }
188 }
192 }
198 dl {
201 }
202 dt {
206 }
209 }
213 }
216 }
220 }
221 thead {
224 }
225 tfoot {
227 }
232 }
235 }
240 }
243 }
247 }
249 div#toctitle {
256 }
261 }
265 }
269 }
273 }
275 /* Workarounds for IE6's broken and incomplete CSS2. */
281 }
287 }
293 }
297 }
302 }
304 /* IE6 sets dynamically generated links as visited. */
306 </style>
308 </head>
309 <body>
311 <h1>
312 gitworkflows(7) Manual Page
313 </h1>
316 <p>gitworkflows -
317 An overview of recommended workflows with git
318 </p>
319 </div>
320 </div>
324 </div>
329 though the full workflow is rarely required for smaller projects with
330 fewer people involved.</p></div>
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>
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>
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
350 test suite independent of other uncommitted changes; see the EXAMPLES
352 </div>
359 possible with merges alone. Cherry-picking is still occasionally
362 cherry-picking works at the commit level. This means that a merge can
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>
369 management. The following subsections discuss the important points.</p></div>
372 "graduates" between the corresponding branches of the software.
375 <li>
376 <p>
378 release", i.e., update of the last released stable version;
379 </p>
380 </li>
381 <li>
382 <p>
384 </p>
385 </li>
386 <li>
387 <p>
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>
395 <li>
396 <p>
398 not quite ready for inclusion yet (see "Integration Branches"
399 below).
400 </p>
401 </li>
402 </ul></div>
404 above it.</p></div>
405 <div class="para"><p>Conceptually, the feature enters at an unstable branch (usually <em>next</em>
407 considered stable enough.</p></div>
411 the unstable branch into the stable one. Hence the following:</p></div>
416 them. Then (periodically) merge the integration branches upwards into each
417 other.</p></div>
418 </div></div>
422 downwards. This will happen a few times and is nothing to worry about
423 unless you do it very frequently.</p></div>
426 may get extra bugfixes or improvements during its lifetime.</p></div>
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>
433 self explanatory, with a caveat that comes from the "merge upwards"
434 rule above:</p></div>
439 at the oldest integration branch that you will eventually want to merge it
440 into.</p></div>
441 </div></div>
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
451 know it is stable.)
452 </p>
453 </li>
454 <li>
455 <p>
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
465 </p>
466 </li>
467 </ul></div>
469 been merged elsewhere should not be rebased. See the section on
472 merging an integration branch into your topics — and by extension,
473 merging anything upstream into anything downstream on a regular basis
479 changes affect your branch; your branch no longer merges to upstream
480 cleanly; etc.</p></div>
481 </div></div>
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
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>
495 into a throw-away branch.</p></div>
500 throw-away branch. You must never base any work on such a branch!</p></div>
501 </div></div>
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
507 <h3 id="_branch_management_for_a_release">Branch management for a release</h3><div style="clear:left"></div>
509 are releasing your project you will need to do some additional branch
510 management work.</p></div>
511 <div class="para"><p>A feature release is created from the <em>master</em> branch, since <em>master</em>
512 tracks the commits that should go into the next feature release.</p></div>
513 <div class="para"><p>The <em>master</em> branch is supposed to be a superset of <em>maint</em>. If this
516 will therefore not be included in your feature release.</p></div>
517 <div class="para"><p>To verify that <em>master</em> is indeed a superset of <em>maint</em>, use git log:</p></div>
522 </div></div>
531 </div></div>
533 "DISTRIBUTED WORKFLOWS" below). This makes the tag available to
534 others tracking your project. The push could also trigger a
535 post-update hook to perform release-related items such as building
536 release tarballs and preformatted documentation pages.</p></div>
537 <div class="para"><p>Similarly, for a maintenance release, <em>maint</em> is tracking the commits
538 to be released. Therefore, in the steps above simply tag and push
540 <h3 id="_maintenance_branch_management_after_a_feature_release">Maintenance branch management after a feature release</h3><div style="clear:left"></div>
541 <div class="para"><p>After a feature release, you need to manage your maintenance branches.</p></div>
543 feature release made before the recent one, then you must create
544 another branch to track commits for that previous release.</p></div>
546 named with the previous release version number (e.g. maint-X.Y.(Z-1)
547 where X.Y.Z is the current release).</p></div>
552 </div></div>
553 <div class="para"><p>The <em>maint</em> branch should now be fast-forwarded to the newly released
554 code so that maintenance fixes can be tracked for the current release:</p></div>
559 <li>
560 <p>
562 </p>
563 </li>
564 <li>
565 <p>
567 </p>
568 </li>
569 </ul></div>
570 </div></div>
573 This will not happen if the content of the branches was verified as
574 described in the previous section.</p></div>
575 <h3 id="_branch_management_for_next_and_pu_after_a_feature_release">Branch management for next and pu after a feature release</h3><div style="clear:left"></div>
576 <div class="para"><p>After a feature release, the integration branch <em>next</em> may optionally be
583 <li>
584 <p>
586 </p>
587 </li>
588 <li>
589 <p>
591 </p>
592 </li>
593 <li>
594 <p>
596 </p>
597 </li>
598 <li>
599 <p>
601 </p>
602 </li>
603 <li>
604 <p>
605 …
606 </p>
607 </li>
608 </ul></div>
609 </div></div>
612 looked promising, but were later found to be undesirable or premature.
614 remains in the history that it was once merged and reverted. By
616 slate to retry, and a feature release is a good point in history to do
617 so.</p></div>
620 <div class="para"><p>The same rewind and rebuild process may be followed for <em>pu</em>. A public
622 described above.</p></div>
623 </div>
627 general, you will not be the only person working on the project, so
628 you will have to share your work.</p></div>
630 The important difference is that the merge workflow can propagate full
631 history, including merges, while patches cannot. Both workflows can
633 the merge workflow, while everyone else sends patches.</p></div>
635 "Signed-off-by" requirements, that all commits/patches submitted for
636 inclusion must adhere to. Consult your project's documentation for
637 more information.</p></div>
640 downstream. Upstream can merge contributions into the official
641 history; downstream base their work on the official history.</p></div>
644 <li>
645 <p>
647 usually to one that can be read by all involved parties;
648 </p>
649 </li>
650 <li>
651 <p>
653 and
654 </p>
655 </li>
656 <li>
657 <p>
659 </p>
660 </li>
661 </ul></div>
662 <div class="para"><p>Note the last point. Do <em>not</em> use <em>git pull</em> unless you actually want
663 to merge the remote branch.</p></div>
668 <div class="para"><p><tt>git push <remote> <branch></tt> and tell everyone where they can fetch
669 from.</p></div>
670 </div></div>
673 requests to upstream maintainers to simplify this task.)</p></div>
675 staying up to date is easy too:</p></div>
679 <div class="para"><p>Use <tt>git fetch <remote></tt> or <tt>git remote update</tt> to stay up to date.</p></div>
680 </div></div>
682 explained earlier.</p></div>
684 branches to the integration branches, they will typically send a
685 request to do so by mail. Such a request looks like</p></div>
688 <pre><tt>Please pull from
690 </div></div>
692 follows.</p></div>
697 </div></div>
699 pull changes from downstream. In this case, he can ask downstream to
700 do the merge and resolve the conflicts themselves (perhaps they will
701 know better how to resolve them). It is one of the rare cases where
705 emails, you should use topic branches as usual (see above). Then use
707 (highly recommended over manually formatting them because it makes the
708 maintainer's life easier).</p></div>
713 <li>
714 <p>
716 patch files
717 </p>
718 </li>
719 <li>
720 <p>
722 </p>
723 </li>
724 </ul></div>
725 </div></div>
726 <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>
727 manpages for further usage notes.</p></div>
729 current upstream, you will have to rebase your topic (you cannot use a
730 merge because you cannot format-patch merges):</p></div>
735 </div></div>
737 not published your topic other than by mail, so rebasing it is not a
738 problem.</p></div>
740 reader of the mailing list it was sent to), save the mails to files,
746 </div></div>
750 other options.</p></div>
751 </div>
762 </div>
766 </div>
770 </div>
771 </div>
772 </body>
773 </html>