| blob | 950589c39f82c0bfd2c7bd0fbd3e886f5911cb93 |
4 <head>
9 /* Debug borders */
11 /*
12 border: 1px solid red;
13 */
14 }
16 body {
18 }
20 a {
23 }
26 }
28 em {
31 }
33 strong {
36 }
38 tt {
40 }
48 }
52 }
53 h2 {
55 }
56 h3 {
58 }
59 h3 + * {
61 }
66 }
68 hr {
70 }
72 p {
75 }
79 }
81 pre {
84 }
86 span#author {
91 }
92 span#email {
93 }
96 }
98 div#footer {
104 }
105 div#footer-text {
108 }
109 div#footer-badges {
112 }
114 div#preamble {
117 }
123 }
127 }
131 }
133 /* Block element titles. */
141 }
144 }
148 }
151 }
154 }
160 }
166 }
171 }
175 }
180 }
183 }
187 }
188 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
191 }
200 }
204 }
209 }
215 dl {
218 }
219 dt {
224 }
227 }
231 }
234 }
237 }
240 }
243 }
246 }
253 }
257 }
258 thead {
261 }
262 tfoot {
264 }
267 }
270 }
271 /* Because the table frame attribute is overriden by CSS in most browsers. */
274 }
278 }
282 }
288 }
291 }
294 }
300 }
303 }
307 }
311 }
315 }
317 div#toctitle {
324 }
329 }
333 }
337 }
341 }
342 /* Overrides for manpage documents */
343 h1 {
348 }
349 h2 {
351 }
354 }
358 }
360 /* Workarounds for IE6's broken and incomplete CSS2. */
366 }
373 }
379 }
384 }
388 }
392 }
397 }
399 /* IE6 sets dynamically generated links as visited. */
401 </style>
402 </head>
403 <body>
405 <h1>
406 gitworkflows(7) Manual Page
407 </h1>
410 <p>gitworkflows -
411 An overview of recommended workflows with git
412 </p>
413 </div>
414 </div>
420 </div></div>
421 </div>
424 <div class="paragraph"><p>This document attempts to write down and motivate some of the workflow
426 though the full workflow is rarely required for smaller projects with
427 fewer people involved.</p></div>
428 <div class="paragraph"><p>We formulate a set of <em>rules</em> for quick reference, while the prose
429 tries to motivate each of them. Do not always take them literally;
430 you should value good reasons for your actions higher than manpages
431 such as this one.</p></div>
432 </div>
436 logical steps, and commit each of them. They should be consistent,
437 working independently of any later commits, pass the test suite, etc.
438 This makes the review process much easier, and the history much more
439 useful for later inspection and analysis, for example with
440 <a href="git-blame.html">git-blame(1)</a> and <a href="git-bisect.html">git-bisect(1)</a>.</p></div>
441 <div class="paragraph"><p>To achieve this, try to split your work into small steps from the very
442 beginning. It is always easier to squash a few commits together than
443 to split one big commit into several. Don’t be afraid of making too
444 small or imperfect steps along the way. You can always go back later
447 test suite independent of other uncommitted changes; see the EXAMPLES
449 </div>
456 possible with merges alone. Cherry-picking is still occasionally
459 cherry-picking works at the commit level. This means that a merge can
461 which in turn means the workflow scales much better to a large number
462 of contributors (and contributions). Merges are also easier to
463 understand because a merge commit is a "promise" that all changes from
464 all its parents are now included.</p></div>
466 management. The following subsections discuss the important points.</p></div>
469 "graduates" between the corresponding branches of the software.
472 <li>
473 <p>
475 release", i.e., update of the last released stable version;
476 </p>
477 </li>
478 <li>
479 <p>
481 </p>
482 </li>
483 <li>
484 <p>
486 stability for master.
487 </p>
488 </li>
489 </ul></div>
490 <div class="paragraph"><p>There is a fourth official branch that is used slightly differently:</p></div>
492 <li>
493 <p>
495 not quite ready for inclusion yet (see "Integration Branches"
496 below).
497 </p>
498 </li>
499 </ul></div>
501 above it.</p></div>
502 <div class="paragraph"><p>Conceptually, the feature enters at an unstable branch (usually <em>next</em>
504 considered stable enough.</p></div>
508 the unstable branch into the stable one. Hence the following:</p></div>
513 them. Then (periodically) merge the integration branches upwards into each
514 other.</p></div>
515 </div></div>
519 downwards. This will happen a few times and is nothing to worry about
520 unless you do it very frequently.</p></div>
523 may get extra bugfixes or improvements during its lifetime.</p></div>
524 <div class="paragraph"><p>Committing everything directly on the integration branches leads to many
525 problems: Bad commits cannot be undone, so they must be reverted one
526 by one, which creates confusing histories and further error potential
527 when you forget to revert part of a group of changes. Working in
528 parallel mixes up the changes, creating further confusion.</p></div>
530 self explanatory, with a caveat that comes from the "merge upwards"
531 rule above:</p></div>
535 <div class="paragraph"><p>Make a side branch for every topic (feature, bugfix, …). Fork it off
536 at the oldest integration branch that you will eventually want to merge it
537 into.</p></div>
538 </div></div>
541 <li>
542 <p>
543 To get the feature/bugfix into an integration branch, simply merge
544 it. If the topic has evolved further in the meantime, merge again.
545 (Note that you do not necessarily have to merge it to the oldest
546 integration branch first. For example, you can first merge a bugfix
548 know it is stable.)
549 </p>
550 </li>
551 <li>
552 <p>
555 do this "just habitually", see below.)
556 </p>
557 </li>
558 <li>
559 <p>
560 If you find you forked off the wrong branch and want to move it
562 </p>
563 </li>
564 </ul></div>
566 been merged elsewhere should not be rebased. See the section on
569 merging an integration branch into your topics — and by extension,
570 merging anything upstream into anything downstream on a regular basis — is frowned upon:</p></div>
575 changes affect your branch; your branch no longer merges to upstream
576 cleanly; etc.</p></div>
577 </div></div>
579 single (well-separated) change. The many resulting small merges will
580 greatly clutter up history. Anyone who later investigates the history
581 of a file will have to find out whether that merge affected the topic
582 in development. An upstream might even inadvertently be merged into a
585 <div class="paragraph"><p>If you followed the last paragraph, you will now have many small topic
586 branches, and occasionally wonder how they interact. Perhaps the
587 result of merging them does not even work? But on the other hand, we
588 want to avoid merging them anywhere "stable" because such merges
589 cannot easily be undone.</p></div>
591 into a throw-away branch.</p></div>
596 throw-away branch. You must never base any work on such a branch!</p></div>
597 </div></div>
599 right after the testing, you can even publish this branch, for example
600 to give the testers a chance to work with it, or other developers a
603 <h3 id="_branch_management_for_a_release">Branch management for a release</h3><div style="clear:left"></div>
605 are releasing your project you will need to do some additional branch
606 management work.</p></div>
607 <div class="paragraph"><p>A feature release is created from the <em>master</em> branch, since <em>master</em>
608 tracks the commits that should go into the next feature release.</p></div>
609 <div class="paragraph"><p>The <em>master</em> branch is supposed to be a superset of <em>maint</em>. If this
612 will therefore not be included in your feature release.</p></div>
613 <div class="paragraph"><p>To verify that <em>master</em> is indeed a superset of <em>maint</em>, use git log:</p></div>
618 </div></div>
627 </div></div>
629 "DISTRIBUTED WORKFLOWS" below). This makes the tag available to
630 others tracking your project. The push could also trigger a
631 post-update hook to perform release-related items such as building
632 release tarballs and preformatted documentation pages.</p></div>
633 <div class="paragraph"><p>Similarly, for a maintenance release, <em>maint</em> is tracking the commits
634 to be released. Therefore, in the steps above simply tag and push
636 <h3 id="_maintenance_branch_management_after_a_feature_release">Maintenance branch management after a feature release</h3><div style="clear:left"></div>
637 <div class="paragraph"><p>After a feature release, you need to manage your maintenance branches.</p></div>
639 feature release made before the recent one, then you must create
640 another branch to track commits for that previous release.</p></div>
641 <div class="paragraph"><p>To do this, the current maintenance branch is copied to another branch
642 named with the previous release version number (e.g. maint-X.Y.(Z-1)
643 where X.Y.Z is the current release).</p></div>
648 </div></div>
649 <div class="paragraph"><p>The <em>maint</em> branch should now be fast-forwarded to the newly released
650 code so that maintenance fixes can be tracked for the current release:</p></div>
655 <li>
656 <p>
658 </p>
659 </li>
660 <li>
661 <p>
663 </p>
664 </li>
665 </ul></div>
666 </div></div>
669 This will not happen if the content of the branches was verified as
670 described in the previous section.</p></div>
671 <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>
672 <div class="paragraph"><p>After a feature release, the integration branch <em>next</em> may optionally be
679 <li>
680 <p>
682 </p>
683 </li>
684 <li>
685 <p>
687 </p>
688 </li>
689 <li>
690 <p>
692 </p>
693 </li>
694 <li>
695 <p>
697 </p>
698 </li>
699 <li>
700 <p>
701 …
702 </p>
703 </li>
704 </ul></div>
705 </div></div>
706 <div class="paragraph"><p>The advantage of doing this is that the history of <em>next</em> will be
708 looked promising, but were later found to be undesirable or premature.
710 remains in the history that it was once merged and reverted. By
712 slate to retry, and a feature release is a good point in history to do
713 so.</p></div>
716 <div class="paragraph"><p>The same rewind and rebuild process may be followed for <em>pu</em>. A public
718 described above.</p></div>
719 </div>
723 general, you will not be the only person working on the project, so
724 you will have to share your work.</p></div>
726 The important difference is that the merge workflow can propagate full
727 history, including merges, while patches cannot. Both workflows can
729 the merge workflow, while everyone else sends patches.</p></div>
731 "Signed-off-by" requirements, that all commits/patches submitted for
732 inclusion must adhere to. Consult your project’s documentation for
733 more information.</p></div>
736 downstream. Upstream can merge contributions into the official
737 history; downstream base their work on the official history.</p></div>
740 <li>
741 <p>
743 usually to one that can be read by all involved parties;
744 </p>
745 </li>
746 <li>
747 <p>
749 and
750 </p>
751 </li>
752 <li>
753 <p>
755 </p>
756 </li>
757 </ul></div>
758 <div class="paragraph"><p>Note the last point. Do <em>not</em> use <em>git pull</em> unless you actually want
759 to merge the remote branch.</p></div>
764 <div class="paragraph"><p><tt>git push <remote> <branch></tt> and tell everyone where they can fetch
765 from.</p></div>
766 </div></div>
769 requests to upstream maintainers to simplify this task.)</p></div>
770 <div class="paragraph"><p>If you just want to get the newest copies of the integration branches,
771 staying up to date is easy too:</p></div>
775 <div class="paragraph"><p>Use <tt>git fetch <remote></tt> or <tt>git remote update</tt> to stay up to date.</p></div>
776 </div></div>
778 explained earlier.</p></div>
779 <div class="paragraph"><p>If you are a maintainer and would like to merge other people’s topic
780 branches to the integration branches, they will typically send a
781 request to do so by mail. Such a request looks like</p></div>
784 <pre><tt>Please pull from
786 </div></div>
787 <div class="paragraph"><p>In that case, <em>git pull</em> can do the fetch and merge in one go, as
788 follows.</p></div>
793 </div></div>
795 pull changes from downstream. In this case, he can ask downstream to
796 do the merge and resolve the conflicts themselves (perhaps they will
797 know better how to resolve them). It is one of the rare cases where
801 emails, you should use topic branches as usual (see above). Then use
803 (highly recommended over manually formatting them because it makes the
809 <li>
810 <p>
812 patch files
813 </p>
814 </li>
815 <li>
816 <p>
818 </p>
819 </li>
820 </ul></div>
821 </div></div>
822 <div class="paragraph"><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>
823 manpages for further usage notes.</p></div>
825 current upstream, you will have to rebase your topic (you cannot use a
826 merge because you cannot format-patch merges):</p></div>
831 </div></div>
833 not published your topic other than by mail, so rebasing it is not a
834 problem.</p></div>
836 reader of the mailing list it was sent to), save the mails to files,
842 </div></div>
846 other options.</p></div>
847 </div>
858 </div>
862 </div>
866 </div>
867 </div>
868 </body>
869 </html>