gitworkflows.html

   1 <!DOCTYPE html>
   2 <html xmlns="http://www.w3.org/1999/xhtml" lang="en">
   3 <head>
   4 <meta charset="UTF-8"/>
   5 <meta http-equiv="X-UA-Compatible" content="IE=edge"/>
   6 <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
   7 <meta name="generator" content="Asciidoctor 2.0.20"/>
   8 <title>gitworkflows(7)</title>
   9 <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"/>
  10 <style>
  11 /*! Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */
  12 /* Uncomment the following line when using as a custom stylesheet */
  13 /* @import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"; */
  14 html{font-family:sans-serif;-webkit-text-size-adjust:100%}
  15 a{background:none}
  16 a:focus{outline:thin dotted}
  17 a:active,a:hover{outline:0}
  18 h1{font-size:2em;margin:.67em 0}
  19 b,strong{font-weight:bold}
  20 abbr{font-size:.9em}
  21 abbr[title]{cursor:help;border-bottom:1px dotted #dddddf;text-decoration:none}
  22 dfn{font-style:italic}
  23 hr{height:0}
  24 mark{background:#ff0;color:#000}
  25 code,kbd,pre,samp{font-family:monospace;font-size:1em}
  26 pre{white-space:pre-wrap}
  27 q{quotes:"\201C" "\201D" "\2018" "\2019"}
  28 small{font-size:80%}
  29 sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
  30 sup{top:-.5em}
  31 sub{bottom:-.25em}
  32 img{border:0}
  33 svg:not(:root){overflow:hidden}
  34 figure{margin:0}
  35 audio,video{display:inline-block}
  36 audio:not([controls]){display:none;height:0}
  37 fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
  38 legend{border:0;padding:0}
  39 button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
  40 button,input{line-height:normal}
  41 button,select{text-transform:none}
  42 button,html input[type=button],input[type=reset],input[type=submit]{-webkit-appearance:button;cursor:pointer}
  43 button[disabled],html input[disabled]{cursor:default}
  44 input[type=checkbox],input[type=radio]{padding:0}
  45 button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
  46 textarea{overflow:auto;vertical-align:top}
  47 table{border-collapse:collapse;border-spacing:0}
  48 *,::before,::after{box-sizing:border-box}
  49 html,body{font-size:100%}
  50 body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;line-height:1;position:relative;cursor:auto;-moz-tab-size:4;-o-tab-size:4;tab-size:4;word-wrap:anywhere;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}
  51 a:hover{cursor:pointer}
  52 img,object,embed{max-width:100%;height:auto}
  53 object,embed{height:100%}
  54 img{-ms-interpolation-mode:bicubic}
  55 .left{float:left!important}
  56 .right{float:right!important}
  57 .text-left{text-align:left!important}
  58 .text-right{text-align:right!important}
  59 .text-center{text-align:center!important}
  60 .text-justify{text-align:justify!important}
  61 .hide{display:none}
  62 img,object,svg{display:inline-block;vertical-align:middle}
  63 textarea{height:auto;min-height:50px}
  64 select{width:100%}
  65 .subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}
  66 div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0}
  67 a{color:#2156a5;text-decoration:underline;line-height:inherit}
  68 a:hover,a:focus{color:#1d4b8f}
  69 a img{border:0}
  70 p{line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
  71 p aside{font-size:.875em;line-height:1.35;font-style:italic}
  72 h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}
  73 h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}
  74 h1{font-size:2.125em}
  75 h2{font-size:1.6875em}
  76 h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
  77 h4,h5{font-size:1.125em}
  78 h6{font-size:1em}
  79 hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em}
  80 em,i{font-style:italic;line-height:inherit}
  81 strong,b{font-weight:bold;line-height:inherit}
  82 small{font-size:60%;line-height:inherit}
  83 code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
  84 ul,ol,dl{line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
  85 ul,ol{margin-left:1.5em}
  86 ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0}
  87 ul.circle{list-style-type:circle}
  88 ul.disc{list-style-type:disc}
  89 ul.square{list-style-type:square}
  90 ul.circle ul:not([class]),ul.disc ul:not([class]),ul.square ul:not([class]){list-style:inherit}
  91 ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
  92 dl dt{margin-bottom:.3125em;font-weight:bold}
  93 dl dd{margin-bottom:1.25em}
  94 blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
  95 blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
  96 @media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
  97 h1{font-size:2.75em}
  98 h2{font-size:2.3125em}
  99 h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
 100 h4{font-size:1.4375em}}
 101 table{background:#fff;margin-bottom:1.25em;border:1px solid #dedede;word-wrap:normal}
 102 table thead,table tfoot{background:#f7f8f7}
 103 table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}
 104 table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
 105 table tr.even,table tr.alt{background:#f8f8f7}
 106 table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{line-height:1.6}
 107 h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
 108 h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
 109 .center{margin-left:auto;margin-right:auto}
 110 .stretch{width:100%}
 111 .clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table}
 112 .clearfix::after,.float-group::after{clear:both}
 113 :not(pre).nobreak{word-wrap:normal}
 114 :not(pre).nowrap{white-space:nowrap}
 115 :not(pre).pre-wrap{white-space:pre-wrap}
 116 :not(pre):not([class^=L])>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background:#f7f7f8;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed}
 117 pre{color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;line-height:1.45;text-rendering:optimizeSpeed}
 118 pre code,pre pre{color:inherit;font-size:inherit;line-height:inherit}
 119 pre>code{display:block}
 120 pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal}
 121 em em{font-style:normal}
 122 strong strong{font-weight:400}
 123 .keyseq{color:rgba(51,51,51,.8)}
 124 kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background:#f7f7f7;border:1px solid #ccc;border-radius:3px;box-shadow:0 1px 0 rgba(0,0,0,.2),inset 0 0 0 .1em #fff;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}
 125 .keyseq kbd:first-child{margin-left:0}
 126 .keyseq kbd:last-child{margin-right:0}
 127 .menuseq,.menuref{color:#000}
 128 .menuseq b:not(.caret),.menuref{font-weight:inherit}
 129 .menuseq{word-spacing:-.02em}
 130 .menuseq b.caret{font-size:1.25em;line-height:.8}
 131 .menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
 132 b.button::before,b.button::after{position:relative;top:-1px;font-weight:400}
 133 b.button::before{content:"[";padding:0 3px 0 2px}
 134 b.button::after{content:"]";padding:0 2px 0 3px}
 135 p a>code:hover{color:rgba(0,0,0,.9)}
 136 #header,#content,#footnotes,#footer{width:100%;margin:0 auto;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
 137 #header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table}
 138 #header::after,#content::after,#footnotes::after,#footer::after{clear:both}
 139 #content{margin-top:1.25em}
 140 #content::before{content:none}
 141 #header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
 142 #header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}
 143 #header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
 144 #header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:flex;flex-flow:row wrap}
 145 #header .details span:first-child{margin-left:-.125em}
 146 #header .details span.email a{color:rgba(0,0,0,.85)}
 147 #header .details br{display:none}
 148 #header .details br+span::before{content:"\00a0\2013\00a0"}
 149 #header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
 150 #header .details br+span#revremark::before{content:"\00a0|\00a0"}
 151 #header #revnumber{text-transform:capitalize}
 152 #header #revnumber::after{content:"\00a0"}
 153 #content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}
 154 #toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em}
 155 #toc>ul{margin-left:.125em}
 156 #toc ul.sectlevel0>li>a{font-style:italic}
 157 #toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
 158 #toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
 159 #toc li{line-height:1.3334;margin-top:.3334em}
 160 #toc a{text-decoration:none}
 161 #toc a:active{text-decoration:underline}
 162 #toctitle{color:#7a2518;font-size:1.2em}
 163 @media screen and (min-width:768px){#toctitle{font-size:1.375em}
 164 body.toc2{padding-left:15em;padding-right:0}
 165 #toc.toc2{margin-top:0!important;background:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
 166 #toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
 167 #toc.toc2>ul{font-size:.9em;margin-bottom:0}
 168 #toc.toc2 ul ul{margin-left:0;padding-left:1em}
 169 #toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
 170 body.toc2.toc-right{padding-left:0;padding-right:15em}
 171 body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}
 172 @media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
 173 #toc.toc2{width:20em}
 174 #toc.toc2 #toctitle{font-size:1.375em}
 175 #toc.toc2>ul{font-size:.95em}
 176 #toc.toc2 ul ul{padding-left:1.25em}
 177 body.toc2.toc-right{padding-left:0;padding-right:20em}}
 178 #content #toc{border:1px solid #e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;border-radius:4px}
 179 #content #toc>:first-child{margin-top:0}
 180 #content #toc>:last-child{margin-bottom:0}
 181 #footer{max-width:none;background:rgba(0,0,0,.8);padding:1.25em}
 182 #footer-text{color:hsla(0,0%,100%,.8);line-height:1.44}
 183 #content{margin-bottom:.625em}
 184 .sect1{padding-bottom:.625em}
 185 @media screen and (min-width:768px){#content{margin-bottom:1.25em}
 186 .sect1{padding-bottom:1.25em}}
 187 .sect1:last-child{padding-bottom:0}
 188 .sect1+.sect1{border-top:1px solid #e7e7e9}
 189 #content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}
 190 #content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}
 191 #content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}
 192 #content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}
 193 #content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}
 194 details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
 195 details{margin-left:1.25rem}
 196 details>summary{cursor:pointer;display:block;position:relative;line-height:1.6;margin-bottom:.625rem;outline:none;-webkit-tap-highlight-color:transparent}
 197 details>summary::-webkit-details-marker{display:none}
 198 details>summary::before{content:"";border:solid transparent;border-left:solid;border-width:.3em 0 .3em .5em;position:absolute;top:.5em;left:-1.25rem;transform:translateX(15%)}
 199 details[open]>summary::before{border:solid transparent;border-top:solid;border-width:.5em .3em 0;transform:translateY(15%)}
 200 details>summary::after{content:"";width:1.25rem;height:1em;position:absolute;top:.3em;left:-1.25rem}
 201 .admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}
 202 table.tableblock.fit-content>caption.title{white-space:nowrap;width:0}
 203 .paragraph.lead>p,#preamble>.sectionbody>[class=paragraph]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)}
 204 .admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
 205 .admonitionblock>table td.icon{text-align:center;width:80px}
 206 .admonitionblock>table td.icon img{max-width:none}
 207 .admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
 208 .admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6);word-wrap:anywhere}
 209 .admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
 210 .exampleblock>.content{border:1px solid #e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;border-radius:4px}
 211 .sidebarblock{border:1px solid #dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;border-radius:4px}
 212 .sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
 213 .exampleblock>.content>:first-child,.sidebarblock>.content>:first-child{margin-top:0}
 214 .exampleblock>.content>:last-child,.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
 215 .literalblock pre,.listingblock>.content>pre{border-radius:4px;overflow-x:auto;padding:1em;font-size:.8125em}
 216 @media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}}
 217 @media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}}
 218 .literalblock pre,.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class=highlight],.listingblock>.content>pre[class^="highlight "]{background:#f7f7f8}
 219 .literalblock.output pre{color:#f7f7f8;background:rgba(0,0,0,.9)}
 220 .listingblock>.content{position:relative}
 221 .listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:inherit;opacity:.5}
 222 .listingblock:hover code[data-lang]::before{display:block}
 223 .listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:inherit;opacity:.5}
 224 .listingblock.terminal pre .command:not([data-prompt])::before{content:"$"}
 225 .listingblock pre.highlightjs{padding:0}
 226 .listingblock pre.highlightjs>code{padding:1em;border-radius:4px}
 227 .listingblock pre.prettyprint{border-width:0}
 228 .prettyprint{background:#f7f7f8}
 229 pre.prettyprint .linenums{line-height:1.45;margin-left:2em}
 230 pre.prettyprint li{background:none;list-style-type:inherit;padding-left:0}
 231 pre.prettyprint li code[data-lang]::before{opacity:1}
 232 pre.prettyprint li:not(:first-child) code[data-lang]::before{display:none}
 233 table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none}
 234 table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal}
 235 table.linenotable td.code{padding-left:.75em}
 236 table.linenotable td.linenos,pre.pygments .linenos{border-right:1px solid;opacity:.35;padding-right:.5em;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}
 237 pre.pygments span.linenos{display:inline-block;margin-right:.75em}
 238 .quoteblock{margin:0 1em 1.25em 1.5em;display:table}
 239 .quoteblock:not(.excerpt)>.title{margin-left:-1.5em;margin-bottom:.75em}
 240 .quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}
 241 .quoteblock blockquote{margin:0;padding:0;border:0}
 242 .quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}
 243 .quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
 244 .quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right}
 245 .verseblock{margin:0 1em 1.25em}
 246 .verseblock pre{font-family:"Open Sans","DejaVu Sans",sans-serif;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}
 247 .verseblock pre strong{font-weight:400}
 248 .verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
 249 .quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
 250 .quoteblock .attribution br,.verseblock .attribution br{display:none}
 251 .quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}
 252 .quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none}
 253 .quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0}
 254 .quoteblock.abstract{margin:0 1em 1.25em;display:block}
 255 .quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center}
 256 .quoteblock.excerpt>blockquote,.quoteblock .quoteblock{padding:0 0 .25em 1em;border-left:.25em solid #dddddf}
 257 .quoteblock.excerpt,.quoteblock .quoteblock{margin-left:0}
 258 .quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem}
 259 .quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;font-size:.85rem;text-align:left;margin-right:0}
 260 p.tableblock:last-child{margin-bottom:0}
 261 td.tableblock>.content{margin-bottom:1.25em;word-wrap:anywhere}
 262 td.tableblock>.content>:last-child{margin-bottom:-1.25em}
 263 table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
 264 table.grid-all>*>tr>*{border-width:1px}
 265 table.grid-cols>*>tr>*{border-width:0 1px}
 266 table.grid-rows>*>tr>*{border-width:1px 0}
 267 table.frame-all{border-width:1px}
 268 table.frame-ends{border-width:1px 0}
 269 table.frame-sides{border-width:0 1px}
 270 table.frame-none>colgroup+*>:first-child>*,table.frame-sides>colgroup+*>:first-child>*{border-top-width:0}
 271 table.frame-none>:last-child>:last-child>*,table.frame-sides>:last-child>:last-child>*{border-bottom-width:0}
 272 table.frame-none>*>tr>:first-child,table.frame-ends>*>tr>:first-child{border-left-width:0}
 273 table.frame-none>*>tr>:last-child,table.frame-ends>*>tr>:last-child{border-right-width:0}
 274 table.stripes-all>*>tr,table.stripes-odd>*>tr:nth-of-type(odd),table.stripes-even>*>tr:nth-of-type(even),table.stripes-hover>*>tr:hover{background:#f8f8f7}
 275 th.halign-left,td.halign-left{text-align:left}
 276 th.halign-right,td.halign-right{text-align:right}
 277 th.halign-center,td.halign-center{text-align:center}
 278 th.valign-top,td.valign-top{vertical-align:top}
 279 th.valign-bottom,td.valign-bottom{vertical-align:bottom}
 280 th.valign-middle,td.valign-middle{vertical-align:middle}
 281 table thead th,table tfoot th{font-weight:bold}
 282 tbody tr th{background:#f7f8f7}
 283 tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
 284 p.tableblock>code:only-child{background:none;padding:0}
 285 p.tableblock{font-size:1em}
 286 ol{margin-left:1.75em}
 287 ul li ol{margin-left:1.5em}
 288 dl dd{margin-left:1.125em}
 289 dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
 290 li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
 291 ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}
 292 ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}
 293 ul.unstyled,ol.unstyled{margin-left:0}
 294 li>p:empty:only-child::before{content:"";display:inline-block}
 295 ul.checklist>li>p:first-child{margin-left:-1em}
 296 ul.checklist>li>p:first-child>.fa-square-o:first-child,ul.checklist>li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em}
 297 ul.checklist>li>p:first-child>input[type=checkbox]:first-child{margin-right:.25em}
 298 ul.inline{display:flex;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em}
 299 ul.inline>li{margin-left:1.25em}
 300 .unstyled dl dt{font-weight:400;font-style:normal}
 301 ol.arabic{list-style-type:decimal}
 302 ol.decimal{list-style-type:decimal-leading-zero}
 303 ol.loweralpha{list-style-type:lower-alpha}
 304 ol.upperalpha{list-style-type:upper-alpha}
 305 ol.lowerroman{list-style-type:lower-roman}
 306 ol.upperroman{list-style-type:upper-roman}
 307 ol.lowergreek{list-style-type:lower-greek}
 308 .hdlist>table,.colist>table{border:0;background:none}
 309 .hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
 310 td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
 311 td.hdlist1{font-weight:bold;padding-bottom:1.25em}
 312 td.hdlist2{word-wrap:anywhere}
 313 .literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
 314 .colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top}
 315 .colist td:not([class]):first-child img{max-width:none}
 316 .colist td:not([class]):last-child{padding:.25em 0}
 317 .thumb,.th{line-height:0;display:inline-block;border:4px solid #fff;box-shadow:0 0 0 1px #ddd}
 318 .imageblock.left{margin:.25em .625em 1.25em 0}
 319 .imageblock.right{margin:.25em 0 1.25em .625em}
 320 .imageblock>.title{margin-bottom:0}
 321 .imageblock.thumb,.imageblock.th{border-width:6px}
 322 .imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
 323 .image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
 324 .image.left{margin-right:.625em}
 325 .image.right{margin-left:.625em}
 326 a.image{text-decoration:none;display:inline-block}
 327 a.image object{pointer-events:none}
 328 sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
 329 sup.footnote a,sup.footnoteref a{text-decoration:none}
 330 sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline}
 331 #footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
 332 #footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}
 333 #footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}
 334 #footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em}
 335 #footnotes .footnote:last-of-type{margin-bottom:0}
 336 #content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
 337 div.unbreakable{page-break-inside:avoid}
 338 .big{font-size:larger}
 339 .small{font-size:smaller}
 340 .underline{text-decoration:underline}
 341 .overline{text-decoration:overline}
 342 .line-through{text-decoration:line-through}
 343 .aqua{color:#00bfbf}
 344 .aqua-background{background:#00fafa}
 345 .black{color:#000}
 346 .black-background{background:#000}
 347 .blue{color:#0000bf}
 348 .blue-background{background:#0000fa}
 349 .fuchsia{color:#bf00bf}
 350 .fuchsia-background{background:#fa00fa}
 351 .gray{color:#606060}
 352 .gray-background{background:#7d7d7d}
 353 .green{color:#006000}
 354 .green-background{background:#007d00}
 355 .lime{color:#00bf00}
 356 .lime-background{background:#00fa00}
 357 .maroon{color:#600000}
 358 .maroon-background{background:#7d0000}
 359 .navy{color:#000060}
 360 .navy-background{background:#00007d}
 361 .olive{color:#606000}
 362 .olive-background{background:#7d7d00}
 363 .purple{color:#600060}
 364 .purple-background{background:#7d007d}
 365 .red{color:#bf0000}
 366 .red-background{background:#fa0000}
 367 .silver{color:#909090}
 368 .silver-background{background:#bcbcbc}
 369 .teal{color:#006060}
 370 .teal-background{background:#007d7d}
 371 .white{color:#bfbfbf}
 372 .white-background{background:#fafafa}
 373 .yellow{color:#bfbf00}
 374 .yellow-background{background:#fafa00}
 375 span.icon>.fa{cursor:default}
 376 a span.icon>.fa{cursor:inherit}
 377 .admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
 378 .admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c}
 379 .admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
 380 .admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900}
 381 .admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400}
 382 .admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000}
 383 .conum[data-value]{display:inline-block;color:#fff!important;background:rgba(0,0,0,.8);border-radius:50%;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
 384 .conum[data-value] *{color:#fff!important}
 385 .conum[data-value]+b{display:none}
 386 .conum[data-value]::after{content:attr(data-value)}
 387 pre .conum[data-value]{position:relative;top:-.125em}
 388 b.conum *{color:inherit!important}
 389 .conum:not([data-value]):empty{display:none}
 390 dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}
 391 h1,h2,p,td.content,span.alt,summary{letter-spacing:-.01em}
 392 p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}
 393 p,blockquote,dt,td.content,td.hdlist1,span.alt,summary{font-size:1.0625rem}
 394 p{margin-bottom:1.25rem}
 395 .sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
 396 .exampleblock>.content{background:#fffef7;border-color:#e0e0dc;box-shadow:0 1px 4px #e0e0dc}
 397 .print-only{display:none!important}
 398 @page{margin:1.25cm .75cm}
 399 @media print{*{box-shadow:none!important;text-shadow:none!important}
 400 html{font-size:80%}
 401 a{color:inherit!important;text-decoration:underline!important}
 402 a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
 403 a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
 404 abbr[title]{border-bottom:1px dotted}
 405 abbr[title]::after{content:" (" attr(title) ")"}
 406 pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
 407 thead{display:table-header-group}
 408 svg{max-width:100%}
 409 p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
 410 h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
 411 #header,#content,#footnotes,#footer{max-width:none}
 412 #toc,.sidebarblock,.exampleblock>.content{background:none!important}
 413 #toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important}
 414 body.book #header{text-align:center}
 415 body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em}
 416 body.book #header .details{border:0!important;display:block;padding:0!important}
 417 body.book #header .details span:first-child{margin-left:0!important}
 418 body.book #header .details br{display:block}
 419 body.book #header .details br+span::before{content:none!important}
 420 body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
 421 body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
 422 .listingblock code[data-lang]::before{display:block}
 423 #footer{padding:0 .9375em}
 424 .hide-on-print{display:none!important}
 425 .print-only{display:block!important}
 426 .hide-for-print{display:none!important}
 427 .show-for-print{display:inherit!important}}
 428 @media amzn-kf8,print{#header>h1:first-child{margin-top:1.25rem}
 429 .sect1{padding:0!important}
 430 .sect1+.sect1{border:0}
 431 #footer{background:none}
 432 #footer-text{color:rgba(0,0,0,.6);font-size:.9em}}
 433 @media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}}
 434 </style>
 435 <style>
 436 pre>code {
 437    display: inline;
 438 }
 439 </style>
 440 </head>
 441 <body class="manpage">
 442 <div id="header">
 443 <h1>gitworkflows(7) Manual Page</h1>
 444 <h2 id="_name">NAME</h2>
 445 <div class="sectionbody">
 446 <p>gitworkflows - An overview of recommended workflows with Git</p>
 447 </div>
 448 </div>
 449 <div id="content">
 450 <div class="sect1">
 451 <h2 id="_synopsis">SYNOPSIS</h2>
 452 <div class="sectionbody">
 453 <div class="verseblock">
 454 <pre class="content">git *</pre>
 455 </div>
 456 </div>
 457 </div>
 458 <div class="sect1">
 459 <h2 id="_description">DESCRIPTION</h2>
 460 <div class="sectionbody">
 461 <div class="paragraph">
 462 <p>This document attempts to write down and motivate some of the workflow
 463 elements used for <code>git.git</code> itself.  Many ideas apply in general,
 464 though the full workflow is rarely required for smaller projects with
 465 fewer people involved.</p>
 466 </div>
 467 <div class="paragraph">
 468 <p>We formulate a set of <em>rules</em> for quick reference, while the prose
 469 tries to motivate each of them.  Do not always take them literally;
 470 you should value good reasons for your actions higher than manpages
 471 such as this one.</p>
 472 </div>
 473 </div>
 474 </div>
 475 <div class="sect1">
 476 <h2 id="_separate_changes">SEPARATE CHANGES</h2>
 477 <div class="sectionbody">
 478 <div class="paragraph">
 479 <p>As a general rule, you should try to split your changes into small
 480 logical steps, and commit each of them.  They should be consistent,
 481 working independently of any later commits, pass the test suite, etc.
 482 This makes the review process much easier, and the history much more
 483 useful for later inspection and analysis, for example with
 484 <a href="git-blame.html">git-blame(1)</a> and <a href="git-bisect.html">git-bisect(1)</a>.</p>
 485 </div>
 486 <div class="paragraph">
 487 <p>To achieve this, try to split your work into small steps from the very
 488 beginning. It is always easier to squash a few commits together than
 489 to split one big commit into several.  Don&#8217;t be afraid of making too
 490 small or imperfect steps along the way. You can always go back later
 491 and edit the commits with <code>git rebase --interactive</code> before you
 492 publish them.  You can use <code>git stash push --keep-index</code> to run the
 493 test suite independent of other uncommitted changes; see the EXAMPLES
 494 section of <a href="git-stash.html">git-stash(1)</a>.</p>
 495 </div>
 496 </div>
 497 </div>
 498 <div class="sect1">
 499 <h2 id="_managing_branches">MANAGING BRANCHES</h2>
 500 <div class="sectionbody">
 501 <div class="paragraph">
 502 <p>There are two main tools that can be used to include changes from one
 503 branch on another: <a href="git-merge.html">git-merge(1)</a> and
 504 <a href="git-cherry-pick.html">git-cherry-pick(1)</a>.</p>
 505 </div>
 506 <div class="paragraph">
 507 <p>Merges have many advantages, so we try to solve as many problems as
 508 possible with merges alone.  Cherry-picking is still occasionally
 509 useful; see "Merging upwards" below for an example.</p>
 510 </div>
 511 <div class="paragraph">
 512 <p>Most importantly, merging works at the branch level, while
 513 cherry-picking works at the commit level.  This means that a merge can
 514 carry over the changes from 1, 10, or 1000 commits with equal ease,
 515 which in turn means the workflow scales much better to a large number
 516 of contributors (and contributions).  Merges are also easier to
 517 understand because a merge commit is a "promise" that all changes from
 518 all its parents are now included.</p>
 519 </div>
 520 <div class="paragraph">
 521 <p>There is a tradeoff of course: merges require a more careful branch
 522 management.  The following subsections discuss the important points.</p>
 523 </div>
 524 <div class="sect2">
 525 <h3 id="_graduation">Graduation</h3>
 526 <div class="paragraph">
 527 <p>As a given feature goes from experimental to stable, it also
 528 "graduates" between the corresponding branches of the software.
 529 <code>git.git</code> uses the following <em>integration branches</em>:</p>
 530 </div>
 531 <div class="ulist">
 532 <ul>
 533 <li>
 534 <p><em>maint</em> tracks the commits that should go into the next "maintenance
 535 release", i.e., update of the last released stable version;</p>
 536 </li>
 537 <li>
 538 <p><em>master</em> tracks the commits that should go into the next release;</p>
 539 </li>
 540 <li>
 541 <p><em>next</em> is intended as a testing branch for topics being tested for
 542 stability for master.</p>
 543 </li>
 544 </ul>
 545 </div>
 546 <div class="paragraph">
 547 <p>There is a fourth official branch that is used slightly differently:</p>
 548 </div>
 549 <div class="ulist">
 550 <ul>
 551 <li>
 552 <p><em>seen</em> (patches seen by the maintainer) is an integration branch for
 553 things that are not quite ready for inclusion yet (see "Integration
 554 Branches" below).</p>
 555 </li>
 556 </ul>
 557 </div>
 558 <div class="paragraph">
 559 <p>Each of the four branches is usually a direct descendant of the one
 560 above it.</p>
 561 </div>
 562 <div class="paragraph">
 563 <p>Conceptually, the feature enters at an unstable branch (usually <em>next</em>
 564 or <em>seen</em>), and "graduates" to <em>master</em> for the next release once it is
 565 considered stable enough.</p>
 566 </div>
 567 </div>
 568 <div class="sect2">
 569 <h3 id="_merging_upwards">Merging upwards</h3>
 570 <div class="paragraph">
 571 <p>The "downwards graduation" discussed above cannot be done by actually
 572 merging downwards, however, since that would merge <em>all</em> changes on
 573 the unstable branch into the stable one.  Hence the following:</p>
 574 </div>
 575 <div class="exampleblock">
 576 <div class="title">Rule: Merge upwards</div>
 577 <div class="content">
 578 <div class="paragraph">
 579 <p>Always commit your fixes to the oldest supported branch that requires
 580 them.  Then (periodically) merge the integration branches upwards into each
 581 other.</p>
 582 </div>
 583 </div>
 584 </div>
 585 <div class="paragraph">
 586 <p>This gives a very controlled flow of fixes.  If you notice that you
 587 have applied a fix to e.g. <em>master</em> that is also required in <em>maint</em>,
 588 you will need to cherry-pick it (using <a href="git-cherry-pick.html">git-cherry-pick(1)</a>)
 589 downwards.  This will happen a few times and is nothing to worry about
 590 unless you do it very frequently.</p>
 591 </div>
 592 </div>
 593 <div class="sect2">
 594 <h3 id="_topic_branches">Topic branches</h3>
 595 <div class="paragraph">
 596 <p>Any nontrivial feature will require several patches to implement, and
 597 may get extra bugfixes or improvements during its lifetime.</p>
 598 </div>
 599 <div class="paragraph">
 600 <p>Committing everything directly on the integration branches leads to many
 601 problems: Bad commits cannot be undone, so they must be reverted one
 602 by one, which creates confusing histories and further error potential
 603 when you forget to revert part of a group of changes.  Working in
 604 parallel mixes up the changes, creating further confusion.</p>
 605 </div>
 606 <div class="paragraph">
 607 <p>Use of "topic branches" solves these problems.  The name is pretty
 608 self explanatory, with a caveat that comes from the "merge upwards"
 609 rule above:</p>
 610 </div>
 611 <div class="exampleblock">
 612 <div class="title">Rule: Topic branches</div>
 613 <div class="content">
 614 <div class="paragraph">
 615 <p>Make a side branch for every topic (feature, bugfix, &#8230;&#8203;). Fork it off
 616 at the oldest integration branch that you will eventually want to merge it
 617 into.</p>
 618 </div>
 619 </div>
 620 </div>
 621 <div class="paragraph">
 622 <p>Many things can then be done very naturally:</p>
 623 </div>
 624 <div class="ulist">
 625 <ul>
 626 <li>
 627 <p>To get the feature/bugfix into an integration branch, simply merge
 628 it.  If the topic has evolved further in the meantime, merge again.
 629 (Note that you do not necessarily have to merge it to the oldest
 630 integration branch first.  For example, you can first merge a bugfix
 631 to <em>next</em>, give it some testing time, and merge to <em>maint</em> when you
 632 know it is stable.)</p>
 633 </li>
 634 <li>
 635 <p>If you find you need new features from the branch <em>other</em> to continue
 636 working on your topic, merge <em>other</em> to <em>topic</em>.  (However, do not
 637 do this "just habitually", see below.)</p>
 638 </li>
 639 <li>
 640 <p>If you find you forked off the wrong branch and want to move it
 641 "back in time", use <a href="git-rebase.html">git-rebase(1)</a>.</p>
 642 </li>
 643 </ul>
 644 </div>
 645 <div class="paragraph">
 646 <p>Note that the last point clashes with the other two: a topic that has
 647 been merged elsewhere should not be rebased.  See the section on
 648 RECOVERING FROM UPSTREAM REBASE in <a href="git-rebase.html">git-rebase(1)</a>.</p>
 649 </div>
 650 <div class="paragraph">
 651 <p>We should point out that "habitually" (regularly for no real reason)
 652 merging an integration branch into your topics&#8201;&#8212;&#8201;and by extension,
 653 merging anything upstream into anything downstream on a regular basis&#8201;&#8212;&#8201;is frowned upon:</p>
 654 </div>
 655 <div class="exampleblock">
 656 <div class="title">Rule: Merge to downstream only at well-defined points</div>
 657 <div class="content">
 658 <div class="paragraph">
 659 <p>Do not merge to downstream except with a good reason: upstream API
 660 changes affect your branch; your branch no longer merges to upstream
 661 cleanly; etc.</p>
 662 </div>
 663 </div>
 664 </div>
 665 <div class="paragraph">
 666 <p>Otherwise, the topic that was merged to suddenly contains more than a
 667 single (well-separated) change.  The many resulting small merges will
 668 greatly clutter up history.  Anyone who later investigates the history
 669 of a file will have to find out whether that merge affected the topic
 670 in development.  An upstream might even inadvertently be merged into a
 671 "more stable" branch.  And so on.</p>
 672 </div>
 673 </div>
 674 <div class="sect2">
 675 <h3 id="_throw_away_integration">Throw-away integration</h3>
 676 <div class="paragraph">
 677 <p>If you followed the last paragraph, you will now have many small topic
 678 branches, and occasionally wonder how they interact.  Perhaps the
 679 result of merging them does not even work?  But on the other hand, we
 680 want to avoid merging them anywhere "stable" because such merges
 681 cannot easily be undone.</p>
 682 </div>
 683 <div class="paragraph">
 684 <p>The solution, of course, is to make a merge that we can undo: merge
 685 into a throw-away branch.</p>
 686 </div>
 687 <div class="exampleblock">
 688 <div class="title">Rule: Throw-away integration branches</div>
 689 <div class="content">
 690 <div class="paragraph">
 691 <p>To test the interaction of several topics, merge them into a
 692 throw-away branch.  You must never base any work on such a branch!</p>
 693 </div>
 694 </div>
 695 </div>
 696 <div class="paragraph">
 697 <p>If you make it (very) clear that this branch is going to be deleted
 698 right after the testing, you can even publish this branch, for example
 699 to give the testers a chance to work with it, or other developers a
 700 chance to see if their in-progress work will be compatible.  <code>git.git</code>
 701 has such an official throw-away integration branch called <em>seen</em>.</p>
 702 </div>
 703 </div>
 704 <div class="sect2">
 705 <h3 id="_branch_management_for_a_release">Branch management for a release</h3>
 706 <div class="paragraph">
 707 <p>Assuming you are using the merge approach discussed above, when you
 708 are releasing your project you will need to do some additional branch
 709 management work.</p>
 710 </div>
 711 <div class="paragraph">
 712 <p>A feature release is created from the <em>master</em> branch, since <em>master</em>
 713 tracks the commits that should go into the next feature release.</p>
 714 </div>
 715 <div class="paragraph">
 716 <p>The <em>master</em> branch is supposed to be a superset of <em>maint</em>. If this
 717 condition does not hold, then <em>maint</em> contains some commits that
 718 are not included on <em>master</em>. The fixes represented by those commits
 719 will therefore not be included in your feature release.</p>
 720 </div>
 721 <div class="paragraph">
 722 <p>To verify that <em>master</em> is indeed a superset of <em>maint</em>, use git log:</p>
 723 </div>
 724 <div class="exampleblock">
 725 <div class="title">Recipe: Verify <em>master</em> is a superset of <em>maint</em></div>
 726 <div class="content">
 727 <div class="paragraph">
 728 <p><code>git log master..maint</code></p>
 729 </div>
 730 </div>
 731 </div>
 732 <div class="paragraph">
 733 <p>This command should not list any commits.  Otherwise, check out
 734 <em>master</em> and merge <em>maint</em> into it.</p>
 735 </div>
 736 <div class="paragraph">
 737 <p>Now you can proceed with the creation of the feature release. Apply a
 738 tag to the tip of <em>master</em> indicating the release version:</p>
 739 </div>
 740 <div class="exampleblock">
 741 <div class="title">Recipe: Release tagging</div>
 742 <div class="content">
 743 <div class="paragraph">
 744 <p><code>git tag -s -m "Git X.Y.Z" vX.Y.Z master</code></p>
 745 </div>
 746 </div>
 747 </div>
 748 <div class="paragraph">
 749 <p>You need to push the new tag to a public Git server (see
 750 "DISTRIBUTED WORKFLOWS" below). This makes the tag available to
 751 others tracking your project. The push could also trigger a
 752 post-update hook to perform release-related items such as building
 753 release tarballs and preformatted documentation pages.</p>
 754 </div>
 755 <div class="paragraph">
 756 <p>Similarly, for a maintenance release, <em>maint</em> is tracking the commits
 757 to be released. Therefore, in the steps above simply tag and push
 758 <em>maint</em> rather than <em>master</em>.</p>
 759 </div>
 760 </div>
 761 <div class="sect2">
 762 <h3 id="_maintenance_branch_management_after_a_feature_release">Maintenance branch management after a feature release</h3>
 763 <div class="paragraph">
 764 <p>After a feature release, you need to manage your maintenance branches.</p>
 765 </div>
 766 <div class="paragraph">
 767 <p>First, if you wish to continue to release maintenance fixes for the
 768 feature release made before the recent one, then you must create
 769 another branch to track commits for that previous release.</p>
 770 </div>
 771 <div class="paragraph">
 772 <p>To do this, the current maintenance branch is copied to another branch
 773 named with the previous release version number (e.g. maint-X.Y.(Z-1)
 774 where X.Y.Z is the current release).</p>
 775 </div>
 776 <div class="exampleblock">
 777 <div class="title">Recipe: Copy maint</div>
 778 <div class="content">
 779 <div class="paragraph">
 780 <p><code>git branch maint-X.Y.(Z-1) maint</code></p>
 781 </div>
 782 </div>
 783 </div>
 784 <div class="paragraph">
 785 <p>The <em>maint</em> branch should now be fast-forwarded to the newly released
 786 code so that maintenance fixes can be tracked for the current release:</p>
 787 </div>
 788 <div class="exampleblock">
 789 <div class="title">Recipe: Update maint to new release</div>
 790 <div class="content">
 791 <div class="ulist">
 792 <ul>
 793 <li>
 794 <p><code>git checkout maint</code></p>
 795 </li>
 796 <li>
 797 <p><code>git merge --ff-only master</code></p>
 798 </li>
 799 </ul>
 800 </div>
 801 </div>
 802 </div>
 803 <div class="paragraph">
 804 <p>If the merge fails because it is not a fast-forward, then it is
 805 possible some fixes on <em>maint</em> were missed in the feature release.
 806 This will not happen if the content of the branches was verified as
 807 described in the previous section.</p>
 808 </div>
 809 </div>
 810 <div class="sect2">
 811 <h3 id="_branch_management_for_next_and_seen_after_a_feature_release">Branch management for next and seen after a feature release</h3>
 812 <div class="paragraph">
 813 <p>After a feature release, the integration branch <em>next</em> may optionally be
 814 rewound and rebuilt from the tip of <em>master</em> using the surviving
 815 topics on <em>next</em>:</p>
 816 </div>
 817 <div class="exampleblock">
 818 <div class="title">Recipe: Rewind and rebuild next</div>
 819 <div class="content">
 820 <div class="ulist">
 821 <ul>
 822 <li>
 823 <p><code>git switch -C next master</code></p>
 824 </li>
 825 <li>
 826 <p><code>git merge ai/topic_in_next1</code></p>
 827 </li>
 828 <li>
 829 <p><code>git merge ai/topic_in_next2</code></p>
 830 </li>
 831 <li>
 832 <p>&#8230;&#8203;</p>
 833 </li>
 834 </ul>
 835 </div>
 836 </div>
 837 </div>
 838 <div class="paragraph">
 839 <p>The advantage of doing this is that the history of <em>next</em> will be
 840 clean. For example, some topics merged into <em>next</em> may have initially
 841 looked promising, but were later found to be undesirable or premature.
 842 In such a case, the topic is reverted out of <em>next</em> but the fact
 843 remains in the history that it was once merged and reverted. By
 844 recreating <em>next</em>, you give another incarnation of such topics a clean
 845 slate to retry, and a feature release is a good point in history to do
 846 so.</p>
 847 </div>
 848 <div class="paragraph">
 849 <p>If you do this, then you should make a public announcement indicating
 850 that <em>next</em> was rewound and rebuilt.</p>
 851 </div>
 852 <div class="paragraph">
 853 <p>The same rewind and rebuild process may be followed for <em>seen</em>. A public
 854 announcement is not necessary since <em>seen</em> is a throw-away branch, as
 855 described above.</p>
 856 </div>
 857 </div>
 858 </div>
 859 </div>
 860 <div class="sect1">
 861 <h2 id="_distributed_workflows">DISTRIBUTED WORKFLOWS</h2>
 862 <div class="sectionbody">
 863 <div class="paragraph">
 864 <p>After the last section, you should know how to manage topics.  In
 865 general, you will not be the only person working on the project, so
 866 you will have to share your work.</p>
 867 </div>
 868 <div class="paragraph">
 869 <p>Roughly speaking, there are two important workflows: merge and patch.
 870 The important difference is that the merge workflow can propagate full
 871 history, including merges, while patches cannot.  Both workflows can
 872 be used in parallel: in <code>git.git</code>, only subsystem maintainers use
 873 the merge workflow, while everyone else sends patches.</p>
 874 </div>
 875 <div class="paragraph">
 876 <p>Note that the maintainer(s) may impose restrictions, such as
 877 "Signed-off-by" requirements, that all commits/patches submitted for
 878 inclusion must adhere to.  Consult your project&#8217;s documentation for
 879 more information.</p>
 880 </div>
 881 <div class="sect2">
 882 <h3 id="_merge_workflow">Merge workflow</h3>
 883 <div class="paragraph">
 884 <p>The merge workflow works by copying branches between upstream and
 885 downstream.  Upstream can merge contributions into the official
 886 history; downstream base their work on the official history.</p>
 887 </div>
 888 <div class="paragraph">
 889 <p>There are three main tools that can be used for this:</p>
 890 </div>
 891 <div class="ulist">
 892 <ul>
 893 <li>
 894 <p><a href="git-push.html">git-push(1)</a> copies your branches to a remote repository,
 895 usually to one that can be read by all involved parties;</p>
 896 </li>
 897 <li>
 898 <p><a href="git-fetch.html">git-fetch(1)</a> that copies remote branches to your repository;
 899 and</p>
 900 </li>
 901 <li>
 902 <p><a href="git-pull.html">git-pull(1)</a> that does fetch and merge in one go.</p>
 903 </li>
 904 </ul>
 905 </div>
 906 <div class="paragraph">
 907 <p>Note the last point.  Do <em>not</em> use <em>git pull</em> unless you actually want
 908 to merge the remote branch.</p>
 909 </div>
 910 <div class="paragraph">
 911 <p>Getting changes out is easy:</p>
 912 </div>
 913 <div class="exampleblock">
 914 <div class="title">Recipe: Push/pull: Publishing branches/topics</div>
 915 <div class="content">
 916 <div class="paragraph">
 917 <p><code>git push &lt;remote&gt; &lt;branch&gt;</code> and tell everyone where they can fetch
 918 from.</p>
 919 </div>
 920 </div>
 921 </div>
 922 <div class="paragraph">
 923 <p>You will still have to tell people by other means, such as mail.  (Git
 924 provides the <a href="git-request-pull.html">git-request-pull(1)</a> to send preformatted pull
 925 requests to upstream maintainers to simplify this task.)</p>
 926 </div>
 927 <div class="paragraph">
 928 <p>If you just want to get the newest copies of the integration branches,
 929 staying up to date is easy too:</p>
 930 </div>
 931 <div class="exampleblock">
 932 <div class="title">Recipe: Push/pull: Staying up to date</div>
 933 <div class="content">
 934 <div class="paragraph">
 935 <p>Use <code>git fetch &lt;remote&gt;</code> or <code>git remote update</code> to stay up to date.</p>
 936 </div>
 937 </div>
 938 </div>
 939 <div class="paragraph">
 940 <p>Then simply fork your topic branches from the stable remotes as
 941 explained earlier.</p>
 942 </div>
 943 <div class="paragraph">
 944 <p>If you are a maintainer and would like to merge other people&#8217;s topic
 945 branches to the integration branches, they will typically send a
 946 request to do so by mail.  Such a request looks like</p>
 947 </div>
 948 <div class="listingblock">
 949 <div class="content">
 950 <pre>Please pull from
 951     &lt;URL&gt; &lt;branch&gt;</pre>
 952 </div>
 953 </div>
 954 <div class="paragraph">
 955 <p>In that case, <em>git pull</em> can do the fetch and merge in one go, as
 956 follows.</p>
 957 </div>
 958 <div class="exampleblock">
 959 <div class="title">Recipe: Push/pull: Merging remote topics</div>
 960 <div class="content">
 961 <div class="paragraph">
 962 <p><code>git pull &lt;URL&gt; &lt;branch&gt;</code></p>
 963 </div>
 964 </div>
 965 </div>
 966 <div class="paragraph">
 967 <p>Occasionally, the maintainer may get merge conflicts when they try to
 968 pull changes from downstream.  In this case, they can ask downstream to
 969 do the merge and resolve the conflicts themselves (perhaps they will
 970 know better how to resolve them).  It is one of the rare cases where
 971 downstream <em>should</em> merge from upstream.</p>
 972 </div>
 973 </div>
 974 <div class="sect2">
 975 <h3 id="_patch_workflow">Patch workflow</h3>
 976 <div class="paragraph">
 977 <p>If you are a contributor that sends changes upstream in the form of
 978 emails, you should use topic branches as usual (see above).  Then use
 979 <a href="git-format-patch.html">git-format-patch(1)</a> to generate the corresponding emails
 980 (highly recommended over manually formatting them because it makes the
 981 maintainer&#8217;s life easier).</p>
 982 </div>
 983 <div class="exampleblock">
 984 <div class="title">Recipe: format-patch/am: Publishing branches/topics</div>
 985 <div class="content">
 986 <div class="ulist">
 987 <ul>
 988 <li>
 989 <p><code>git format-patch -M upstream..topic</code> to turn them into preformatted
 990 patch files</p>
 991 </li>
 992 <li>
 993 <p><code>git send-email --to=&lt;recipient&gt; &lt;patches&gt;</code></p>
 994 </li>
 995 </ul>
 996 </div>
 997 </div>
 998 </div>
 999 <div class="paragraph">
1000 <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>
1001 manpages for further usage notes.</p>
1002 </div>
1003 <div class="paragraph">
1004 <p>If the maintainer tells you that your patch no longer applies to the
1005 current upstream, you will have to rebase your topic (you cannot use a
1006 merge because you cannot format-patch merges):</p>
1007 </div>
1008 <div class="exampleblock">
1009 <div class="title">Recipe: format-patch/am: Keeping topics up to date</div>
1010 <div class="content">
1011 <div class="paragraph">
1012 <p><code>git pull --rebase &lt;URL&gt; &lt;branch&gt;</code></p>
1013 </div>
1014 </div>
1015 </div>
1016 <div class="paragraph">
1017 <p>You can then fix the conflicts during the rebase.  Presumably you have
1018 not published your topic other than by mail, so rebasing it is not a
1019 problem.</p>
1020 </div>
1021 <div class="paragraph">
1022 <p>If you receive such a patch series (as maintainer, or perhaps as a
1023 reader of the mailing list it was sent to), save the mails to files,
1024 create a new topic branch and use <em>git am</em> to import the commits:</p>
1025 </div>
1026 <div class="exampleblock">
1027 <div class="title">Recipe: format-patch/am: Importing patches</div>
1028 <div class="content">
1029 <div class="paragraph">
1030 <p><code>git am &lt; patch</code></p>
1031 </div>
1032 </div>
1033 </div>
1034 <div class="paragraph">
1035 <p>One feature worth pointing out is the three-way merge, which can help
1036 if you get conflicts: <code>git am -3</code> will use index information contained
1037 in patches to figure out the merge base.  See <a href="git-am.html">git-am(1)</a> for
1038 other options.</p>
1039 </div>
1040 </div>
1041 </div>
1042 </div>
1043 <div class="sect1">
1044 <h2 id="_see_also">SEE ALSO</h2>
1045 <div class="sectionbody">
1046 <div class="paragraph">
1047 <p><a href="gittutorial.html">gittutorial(7)</a>,
1048 <a href="git-push.html">git-push(1)</a>,
1049 <a href="git-pull.html">git-pull(1)</a>,
1050 <a href="git-merge.html">git-merge(1)</a>,
1051 <a href="git-rebase.html">git-rebase(1)</a>,
1052 <a href="git-format-patch.html">git-format-patch(1)</a>,
1053 <a href="git-send-email.html">git-send-email(1)</a>,
1054 <a href="git-am.html">git-am(1)</a></p>
1055 </div>
1056 </div>
1057 </div>
1058 <div class="sect1">
1059 <h2 id="_git">GIT</h2>
1060 <div class="sectionbody">
1061 <div class="paragraph">
1062 <p>Part of the <a href="git.html">git(1)</a> suite</p>
1063 </div>
1064 </div>
1065 </div>
1066 </div>
1067 <div id="footer">
1068 <div id="footer-text">
1069 Last updated 2021-12-10 14:52:02 -0800
1070 </div>
1071 </div>
1072 </body>
1073 </html>