| blob | 7a6896de432bdf0e3820a1ca4aadd9861e17f169 |
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 }
129 }
133 }
135 /* Block element titles. */
143 }
146 }
150 }
153 }
156 }
162 }
168 }
176 }
181 }
185 }
189 }
190 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
193 }
202 }
206 }
211 }
217 dl {
220 }
221 dt {
226 }
229 }
233 }
236 }
239 }
242 }
245 }
248 }
255 }
259 }
263 }
264 tfoot {
266 }
269 }
272 }
273 /* Because the table frame attribute is overriden by CSS in most browsers. */
276 }
280 }
284 }
290 }
293 }
296 }
302 }
305 }
309 }
313 }
317 }
321 }
326 }
330 }
340 }
345 }
347 div#toc {
349 }
351 div#toctitle {
358 }
363 }
367 }
371 }
375 }
376 /* Overrides for manpage documents */
377 h1 {
382 }
383 h2 {
385 }
388 }
392 }
394 /* Workarounds for IE6's broken and incomplete CSS2. */
400 }
407 }
413 }
418 }
422 }
426 }
431 }
433 /* IE6 sets dynamically generated links as visited. */
435 </style>
437 /*<![CDATA[*/
441 /////////////////////////////////////////////////////////////////////
442 // Table Of Contents generator
443 /////////////////////////////////////////////////////////////////////
445 /* Author: Mihai Bazon, September 2002
446 * http://students.infoiasi.ro/~mishoo
447 *
448 * Table Of Content generator
449 * Version: 0.4
450 *
451 * Feel free to use this script under the terms of the GNU General Public
452 * License, as long as you do not remove or alter this notice.
453 */
455 /* modified by Troy D. Hanson, September 2006. License: GPL */
456 /* modified by Stuart Rackham, 2006, 2009. License: GPL */
458 // toclevels = 1..4.
468 }
470 }
476 }
481 // Function that scans the DOM tree for header elements (the DOM2
482 // nodeIterator API would be a better technique but not supported by all
483 // browsers).
490 }
492 }
493 }
494 }
497 }
512 }
515 },
518 /////////////////////////////////////////////////////////////////////
519 // Footnotes generator
520 /////////////////////////////////////////////////////////////////////
522 /* Based on footnote generation code from:
523 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
524 */
534 n++;
535 // Use [\s\S] in place of . so multi-line matches work.
536 // Because JavaScript has no s (dotall) regex flag.
547 }
548 }
552 // Process footnoterefs.
561 }
562 }
563 }
564 }
566 }
567 /*]]>*/
568 </script>
569 </head>
570 <body>
572 <h1>
573 gitworkflows(7) Manual Page
574 </h1>
577 <p>gitworkflows -
578 An overview of recommended workflows with git
579 </p>
580 </div>
581 </div>
588 </div></div>
589 </div>
592 <div class="paragraph"><p>This document attempts to write down and motivate some of the workflow
594 though the full workflow is rarely required for smaller projects with
595 fewer people involved.</p></div>
596 <div class="paragraph"><p>We formulate a set of <em>rules</em> for quick reference, while the prose
597 tries to motivate each of them. Do not always take them literally;
598 you should value good reasons for your actions higher than manpages
599 such as this one.</p></div>
600 </div>
604 logical steps, and commit each of them. They should be consistent,
605 working independently of any later commits, pass the test suite, etc.
606 This makes the review process much easier, and the history much more
607 useful for later inspection and analysis, for example with
608 <a href="git-blame.html">git-blame(1)</a> and <a href="git-bisect.html">git-bisect(1)</a>.</p></div>
609 <div class="paragraph"><p>To achieve this, try to split your work into small steps from the very
610 beginning. It is always easier to squash a few commits together than
611 to split one big commit into several. Don’t be afraid of making too
612 small or imperfect steps along the way. You can always go back later
615 test suite independent of other uncommitted changes; see the EXAMPLES
617 </div>
624 possible with merges alone. Cherry-picking is still occasionally
627 cherry-picking works at the commit level. This means that a merge can
629 which in turn means the workflow scales much better to a large number
630 of contributors (and contributions). Merges are also easier to
631 understand because a merge commit is a "promise" that all changes from
632 all its parents are now included.</p></div>
634 management. The following subsections discuss the important points.</p></div>
637 "graduates" between the corresponding branches of the software.
640 <li>
641 <p>
643 release", i.e., update of the last released stable version;
644 </p>
645 </li>
646 <li>
647 <p>
649 </p>
650 </li>
651 <li>
652 <p>
654 stability for master.
655 </p>
656 </li>
657 </ul></div>
658 <div class="paragraph"><p>There is a fourth official branch that is used slightly differently:</p></div>
660 <li>
661 <p>
663 not quite ready for inclusion yet (see "Integration Branches"
664 below).
665 </p>
666 </li>
667 </ul></div>
669 above it.</p></div>
670 <div class="paragraph"><p>Conceptually, the feature enters at an unstable branch (usually <em>next</em>
672 considered stable enough.</p></div>
676 the unstable branch into the stable one. Hence the following:</p></div>
681 them. Then (periodically) merge the integration branches upwards into each
682 other.</p></div>
683 </div></div>
687 downwards. This will happen a few times and is nothing to worry about
688 unless you do it very frequently.</p></div>
691 may get extra bugfixes or improvements during its lifetime.</p></div>
692 <div class="paragraph"><p>Committing everything directly on the integration branches leads to many
693 problems: Bad commits cannot be undone, so they must be reverted one
694 by one, which creates confusing histories and further error potential
695 when you forget to revert part of a group of changes. Working in
696 parallel mixes up the changes, creating further confusion.</p></div>
698 self explanatory, with a caveat that comes from the "merge upwards"
699 rule above:</p></div>
703 <div class="paragraph"><p>Make a side branch for every topic (feature, bugfix, …). Fork it off
704 at the oldest integration branch that you will eventually want to merge it
705 into.</p></div>
706 </div></div>
709 <li>
710 <p>
711 To get the feature/bugfix into an integration branch, simply merge
712 it. If the topic has evolved further in the meantime, merge again.
713 (Note that you do not necessarily have to merge it to the oldest
714 integration branch first. For example, you can first merge a bugfix
716 know it is stable.)
717 </p>
718 </li>
719 <li>
720 <p>
723 do this "just habitually", see below.)
724 </p>
725 </li>
726 <li>
727 <p>
728 If you find you forked off the wrong branch and want to move it
730 </p>
731 </li>
732 </ul></div>
734 been merged elsewhere should not be rebased. See the section on
737 merging an integration branch into your topics — and by extension,
738 merging anything upstream into anything downstream on a regular basis — is frowned upon:</p></div>
743 changes affect your branch; your branch no longer merges to upstream
744 cleanly; etc.</p></div>
745 </div></div>
747 single (well-separated) change. The many resulting small merges will
748 greatly clutter up history. Anyone who later investigates the history
749 of a file will have to find out whether that merge affected the topic
750 in development. An upstream might even inadvertently be merged into a
753 <div class="paragraph"><p>If you followed the last paragraph, you will now have many small topic
754 branches, and occasionally wonder how they interact. Perhaps the
755 result of merging them does not even work? But on the other hand, we
756 want to avoid merging them anywhere "stable" because such merges
757 cannot easily be undone.</p></div>
759 into a throw-away branch.</p></div>
764 throw-away branch. You must never base any work on such a branch!</p></div>
765 </div></div>
767 right after the testing, you can even publish this branch, for example
768 to give the testers a chance to work with it, or other developers a
771 <h3 id="_branch_management_for_a_release">Branch management for a release</h3><div style="clear:left"></div>
773 are releasing your project you will need to do some additional branch
774 management work.</p></div>
775 <div class="paragraph"><p>A feature release is created from the <em>master</em> branch, since <em>master</em>
776 tracks the commits that should go into the next feature release.</p></div>
777 <div class="paragraph"><p>The <em>master</em> branch is supposed to be a superset of <em>maint</em>. If this
780 will therefore not be included in your feature release.</p></div>
781 <div class="paragraph"><p>To verify that <em>master</em> is indeed a superset of <em>maint</em>, use git log:</p></div>
786 </div></div>
795 </div></div>
797 "DISTRIBUTED WORKFLOWS" below). This makes the tag available to
798 others tracking your project. The push could also trigger a
799 post-update hook to perform release-related items such as building
800 release tarballs and preformatted documentation pages.</p></div>
801 <div class="paragraph"><p>Similarly, for a maintenance release, <em>maint</em> is tracking the commits
802 to be released. Therefore, in the steps above simply tag and push
804 <h3 id="_maintenance_branch_management_after_a_feature_release">Maintenance branch management after a feature release</h3><div style="clear:left"></div>
805 <div class="paragraph"><p>After a feature release, you need to manage your maintenance branches.</p></div>
807 feature release made before the recent one, then you must create
808 another branch to track commits for that previous release.</p></div>
809 <div class="paragraph"><p>To do this, the current maintenance branch is copied to another branch
810 named with the previous release version number (e.g. maint-X.Y.(Z-1)
811 where X.Y.Z is the current release).</p></div>
816 </div></div>
817 <div class="paragraph"><p>The <em>maint</em> branch should now be fast-forwarded to the newly released
818 code so that maintenance fixes can be tracked for the current release:</p></div>
823 <li>
824 <p>
826 </p>
827 </li>
828 <li>
829 <p>
831 </p>
832 </li>
833 </ul></div>
834 </div></div>
837 This will not happen if the content of the branches was verified as
838 described in the previous section.</p></div>
839 <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>
840 <div class="paragraph"><p>After a feature release, the integration branch <em>next</em> may optionally be
847 <li>
848 <p>
850 </p>
851 </li>
852 <li>
853 <p>
855 </p>
856 </li>
857 <li>
858 <p>
860 </p>
861 </li>
862 <li>
863 <p>
865 </p>
866 </li>
867 <li>
868 <p>
869 …
870 </p>
871 </li>
872 </ul></div>
873 </div></div>
874 <div class="paragraph"><p>The advantage of doing this is that the history of <em>next</em> will be
876 looked promising, but were later found to be undesirable or premature.
878 remains in the history that it was once merged and reverted. By
880 slate to retry, and a feature release is a good point in history to do
881 so.</p></div>
884 <div class="paragraph"><p>The same rewind and rebuild process may be followed for <em>pu</em>. A public
886 described above.</p></div>
887 </div>
891 general, you will not be the only person working on the project, so
892 you will have to share your work.</p></div>
894 The important difference is that the merge workflow can propagate full
895 history, including merges, while patches cannot. Both workflows can
897 the merge workflow, while everyone else sends patches.</p></div>
899 "Signed-off-by" requirements, that all commits/patches submitted for
900 inclusion must adhere to. Consult your project’s documentation for
901 more information.</p></div>
904 downstream. Upstream can merge contributions into the official
905 history; downstream base their work on the official history.</p></div>
908 <li>
909 <p>
911 usually to one that can be read by all involved parties;
912 </p>
913 </li>
914 <li>
915 <p>
917 and
918 </p>
919 </li>
920 <li>
921 <p>
923 </p>
924 </li>
925 </ul></div>
926 <div class="paragraph"><p>Note the last point. Do <em>not</em> use <em>git pull</em> unless you actually want
927 to merge the remote branch.</p></div>
932 <div class="paragraph"><p><tt>git push <remote> <branch></tt> and tell everyone where they can fetch
933 from.</p></div>
934 </div></div>
937 requests to upstream maintainers to simplify this task.)</p></div>
938 <div class="paragraph"><p>If you just want to get the newest copies of the integration branches,
939 staying up to date is easy too:</p></div>
943 <div class="paragraph"><p>Use <tt>git fetch <remote></tt> or <tt>git remote update</tt> to stay up to date.</p></div>
944 </div></div>
946 explained earlier.</p></div>
947 <div class="paragraph"><p>If you are a maintainer and would like to merge other people’s topic
948 branches to the integration branches, they will typically send a
949 request to do so by mail. Such a request looks like</p></div>
952 <pre><tt>Please pull from
954 </div></div>
955 <div class="paragraph"><p>In that case, <em>git pull</em> can do the fetch and merge in one go, as
956 follows.</p></div>
961 </div></div>
963 pull changes from downstream. In this case, he can ask downstream to
964 do the merge and resolve the conflicts themselves (perhaps they will
965 know better how to resolve them). It is one of the rare cases where
969 emails, you should use topic branches as usual (see above). Then use
971 (highly recommended over manually formatting them because it makes the
977 <li>
978 <p>
980 patch files
981 </p>
982 </li>
983 <li>
984 <p>
986 </p>
987 </li>
988 </ul></div>
989 </div></div>
990 <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>
991 manpages for further usage notes.</p></div>
993 current upstream, you will have to rebase your topic (you cannot use a
994 merge because you cannot format-patch merges):</p></div>
999 </div></div>
1000 <div class="paragraph"><p>You can then fix the conflicts during the rebase. Presumably you have
1001 not published your topic other than by mail, so rebasing it is not a
1002 problem.</p></div>
1004 reader of the mailing list it was sent to), save the mails to files,
1010 </div></div>
1011 <div class="paragraph"><p>One feature worth pointing out is the three-way merge, which can help
1014 other options.</p></div>
1015 </div>
1026 </div>
1030 </div>
1031 </div>
1036 </div>
1037 </div>
1038 </body>
1039 </html>