| blob | 506c5d7f9e7ede08a96774bc4e1335ae165076a4 |
3 <head>
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}
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}
28 small{font-size:80%}
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}
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}
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}
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}
77 h4,h5{font-size:1.125em}
78 h6{font-size:1em}
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)}
85 ul,ol{margin-left:1.5em}
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}
92 dl dt{margin-bottom:.3125em;font-weight:bold}
93 dl dd{margin-bottom:1.25em}
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}
100 h4{font-size:1.4375em}}
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}
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}
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}
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}
131 .menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
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}
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}
147 #header .details br{display:none}
148 #header .details br+span::before{content:"\00a0\2013\00a0"}
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}
160 #toc a{text-decoration:none}
161 #toc a:active{text-decoration:underline}
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}
171 body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}
173 #toc.toc2{width:20em}
174 #toc.toc2 #toctitle{font-size:1.375em}
176 #toc.toc2 ul ul{padding-left:1.25em}
178 #content #toc{border:1px solid #e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;border-radius:4px}
183 #content{margin-bottom:.625em}
184 .sect1{padding-bottom:.625em}
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}
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)}
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}
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}
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}
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}
227 .listingblock pre.prettyprint{border-width:0}
228 .prettyprint{background:#f7f7f8}
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}
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}
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}
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)}
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}
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}
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}
263 table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
267 table.frame-all{border-width:1px}
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}
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}
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}
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}
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}
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}
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}
315 .colist td:not([class]):first-child img{max-width:none}
321 .imageblock.thumb,.imageblock.th{border-width:6px}
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}
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}
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}
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}
397 .print-only{display:none!important}
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}
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}
406 pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
407 thead{display:table-header-group}
408 svg{max-width:100%}
411 #header,#content,#footnotes,#footer{max-width:none}
412 #toc,.sidebarblock,.exampleblock>.content{background:none!important}
414 body.book #header{text-align:center}
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}}
429 .sect1{padding:0!important}
430 .sect1+.sect1{border:0}
431 #footer{background:none}
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>
444 </div>
450 <p>This is a tutorial demonstrating the end-to-end workflow of creating a change to
451 the Git tree, sending it for review, and making changes based on comments.</p>
452 </div>
457 source code. The Git workflow steps will largely remain unexplained.</p>
458 </div>
459 </div>
463 <p>This tutorial aims to summarize the following documents, but the reader may find
464 useful additional context:</p>
465 </div>
467 <ul>
468 <li>
470 </li>
471 <li>
473 </li>
474 </ul>
475 </div>
476 </div>
481 </div>
483 <h4 id="_gitvger_kernel_org"><a class="anchor" href="#_gitvger_kernel_org"></a><a href="mailto:git@vger.kernel.org">git@vger.kernel.org</a></h4>
485 <p>This is the main Git project mailing list where code reviews, version
486 announcements, design discussions, and more take place. Those interested in
487 contributing are welcome to post questions here. The Git list requires
488 plain-text-only emails and prefers inline and bottom-posting when replying to
489 mail; you will be CC’d in all replies to you. Optionally, you can subscribe to
490 the list by sending an email to <<a href="mailto:git+subscribe@vger.kernel.org">git+subscribe@vger.kernel.org</a>>
491 (see <a href="https://subspace.kernel.org/subscribing.html" class="bare">https://subspace.kernel.org/subscribing.html</a> for details).
493 available to view in a browser.</p>
494 </div>
495 </div>
497 <h4 id="_git_mentoringgooglegroups_com"><a class="anchor" href="#_git_mentoringgooglegroups_com"></a><a href="https://groups.google.com/forum/#!forum/git-mentoring">git-mentoring@googlegroups.com</a></h4>
499 <p>This mailing list is targeted to new contributors and was created as a place to
500 post questions and receive answers outside of the public eye of the main list.
501 Veteran contributors who are especially interested in helping mentor newcomers
502 are present on the list. In order to avoid search indexers, group membership is
503 required to view messages; anyone can join and no approval is required.</p>
504 </div>
505 </div>
507 <h4 id="_git_devel_on_libera_chat"><a class="anchor" href="#_git_devel_on_libera_chat"></a><a href="https://web.libera.chat/#git-devel">#git-devel</a> on Libera Chat</h4>
509 <p>This IRC channel is for conversations between Git contributors. If someone is
510 currently online and knows the answer to your question, you can receive help
511 in real time. Otherwise, you can read the
513 whether someone answered you. IRC does not allow offline private messaging, so
514 if you try to private message someone and then log out of IRC, they cannot
515 respond to you. It’s better to ask your questions in the channel so that you
516 can be answered if you disconnect and so that others can learn from the
517 conversation.</p>
518 </div>
519 </div>
520 </div>
521 </div>
522 </div>
529 <p>Git is mirrored in a number of locations. Clone the repository from one of them;
530 <a href="https://git-scm.com/downloads" class="bare">https://git-scm.com/downloads</a> suggests one of the best places to clone from is
531 the mirror on GitHub.</p>
532 </div>
535 <pre>$ git clone https://github.com/git/git git
536 $ cd git</pre>
537 </div>
538 </div>
539 </div>
543 <p>To build Git from source, you need to have a handful of dependencies installed
544 on your system. For a hint of what’s needed, you can take a look at
546 external programs and libraries. That document mentions a way to "test-drive"
548 this tutorial.</p>
549 </div>
551 <p>Make sure that your environment has everything you need by building your brand
552 new clone of Git from the above step:</p>
553 </div>
557 </div>
558 </div>
560 <table>
561 <tr>
564 </td>
567 use it as you prefer, here and elsewhere.
568 </td>
569 </tr>
570 </table>
571 </div>
572 </div>
574 <h3 id="identify-problem"><a class="anchor" href="#identify-problem"></a>Identify Problem to Solve</h3>
576 <p>In this tutorial, we will add a new command, <code>git</code> <code>psuh</code>, short for “Pony Saying
577 ‘Um, Hello”’ - a feature which has gone unimplemented despite a high frequency
578 of invocation during users' typical daily workflow.</p>
579 </div>
583 </div>
584 </div>
586 <h3 id="setup-workspace"><a class="anchor" href="#setup-workspace"></a>Set Up Your Workspace</h3>
591 etc., you should check that document and base it on the appropriate branch.</p>
592 </div>
596 development like so:</p>
597 </div>
601 </div>
602 </div>
605 with multiple patches up for review simultaneously.</p>
606 </div>
607 </div>
608 </div>
609 </div>
614 <table>
615 <tr>
618 </td>
620 A reference implementation can be found at
621 <a href="https://github.com/nasamuffin/git/tree/psuh" class="bare">https://github.com/nasamuffin/git/tree/psuh</a>.
622 </td>
623 </tr>
624 </table>
625 </div>
627 <h3 id="add-new-command"><a class="anchor" href="#add-new-command"></a>Adding a New Command</h3>
629 <p>Lots of the subcommands are written as builtins, which means they are
632 codebase, the internal API, and the process of working together as a contributor
633 with the reviewers and maintainer to integrate this change into the system.</p>
634 </div>
637 followed by the name of the subcommand, in a source file named after the
640 point for your command in a function matching the style and signature:</p>
641 </div>
645 </div>
646 </div>
648 <p>We’ll also need to add the declaration of psuh; open up <code>builtin.h</code>, find the
649 declaration for <code>cmd_pull</code>, and add a new line for <code>psuh</code> immediately before it,
650 in order to keep the declarations alphabetically sorted:</p>
651 </div>
655 </div>
656 </div>
658 <p>Be sure to #include "builtin.<code>h</code>" in your <code>psuh.c</code>. You’ll also need to
660 </div>
663 decent starting point as we can now add build rules and register the command.</p>
664 </div>
666 <table>
667 <tr>
670 </td>
672 Your throwaway text, as well as much of the text you will be adding over
673 the course of this tutorial, is user-facing. That means it needs to be
675 Throughout the tutorial, we will mark strings for translation as necessary; you
676 should also do so when writing your user-facing commands in the future.
677 </td>
678 </tr>
679 </table>
680 </div>
683 <pre>int cmd_psuh(int argc, const char **argv, const char *prefix)
684 {
685 printf(_("Pony saying hello goes here.\n"));
686 return 0;
687 }</pre>
688 </div>
689 </div>
691 <p>Let’s try to build it. Open <code>Makefile</code>, find where <code>builtin/pull.o</code> is added
693 alphabetical order. Once you’ve done so, move to the top-level directory and
695 some additional warnings:</p>
696 </div>
700 $ make</pre>
701 </div>
702 </div>
704 <table>
705 <tr>
708 </td>
710 When you are developing the Git project, it’s preferred that you use the
711 <code>DEVELOPER</code> flag; if there’s some reason it doesn’t work for you, you can turn
712 it off, but it’s a good idea to mention the problem to the mailing list.
713 </td>
714 </tr>
715 </table>
716 </div>
718 <p>Great, now your new command builds happily on its own. But nobody invokes it.
720 </div>
723 a <code>cmd_struct</code> to the <code>commands</code>[] array. <code>struct</code> <code>cmd_struct</code> takes a string
724 with the command name, a function pointer to the command implementation, and a
726 <code>cmd_push</code> is registered, copy it, and modify it for <code>cmd_psuh</code>, placing the new
728 </div>
731 we hope to print some data about the user’s current workspace context later,
733 </div>
736 and see if it works. There’s a binary you can use to test with in the
738 </div>
742 </div>
743 </div>
746 </div>
748 <p><code>git</code> <code>status</code> reveals modified <code>Makefile</code>, <code>builtin.h</code>, and <code>git.c</code> as well as
749 untracked <code>builtin/psuh.c</code> and <code>git-psuh</code>. First, let’s take care of the binary,
750 which should be ignored. Open .<code>gitignore</code> in your editor, find <code>/git-pull</code>, and
751 add an entry for your new command in alphabetical order:</p>
752 </div>
755 <pre>...
756 /git-prune-packed
757 /git-psuh
758 /git-pull
759 /git-push
760 /git-quiltimport
761 /git-range-diff
762 ...</pre>
763 </div>
764 </div>
766 <p>Checking <code>git</code> <code>status</code> again should show that <code>git-psuh</code> has been removed from
768 can stage and commit:</p>
769 </div>
772 <pre>$ git add Makefile builtin.h builtin/psuh.c git.c .gitignore
773 $ git commit -s</pre>
774 </div>
775 </div>
777 <p>You will be presented with your editor in order to write a commit message. Start
778 the commit with a 50-column or less subject line, including the name of the
779 component you’re working on, followed by a blank line (always required) and then
780 the body of your commit message, which should provide the bulk of the context.
781 Remember to be explicit and provide the "Why" of your change, especially if it
782 couldn’t easily be understood from your diff. When editing your commit message,
783 don’t remove the <code>Signed-off-by</code> trailer which was added by <code>-s</code> above.</p>
784 </div>
787 <pre>psuh: add a built-in by popular demand
789 Internal metrics indicate this is a command many users expect to be
790 present. So here's an implementation to help drive customer
791 satisfaction and engagement: a pony which doubtfully greets the user,
792 or, a Pony Saying "Um, Hello" (PSUH).
794 This commit message is intentionally formatted to 72 columns per line,
795 starts with a single line as "commit message subject" that is written as
796 if to command the codebase to do something (add this, teach a command
797 that). The body of the message is designed to add information about the
798 commit that is not readily deduced from reading the associated diff,
799 such as answering the question "why?".
802 </div>
803 </div>
805 <p>Go ahead and inspect your new commit with <code>git</code> <code>show</code>. "psuh:" indicates you
810 </div>
812 <p>For the remainder of the tutorial, the subject line only will be listed for the
813 sake of brevity. However, fully-fleshed example commit messages are available
814 on the reference implementation linked at the top of this document.</p>
815 </div>
816 </div>
822 </div>
824 <p>Modify your <code>cmd_psuh</code> implementation to dump the args you’re passed, keeping
826 </div>
829 <pre> int i;
831 ...
833 printf(Q_("Your args (there is %d):\n",
834 "Your args (there are %d):\n",
835 argc),
836 argc);
838 printf("%d: %s\n", i, argv[i]);
840 printf(_("Your current working directory:\n<top-level>%s%s\n"),
842 </div>
843 </div>
847 for you, try <code>cd</code> <code>Documentation/</code> && <code>..</code><code>/bin-wrappers/git</code> <code>psuh</code>). That’s not so
848 helpful. So what other context can we get?</p>
849 </div>
852 function body:</p>
853 </div>
856 <pre> const char *cfg_name;
858 ...
860 git_config(git_default_config, NULL);
862 printf(_("No name is found in config\n"));
863 else
865 </div>
866 </div>
870 a specific key ("user.name") and give you the value. There are a number of
871 single-key lookup functions like this one; you can see them all (and more info
872 about how to use <code>git_config</code>()) in <code>Documentation/technical/api-config.txt</code>.</p>
873 </div>
876 </div>
880 </div>
881 </div>
885 </div>
888 <pre>$ git add builtin/psuh.c
890 </div>
891 </div>
893 <table>
894 <tr>
897 </td>
899 Again, the above is for sake of brevity in this tutorial. In a real change
901 message.
902 </td>
903 </tr>
904 </table>
905 </div>
907 <p>Still, it’d be nice to know what the user’s working context is like. Let’s see
908 if we can print the name of the user’s current branch. We can mimic the
909 <code>git</code> <code>status</code> implementation; the printer is located in <code>wt-status.c</code> and we can
911 </div>
913 <p><code>wt_status_print</code>() gets invoked by <code>cmd_status</code>() in <code>builtin/commit.c</code>.
914 Looking at that implementation we see the status config being populated like so:</p>
915 </div>
919 </div>
920 </div>
924 </div>
926 <p>Be sure to include the header to allow you to use <code>struct</code> <code>wt_status</code>:</p>
927 </div>
931 </div>
932 </div>
934 <p>Then modify your <code>cmd_psuh</code> implementation to declare your <code>struct</code> <code>wt_status</code>,
935 prepare it, and print its contents:</p>
936 </div>
939 <pre> struct wt_status status;
941 ...
943 wt_status_prepare(the_repository, &status);
944 git_config(git_default_config, &status);
946 ...
949 </div>
950 </div>
953 </div>
956 </div>
959 <pre>$ git add builtin/psuh.c
961 </div>
962 </div>
965 </div>
969 string; <code>pretty.h</code> has an extremely handy <code>pp_commit_easy</code>() call which doesn’t
970 require a full format object to be passed.</p>
971 </div>
974 </div>
979 </div>
980 </div>
983 the declarations and the logic, respectively.</p>
984 </div>
987 <pre> struct commit *c = NULL;
988 struct strbuf commitline = STRBUF_INIT;
990 ...
992 c = lookup_commit_reference_by_name("origin/master");
994 if (c != NULL) {
995 pp_commit_easy(CMIT_FMT_ONELINE, c, &commitline);
996 printf(_("Current commit: %s\n"), commitline.buf);
997 }</pre>
998 </div>
999 </div>
1001 <p>The <code>struct</code> <code>strbuf</code> provides some safety belts to your basic <code>char</code>*, one of
1002 which is a length member to prevent buffer overruns. It needs to be initialized
1003 nicely with <code>STRBUF_INIT</code>. Keep it in mind when you need to pass around <code>char</code>*.</p>
1004 </div>
1007 with the value there and see what kind of things you can come up with.</p>
1008 </div>
1010 <p><code>pp_commit_easy</code> is a convenience wrapper in <code>pretty.h</code> that takes a single
1011 format enum shorthand, rather than an entire format struct. It then
1012 pretty-prints the commit according to that shorthand. These are similar to the
1014 </div>
1019 </div>
1022 <pre>$ git add builtin/psuh.c
1024 </div>
1025 </div>
1026 </div>
1028 <h3 id="add-documentation"><a class="anchor" href="#add-documentation"></a>Adding Documentation</h3>
1031 community. But hang on just a minute - this isn’t very user-friendly. Run the
1032 following:</p>
1033 </div>
1037 </div>
1038 </div>
1041 </div>
1043 <p>Take a look at <code>Documentation/git-</code>*.<code>txt</code>. These are the manpages for the
1044 subcommands that Git knows about. You can open these up and take a look to get
1045 acquainted with the format, but then go ahead and make a new file
1047 project, help pages are written with AsciiDoc (see CodingGuidelines, "Writing
1048 Documentation" section). Use the following template to fill out your own
1049 manpage:</p>
1050 </div>
1054 ===========
1056 NAME
1057 ----
1058 git-psuh - Delight users' typo with a shy horse
1061 SYNOPSIS
1062 --------
1063 [verse]
1066 DESCRIPTION
1067 -----------
1068 ...
1070 OPTIONS[[OPTIONS]]
1071 ------------------
1072 ...
1074 OUTPUT
1075 ------
1076 ...
1078 GIT
1079 ---
1081 </div>
1082 </div>
1084 <p>The most important pieces of this to note are the file header, underlined by =,
1085 the NAME section, and the SYNOPSIS, which would normally contain the grammar if
1086 your command took arguments. Try to use well-established manpage headers so your
1087 documentation is consistent with other Git and UNIX manpages; this makes life
1088 easier for your user, who can skip to the section they know contains the
1089 information they need.</p>
1090 </div>
1092 <table>
1093 <tr>
1096 </td>
1099 installed.
1100 </td>
1101 </tr>
1102 </table>
1103 </div>
1106 convert your AsciiDoc to troff which is man-readable like so:</p>
1107 </div>
1110 <pre>$ make all doc
1112 </div>
1113 </div>
1116 </div>
1121 </div>
1122 </div>
1124 <p>While this isn’t as satisfying as running through <code>git</code> <code>help</code>, you can at least
1125 check that your help page looks right.</p>
1126 </div>
1128 <p>You can also check that the documentation coverage is good (that is, the project
1129 sees that your command has been implemented as well as documented) by running
1131 </div>
1134 </div>
1135 </div>
1139 <p>Try and run .<code>/bin-wrappers/git</code> <code>psuh</code> <code>-h</code>. Your command should crash at the end.
1141 printing usage.</p>
1142 </div>
1145 tool for pulling out options you need to be able to handle, and it takes a
1146 usage string.</p>
1147 </div>
1151 </div>
1154 </div>
1157 </div>
1160 <pre>static const char * const psuh_usage[] = {
1161 N_("git psuh [<arg>...]"),
1162 NULL,
1163 };</pre>
1164 </div>
1165 </div>
1170 </div>
1173 <pre> struct option options[] = {
1174 OPT_END()
1175 };</pre>
1176 </div>
1177 </div>
1179 <p>Finally, before you print your args and prefix, add the call to
1181 </div>
1185 </div>
1186 </div>
1189 specified in <code>options</code> from <code>argv</code> and the locations pointed to from <code>options</code>
1191 <code>parse_options</code>(), or you will be confused if you try to parse <code>argv</code> later.</p>
1192 </div>
1194 <p>It’s worth noting the special argument <code>--</code>. As you may be aware, many Unix
1197 you want to pass as a parameter something which would usually be interpreted as
1198 a flag.) <code>parse_options</code>() will terminate parsing when it reaches <code>--</code> and give
1199 you the rest of the options afterwards, untouched.</p>
1200 </div>
1202 <p>Now that you have a usage hint, you can teach Git how to show it in the general
1203 command list shown by <code>git</code> <code>help</code> <code>git</code> or <code>git</code> <code>help</code> <code>-a</code>, which is generated from
1204 <code>command-list.txt</code>. Find the line for <em>git-pull</em> so you can add your <em>git-psuh</em>
1205 line above it in alphabetical order. Now, we can add some attributes about the
1206 command which impacts where it shows up in the aforementioned help commands. The
1208 means; in those help pages, the commands are sorted according to these
1209 attributes. <code>git</code> <code>psuh</code> is user-facing, or porcelain - so we will mark it as
1212 list; since <code>git</code> <code>psuh</code> shows some information about the user’s workspace but
1215 align and delineate them:</p>
1216 </div>
1219 <pre>git-prune-packed plumbingmanipulators
1220 git-psuh mainporcelain info
1221 git-pull mainporcelain remote
1222 git-push mainporcelain remote</pre>
1223 </div>
1224 </div>
1227 your command terminated before anything else interesting happens. Great!</p>
1228 </div>
1231 </div>
1232 </div>
1233 </div>
1234 </div>
1240 Moreover, your patch won’t be accepted into the Git tree without tests. Your
1241 tests should:</p>
1242 </div>
1244 <ul>
1245 <li>
1247 </li>
1248 <li>
1250 </li>
1251 <li>
1253 </li>
1254 </ul>
1255 </div>
1258 </div>
1261 </div>
1263 <h3 id="overview-test-structure"><a class="anchor" href="#overview-test-structure"></a>Overview of Testing Structure</h3>
1267 </div>
1268 </div>
1273 as many of the family/subcmd combinations are full, best practice seems to be
1274 to find a command close enough to the one you’ve added and share its naming
1275 space.</p>
1276 </div>
1280 </div>
1283 <pre>#!/bin/sh
1285 test_description='git-psuh test
1287 This test runs git-psuh and makes sure it does not crash.'
1289 . ./test-lib.sh</pre>
1290 </div>
1291 </div>
1294 formatted results. Let’s make sure that <code>git</code> <code>psuh</code> doesn’t exit poorly and does
1295 mention the right animal somewhere:</p>
1296 </div>
1299 <pre>test_expect_success 'runs correctly with no args and good output' '
1301 grep Pony actual
1302 '</pre>
1303 </div>
1304 </div>
1307 bottom of your script:</p>
1308 </div>
1312 </div>
1313 </div>
1316 </div>
1320 </div>
1321 </div>
1323 <p>You can get an idea of whether you created your new test script successfully
1324 by running <code>make</code> <code>-C</code> <code>t</code> <code>test-lint</code>, which will check for things like test number
1325 uniqueness, executable bit, and so on.</p>
1326 </div>
1327 </div>
1332 </div>
1335 <pre>$ make
1337 </div>
1338 </div>
1340 <p>You can run the full test suite and ensure <code>git-psuh</code> didn’t break anything:</p>
1341 </div>
1344 <pre>$ cd t/
1346 </div>
1347 </div>
1349 <table>
1350 <tr>
1353 </td>
1355 You can also do this with <code>make</code> <code>test</code> or use any testing harness which can
1356 speak TAP. <code>prove</code> can run concurrently. <code>shuffle</code> randomizes the order the
1357 tests are run in, which makes them resilient against unwanted inter-test
1359 </td>
1360 </tr>
1361 </table>
1362 </div>
1365 </div>
1366 </div>
1367 </div>
1368 </div>
1370 <h2 id="ready-to-share"><a class="anchor" href="#ready-to-share"></a>Getting Ready to Share: Anatomy of a Patch Series</h2>
1373 <p>You may have noticed already that the Git project performs its code reviews via
1374 emailed patches, which are then applied by the maintainer when they are ready
1375 and approved by the community. The Git project does not accept contributions from
1376 pull requests, and the patches emailed for review need to be formatted a
1377 specific way.</p>
1378 </div>
1380 <p>Before taking a look at how to convert your commits into emailed patches,
1382 <a href="https://lore.kernel.org/git/pull.1218.git.git.1645209647.gitgitgadget@gmail.com/">example</a> of the summary view for a patch series on the web interface of
1384 </div>
1388 2022-02-18 18:40 ` [PATCH 1/3] reflog: libify delete reflog function and helpers John Cai via GitGitGadget
1397 2022-02-18 18:40 ` [PATCH 2/3] reflog: call reflog_delete from reflog.c John Cai via GitGitGadget
1400 2022-02-18 18:40 ` [PATCH 3/3] stash: call reflog_delete from reflog.c John Cai via GitGitGadget
1407 2022-02-22 18:30 ` [PATCH v2 1/3] stash: add test to ensure reflog --rewrite --updatref behavior John Cai via GitGitGadget
1410 // continued</pre>
1411 </div>
1412 </div>
1415 </div>
1417 <ul>
1418 <li>
1419 <p>Each commit is sent as a separate email, with the commit message title as
1422 </li>
1423 <li>
1426 </li>
1427 <li>
1430 three patches in the second iteration. Each iteration is sent with a new cover
1431 letter (like "[PATCH v2 0/3]" above), itself a reply to the cover letter of the
1432 previous iteration (more on that below).</p>
1433 </li>
1434 </ul>
1435 </div>
1437 <table>
1438 <tr>
1441 </td>
1445 though).
1446 </td>
1447 </tr>
1448 </table>
1449 </div>
1453 <p>In addition to an email per patch, the Git community also expects your patches
1454 to come with a cover letter. This is an important component of change
1455 submission as it explains to the community from a high level what you’re trying
1456 to do, and why, in a way that’s more apparent than just looking at your
1457 patches.</p>
1458 </div>
1460 <p>The title of your cover letter should be something which succinctly covers the
1461 purpose of your entire topic branch. It’s often in the imperative mood, just
1463 </div>
1464 <hr/>
1467 ---</p>
1468 </div>
1470 <p>The body of the cover letter is used to give additional context to reviewers.
1471 Be sure to explain anything your patches don’t make clear on their own, but
1472 remember that since the cover letter is not recorded in the commit history,
1473 anything that might be useful to future readers of the repository’s history
1474 should also be in your commit messages.</p>
1475 </div>
1478 </div>
1481 <pre>Our internal metrics indicate widespread interest in the command
1482 git-psuh - that is, many users are trying to use it, but finding it is
1483 unavailable, using some unknown workaround instead.
1485 The following handful of patches add the psuh command and implement some
1486 handy features on top of it.
1488 This patchset is part of the MyFirstContribution tutorial and should not
1489 be merged.</pre>
1490 </div>
1491 </div>
1493 <p>At this point the tutorial diverges, in order to demonstrate two
1494 different methods of formatting your patchset and getting it reviewed.</p>
1495 </div>
1497 <p>The first method to be covered is GitGitGadget, which is useful for those
1498 already familiar with GitHub’s common pull request workflow. This method
1499 requires a GitHub account.</p>
1500 </div>
1502 <p>The second method to be covered is <code>git</code> <code>send-email</code>, which can give slightly
1503 more fine-grained control over the emails to be sent. This method requires some
1504 setup which can change depending on your system and will not be covered in this
1505 tutorial.</p>
1506 </div>
1508 <p>Regardless of which method you choose, your engagement with reviewers will be
1509 the same; the review process will be covered after the sections on GitGitGadget
1511 </div>
1512 </div>
1513 </div>
1514 </div>
1516 <h2 id="howto-ggg"><a class="anchor" href="#howto-ggg"></a>Sending Patches via GitGitGadget</h2>
1519 <p>One option for sending patches is to follow a typical pull request workflow and
1520 send your patches out via GitGitGadget. GitGitGadget is a tool created by
1521 Johannes Schindelin to make life as a Git contributor easier for those used to
1522 the GitHub PR workflow. It allows contributors to open pull requests against its
1523 mirror of the Git project, and does some magic to turn the PR into a set of
1524 emails and send them out for you. It also runs the Git continuous integration
1525 suite for you. It’s documented at <a href="https://gitgitgadget.github.io/" class="bare">https://gitgitgadget.github.io/</a>.</p>
1526 </div>
1528 <h3 id="create-fork"><a class="anchor" href="#create-fork"></a>Forking <code>git/git</code> on GitHub</h3>
1530 <p>Before you can send your patch off to be reviewed using GitGitGadget, you will
1531 need to fork the Git project and upload your changes. First thing - make sure
1532 you have a GitHub account.</p>
1533 </div>
1536 button. Place your fork wherever you deem appropriate and create it.</p>
1537 </div>
1538 </div>
1540 <h3 id="upload-to-fork"><a class="anchor" href="#upload-to-fork"></a>Uploading to Your Own Fork</h3>
1543 remote. You can use <code>git</code> <code>remote</code> <code>-v</code> to show the remotes you have added already.
1545 the URL; then you need to run the following to add, replacing your own URL and
1546 remote name for the examples provided:</p>
1547 </div>
1551 </div>
1552 </div>
1555 </div>
1559 </div>
1560 </div>
1562 <p>Run <code>git</code> <code>remote</code> <code>-v</code> again and you should see the new remote showing up.
1563 <code>git</code> <code>fetch</code> <code>remotename</code> (with the real name of your remote replaced) in order to
1564 get ready to push.</p>
1565 </div>
1568 by running <code>git</code> <code>branch</code>. If you didn’t, now is a good time to move your new
1569 commits to their own branch.</p>
1570 </div>
1572 <p>As mentioned briefly at the beginning of this document, we are basing our work
1574 workflow.</p>
1575 </div>
1578 <pre>$ git checkout master
1579 $ git pull -r
1580 $ git rebase master psuh</pre>
1581 </div>
1582 </div>
1585 command name choices, be careful when you type the command below.)</p>
1586 </div>
1590 </div>
1591 </div>
1594 </div>
1595 </div>
1597 <h3 id="send-pr-ggg"><a class="anchor" href="#send-pr-ggg"></a>Sending a PR to GitGitGadget</h3>
1599 <p>In order to have your code tested and formatted for review, you need to start by
1601 <a href="https://github.com/gitgitgadget/git" class="bare">https://github.com/gitgitgadget/git</a> and open a PR either with the "New pull
1603 appear with the name of your newly pushed branch.</p>
1604 </div>
1607 respectively as the subject and body of the cover letter for your change. Refer
1609 submission and what content to include in the description.</p>
1610 </div>
1612 <table>
1613 <tr>
1616 </td>
1618 For single-patch contributions, your commit message should already be
1619 meaningful and explain at a high level the purpose (what is happening and why)
1620 of your patch, so you usually do not need any additional context. In that case,
1621 remove the PR description that GitHub automatically generates from your commit
1622 message (your PR description should be empty). If you do need to supply even
1623 more context, you can do so in that space and it will be appended to the email
1624 that GitGitGadget will send, between the three-dash line and the diffstat
1626 submitted).
1627 </td>
1628 </tr>
1629 </table>
1630 </div>
1633 </div>
1634 </div>
1636 <h3 id="run-ci-ggg"><a class="anchor" href="#run-ci-ggg"></a>Running CI and Getting Ready to Send</h3>
1639 this tutorial) then someone will need to give you permission to use the tool.
1640 As mentioned in the GitGitGadget documentation, you just need someone who
1641 already uses it to comment on your PR with <code>/allow</code> <em><username></em>. GitGitGadget
1642 will automatically run your PRs through the CI even without the permission given
1644 use the tool.</p>
1645 </div>
1647 <table>
1648 <tr>
1651 </td>
1655 (<a href="https://github.com/gitgitgadget/git/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+%22%2Fallow%22">Search:
1660 </td>
1661 </tr>
1662 </table>
1663 </div>
1665 <p>If the CI fails, you can update your changes with <code>git</code> <code>rebase</code> <code>-i</code> and push your
1666 branch again:</p>
1667 </div>
1671 </div>
1672 </div>
1674 <p>In fact, you should continue to make changes this way up until the point when
1676 </div>
1677 </div>
1681 <p>Now that your CI is passing and someone has granted you permission to use
1684 </div>
1685 </div>
1687 <h3 id="responding-ggg"><a class="anchor" href="#responding-ggg"></a>Updating With Comments</h3>
1690 reply to review comments you will receive on the mailing list.</p>
1691 </div>
1693 <p>Once you have your branch again in the shape you want following all review
1694 comments, you can submit again:</p>
1695 </div>
1699 </div>
1700 </div>
1702 <p>Next, go look at your pull request against GitGitGadget; you should see the CI
1703 has been kicked off again. Now while the CI is running is a good time for you
1704 to modify your description at the top of the pull request thread; it will be
1705 used again as the cover letter. You should use this space to describe what
1706 has changed since your previous version, so that your reviewers have some idea
1707 of what they’re looking at. When the CI is done running, you can comment once
1709 changes.</p>
1710 </div>
1711 </div>
1712 </div>
1713 </div>
1715 <h2 id="howto-git-send-email"><a class="anchor" href="#howto-git-send-email"></a>Sending Patches with <code>git</code> <code>send-email</code></h2>
1719 patches. Some benefits of using Git this way include finer grained control of
1720 subject line (for example, being able to use the tag [RFC PATCH] in the subject)
1722 good before going out to the list.</p>
1723 </div>
1725 <h3 id="setup-git-send-email"><a class="anchor" href="#setup-git-send-email"></a>Prerequisite: Setting Up <code>git</code> <code>send-email</code></h3>
1728 provider, and so will not be covered in this tutorial, beyond stating that in
1731 are a number of resources online to help you do so. You will also need to
1732 determine the right way to configure it to use your SMTP server; again, as this
1733 configuration can change significantly based on your system and email setup, it
1734 is out of scope for the context of this tutorial.</p>
1735 </div>
1736 </div>
1738 <h3 id="format-patch"><a class="anchor" href="#format-patch"></a>Preparing Initial Patchset</h3>
1740 <p>Sending emails with Git is a two-part process; before you can prepare the emails
1742 </div>
1746 </div>
1747 </div>
1750 <li>
1752 cover letter template for you. You will need to fill in the
1753 template before you’re ready to send - but for now, the template
1754 will be next to your other patches.</p>
1755 </li>
1756 <li>
1757 <p>The <code>-o</code> <code>psuh/</code> option tells <code>format-patch</code> to place the patch
1759 can take a directory and send out all the patches from there.</p>
1760 </li>
1761 <li>
1763 commit", on which the recipient is expected to apply the patch
1765 the base commit automatically, which is the merge base of tip
1766 commit of the remote-tracking branch and the specified revision
1767 range.</p>
1768 </li>
1769 <li>
1770 <p>The <code>psuh@</code>{u}<code>..</code><code>psuh</code> option tells <code>format-patch</code> to generate
1773 followed the example in the "Set up your workspace" section). If
1775 which means "commits on the current branch since it forked from
1777 </li>
1778 </ol>
1779 </div>
1781 <p>The command will make one patch file per commit. After you
1782 run, you can go have a look at each of the patches with your favorite text
1783 editor and make sure everything looks alright; however, it’s not recommended to
1784 make code fixups via the patch file. It’s a better idea to make the change the
1785 normal way using <code>git</code> <code>rebase</code> <code>-i</code> or by adding a new commit than by modifying a
1786 patch.</p>
1787 </div>
1789 <table>
1790 <tr>
1793 </td>
1796 with “[RFC PATCH]” instead of “[PATCH]”. RFC stands for “request for
1798 you’d like to begin the code review process. This can also be used when your
1799 patch is a proposal, but you aren’t sure whether the community wants to solve
1800 the problem with that approach or not - to conduct a sort of design review. You
1802 but want reviewers to look at what they have so far. You can add this flag with
1804 </td>
1805 </tr>
1806 </table>
1807 </div>
1809 <p>Check and make sure that your patches and cover letter template exist in the
1811 </div>
1812 </div>
1814 <h3 id="preparing-cover-letter"><a class="anchor" href="#preparing-cover-letter"></a>Preparing Email</h3>
1816 <p>Since you invoked <code>format-patch</code> with <code>--cover-letter</code>, you’ve already got a
1817 cover letter template ready. Open it up in your favorite editor.</p>
1818 </div>
1821 header is correct. Then modify your <code>Subject:</code> (see <a href="#cover-letter">above</a> for
1822 how to choose good title for your patch series):</p>
1823 </div>
1827 </div>
1828 </div>
1830 <p>Make sure you retain the “[PATCH 0/X]” part; that’s what indicates to the Git
1831 community that this email is the beginning of a patch series, and many
1832 reviewers filter their email for this type of flag.</p>
1833 </div>
1835 <p>You’ll need to add some extra parameters when you invoke <code>git</code> <code>send-email</code> to add
1836 the cover letter.</p>
1837 </div>
1841 </div>
1843 <p>The template created by <code>git</code> <code>format-patch</code> <code>--cover-letter</code> includes a diffstat.
1844 This gives reviewers a summary of what they’re in for when reviewing your topic.
1846 </div>
1850 Makefile | 1 +
1851 builtin.h | 1 +
1852 builtin/psuh.c | 73 ++++++++++++++++++++++++++++++++++++++
1853 git.c | 1 +
1854 t/t9999-psuh-tutorial.sh | 12 +++++++
1856 create mode 100644 Documentation/git-psuh.txt
1857 create mode 100644 builtin/psuh.c
1859 </div>
1860 </div>
1862 <p>Finally, the letter will include the version of Git used to generate the
1863 patches. You can leave that string alone.</p>
1864 </div>
1865 </div>
1867 <h3 id="sending-git-send-email"><a class="anchor" href="#sending-git-send-email"></a>Sending Email</h3>
1870 patches and a cover letter. Time to mail it out! You can send it like this:</p>
1871 </div>
1875 </div>
1876 </div>
1878 <table>
1879 <tr>
1882 </td>
1884 Check <code>git</code> <code>help</code> <code>send-email</code> for some other options which you may find
1885 valuable, such as changing the Reply-to address or adding more CC and BCC lines.
1886 </td>
1887 </tr>
1888 </table>
1889 </div>
1891 <table>
1892 <tr>
1895 </td>
1899 <code>--cc-cmd=</code>'perl <code>contrib/contacts/git-contacts</code>' <code>feature/</code>*.<code>patch</code><sup class="footnote" id="_footnote_contrib-scripts">[<a id="_footnoteref_1" class="footnote" href="#_footnotedef_1" title="View footnote.">1</a>]</sup> to
1901 </td>
1902 </tr>
1903 </table>
1904 </div>
1906 <table>
1907 <tr>
1910 </td>
1912 When you are sending a real patch, it will go to <a href="mailto:git@vger.kernel.org">git@vger.kernel.org</a> - but
1913 please don’t send your patchset from the tutorial to the real mailing list! For
1914 now, you can send it to yourself, to make sure you understand how it will look.
1915 </td>
1916 </tr>
1917 </table>
1918 </div>
1920 <p>After you run the command above, you will be presented with an interactive
1921 prompt for each patch that’s about to go out. This gives you one last chance to
1922 edit or quit sending something (but again, don’t edit code this way). Once you
1923 press <code>y</code> or <code>a</code> at these prompts your emails will be sent! Congratulations!</p>
1924 </div>
1926 <p>Awesome, now the community will drop everything and review your changes. (Just
1927 kidding - be patient!)</p>
1928 </div>
1929 </div>
1933 <p>This section will focus on how to send a v2 of your patchset. To learn what
1935 information on how to handle comments from reviewers.</p>
1936 </div>
1938 <p>We’ll reuse our <code>psuh</code> topic branch for v2. Before we make any changes, we’ll
1939 mark the tip of our v1 branch for easy reference:</p>
1940 </div>
1943 <pre>$ git checkout psuh
1944 $ git branch psuh-v1</pre>
1945 </div>
1946 </div>
1948 <p>Refine your patch series by using <code>git</code> <code>rebase</code> <code>-i</code> to adjust commits based upon
1949 reviewer comments. Once the patch series is ready for submission, generate your
1950 patches again, but with some new flags:</p>
1951 </div>
1954 <pre>$ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 master..</pre>
1955 </div>
1956 </div>
1958 <p>The <code>--range-diff</code> <code>master</code><code>..</code><code>psuh-v1</code> parameter tells <code>format-patch</code> to include a
1960 <a href="git-range-diff.html">git-range-diff(1)</a>). This helps tell reviewers about the differences
1961 between your v1 and v2 patches.</p>
1962 </div>
1965 as version "2". For instance, you may notice that your v2 patches are
1969 </div>
1971 <p>After you run this command, <code>format-patch</code> will output the patches to the <code>psuh/</code>
1972 directory, alongside the v1 patches. Using a single directory makes it easy to
1973 refer to the old v1 patches while proofreading the v2 patches, but you will need
1974 to be careful to send out only the v2 patches. We will use a pattern like
1975 <code>psuh/v2-</code>*.<code>patch</code> (not <code>psuh/</code>*.<code>patch</code>, which would match v1 and v2 patches).</p>
1976 </div>
1979 between your last version and now, if it’s something significant. You do not
1980 need the exact same body in your second cover letter; focus on explaining to
1982 </div>
1984 <p>You will also need to go and find the Message-ID of your previous cover letter.
1989 header. It should match:</p>
1990 </div>
1994 </div>
1995 </div>
1997 <p>Your Message-ID is <foo.<code>12345.author@example.com</code>>. This example will be used
1998 below as well; make sure to replace it with the correct Message-ID for your
1999 <strong>previous cover letter</strong> - that is, if you’re sending v2, use the Message-ID
2001 </div>
2003 <p>While you’re looking at the email, you should also note who is CC’d, as it’s
2004 common practice in the mailing list to keep all CCs on a thread. You can add
2005 these CC lines directly to your cover letter with a line like so in the header
2006 (before the Subject line):</p>
2007 </div>
2011 </div>
2012 </div>
2014 <p>Now send the emails again, paying close attention to which messages you pass in
2015 to the command:</p>
2016 </div>
2019 <pre>$ git send-email --to=target@example.com
2021 psuh/v2-*.patch</pre>
2022 </div>
2023 </div>
2024 </div>
2026 <h3 id="single-patch"><a class="anchor" href="#single-patch"></a>Bonus Chapter: One-Patch Changes</h3>
2028 <p>In some cases, your very small change may consist of only one patch. When that
2029 happens, you only need to send one email. Your commit message should already be
2030 meaningful and explain at a high level the purpose (what is happening and why)
2031 of your patch, but if you need to supply even more context, you can do so below
2032 the <code>---</code> in your patch. Take the example below, which was generated with <code>git</code>
2035 </div>
2041 Subject: [PATCH] README: change the grammar
2043 I think it looks better this way. This part of the commit message will
2044 end up in the commit-log.
2047 ---
2048 Let's have a wild discussion about grammar on the mailing list. This
2049 part of my email will never end up in the commit log. Here is where I
2050 can add additional context to the mailing list about my intent, outside
2051 of the context of the commit log. This section was added after `git
2052 format-patch` was run, by editing the patch file in a text editor.
2054 README.md | 2 +-
2057 diff --git a/README.md b/README.md
2059 --- a/README.md
2060 +++ b/README.md
2062 Git - fast, scalable, distributed revision control system
2063 =========================================================
2065 -Git is a fast, scalable, distributed revision control system with an
2066 +Git is a fast, scalable, and distributed revision control system with an
2067 unusually rich command set that provides both high-level operations
2068 and full access to internals.
2070 --
2072 </div>
2073 </div>
2074 </div>
2075 </div>
2076 </div>
2081 <p>Please give reviewers enough time to process your initial patch before
2082 sending an updated version. That is, resist the temptation to send a new
2083 version immediately, because others may have already started reviewing
2084 your initial version.</p>
2085 </div>
2087 <p>While waiting for review comments, you may find mistakes in your initial
2088 patch, or perhaps realize a different and better way to achieve the goal
2089 of the patch. In this case you may communicate your findings to other
2090 reviewers as follows:</p>
2091 </div>
2093 <ul>
2094 <li>
2095 <p>If the mistakes you found are minor, send a reply to your patch as if
2096 you were a reviewer and mention that you will fix them in an
2097 updated version.</p>
2098 </li>
2099 <li>
2100 <p>On the other hand, if you think you want to change the course so
2101 drastically that reviews on the initial patch would be a waste of
2102 time (for everyone involved), retract the patch immediately with
2103 a reply like "I am working on a much better approach, so please
2105 </li>
2106 </ul>
2107 </div>
2109 <p>Now, the above is a good practice if you sent your initial patch
2110 prematurely without polish. But a better approach of course is to avoid
2111 sending your patch prematurely in the first place.</p>
2112 </div>
2114 <p>Please be considerate of the time needed by reviewers to examine each
2115 new version of your patch. Rather than seeing the initial version right
2116 now (followed by several "oops, I like this version better than the
2118 single polished version came 2 days later instead, and that version with
2119 fewer mistakes were the only one they would need to review.</p>
2120 </div>
2124 <p>After a few days, you will hopefully receive a reply to your patchset with some
2125 comments. Woohoo! Now you can get back to work.</p>
2126 </div>
2129 made the change suggested, feel the original is better, or that the comment
2130 inspired you to do something a new way which is superior to both the original
2131 and the suggested change. This way reviewers don’t need to inspect your v2 to
2132 figure out whether you implemented their comment or not.</p>
2133 </div>
2135 <p>Reviewers may ask you about what you wrote in the patchset, either in
2136 the proposed commit log message or in the changes themselves. You
2137 should answer these questions in your response messages, but often the
2138 reason why reviewers asked these questions to understand what you meant
2139 to write is because your patchset needed clarification to be understood.</p>
2140 </div>
2142 <p>Do not be satisfied by just answering their questions in your response
2143 and hear them say that they now understand what you wanted to say.
2144 Update your patches to clarify the points reviewers had trouble with,
2145 and prepare your v2; the words you used to explain your v1 to answer
2146 reviewers' questions may be useful thing to use. Your goal is to make
2147 your v2 clear enough so that it becomes unnecessary for you to give the
2148 same explanation to the next person who reads it.</p>
2149 </div>
2151 <p>If you are going to push back on a comment, be polite and explain why you feel
2152 your original is better; be prepared that the reviewer may still disagree with
2153 you, and the rest of the community may weigh in on one side or the other. As
2154 with all code reviews, it’s important to keep an open mind to doing something a
2155 different way than you originally planned; other reviewers have a different
2156 perspective on the project than you do, and may be thinking of a valid side
2157 effect which had not occurred to you. It is always okay to ask for clarification
2158 if you aren’t sure why a change was suggested, or what the reviewer is asking
2159 you to do.</p>
2160 </div>
2162 <p>Make sure your email client has a plaintext email mode and it is turned on; the
2163 Git list rejects HTML email. Please also follow the mailing list etiquette
2164 outlined in the
2166 Note</a>, which are similar to etiquette rules in most open source communities
2167 surrounding bottom-posting and inline replies.</p>
2168 </div>
2171 commits are easiest to look at - if you use <code>git</code> <code>rebase</code> <code>-i</code> (interactive
2172 rebase). Take a look at this
2173 <a href="https://www.oreilly.com/library/view/git-pocket-guide/9781449327507/ch10.html">overview</a>
2174 from O’Reilly. The general idea is to modify each commit which requires changes;
2175 this way, instead of having a patch A with a mistake, a patch B which was fine
2176 and required no upstream reviews in v1, and a patch C which fixes patch A for
2177 v2, you can just ship a v2 with a correct patch A and correct patch B. This is
2179 anyone, that is okay for now! (Later, it may not make sense to do this; take a
2180 look at the section below this one for some context.)</p>
2181 </div>
2182 </div>
2184 <h3 id="after-approval"><a class="anchor" href="#after-approval"></a>After Review Approval</h3>
2186 <p>The Git project has four integration branches: <code>seen</code>, <code>next</code>, <code>master</code>, and
2187 <code>maint</code>. Your change will be placed into <code>seen</code> fairly early on by the maintainer
2188 while it is still in the review process; from there, when it is ready for wider
2189 testing, it will be merged into <code>next</code>. Plenty of early testers use <code>next</code> and
2190 may report issues. Eventually, changes in <code>next</code> will make it to <code>master</code>,
2191 which is typically considered stable. Finally, when a new release is cut,
2194 the use of the various integration branches.</p>
2195 </div>
2197 <p>Back to now: your code has been lauded by the upstream reviewers. It is perfect.
2198 It is ready to be accepted. You don’t need to do anything else; the maintainer
2200 </div>
2203 take some special steps depending on where you are in the process.</p>
2204 </div>
2207 your topic is marked for <code>next</code> - that is, that they plan to merge it to <code>next</code>
2208 but have not yet done so - you should send an email asking the maintainer to
2209 wait a little longer: "I’ve sent v4 of my series and you marked it for <code>next</code>,
2211 </div>
2214 patches with <code>git</code> <code>rebase</code> <code>-i</code>, you should make further changes incrementally -
2215 that is, with another commit, based on top of the maintainer’s topic branch as
2216 detailed in <a href="https://github.com/gitster/git" class="bare">https://github.com/gitster/git</a>. Your work is still in the same topic
2217 but is now incremental, rather than a wholesale rewrite of the topic branch.</p>
2218 </div>
2221 if you’re sending your reviews out that way, you should be sure to open your PR
2222 against the appropriate GitGitGadget/Git branch.</p>
2223 </div>
2225 <p>If you’re using <code>git</code> <code>send-email</code>, you can use it the same way as before, but you
2226 should generate your diffs from <em><topic></em><code>..</code><em><mybranch></em> and base your work on
2228 </div>
2229 </div>
2230 </div>
2231 </div>
2232 </div>
2234 <hr/>
2236 <a href="#_footnoteref_1">1</a>. Scripts under `contrib/` are not part of the core `git` binary and must be called directly. Clone the Git codebase and run `perl contrib/contacts/git-contacts`.
2237 </div>
2238 </div>
2242 </div>
2243 </div>
2244 </body>
2245 </html>