gitcore-tutorial.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>gitcore-tutorial(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>gitcore-tutorial(7) Manual Page</h1>
 444 <h2 id="_name">NAME</h2>
 445 <div class="sectionbody">
 446 <p>gitcore-tutorial - A Git core tutorial for developers</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="paragraph">
 454 <p>git *</p>
 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 tutorial explains how to use the "core" Git commands to set up and
 463 work with a Git repository.</p>
 464 </div>
 465 <div class="paragraph">
 466 <p>If you just need to use Git as a revision control system you may prefer
 467 to start with "A Tutorial Introduction to Git" (<a href="gittutorial.html">gittutorial(7)</a>) or
 468 <a href="user-manual.html">the Git User Manual</a>.</p>
 469 </div>
 470 <div class="paragraph">
 471 <p>However, an understanding of these low-level tools can be helpful if
 472 you want to understand Git&#8217;s internals.</p>
 473 </div>
 474 <div class="paragraph">
 475 <p>The core Git is often called "plumbing", with the prettier user
 476 interfaces on top of it called "porcelain". You may not want to use the
 477 plumbing directly very often, but it can be good to know what the
 478 plumbing does when the porcelain isn&#8217;t flushing.</p>
 479 </div>
 480 <div class="paragraph">
 481 <p>Back when this document was originally written, many porcelain
 482 commands were shell scripts. For simplicity, it still uses them as
 483 examples to illustrate how plumbing is fit together to form the
 484 porcelain commands. The source tree includes some of these scripts in
 485 contrib/examples/ for reference. Although these are not implemented as
 486 shell scripts anymore, the description of what the plumbing layer
 487 commands do is still valid.</p>
 488 </div>
 489 <div class="admonitionblock note">
 490 <table>
 491 <tr>
 492 <td class="icon">
 493 <div class="title">Note</div>
 494 </td>
 495 <td class="content">
 496 Deeper technical details are often marked as Notes, which you can
 497 skip on your first reading.
 498 </td>
 499 </tr>
 500 </table>
 501 </div>
 502 </div>
 503 </div>
 504 <div class="sect1">
 505 <h2 id="_creating_a_git_repository">Creating a Git repository</h2>
 506 <div class="sectionbody">
 507 <div class="paragraph">
 508 <p>Creating a new Git repository couldn&#8217;t be easier: all Git repositories start
 509 out empty, and the only thing you need to do is find yourself a
 510 subdirectory that you want to use as a working tree - either an empty
 511 one for a totally new project, or an existing working tree that you want
 512 to import into Git.</p>
 513 </div>
 514 <div class="paragraph">
 515 <p>For our first example, we&#8217;re going to start a totally new repository from
 516 scratch, with no pre-existing files, and we&#8217;ll call it <em>git-tutorial</em>.
 517 To start up, create a subdirectory for it, change into that
 518 subdirectory, and initialize the Git infrastructure with <em>git init</em>:</p>
 519 </div>
 520 <div class="listingblock">
 521 <div class="content">
 522 <pre>$ mkdir git-tutorial
 523 $ cd git-tutorial
 524 $ git init</pre>
 525 </div>
 526 </div>
 527 <div class="paragraph">
 528 <p>to which Git will reply</p>
 529 </div>
 530 <div class="listingblock">
 531 <div class="content">
 532 <pre>Initialized empty Git repository in .git/</pre>
 533 </div>
 534 </div>
 535 <div class="paragraph">
 536 <p>which is just Git&#8217;s way of saying that you haven&#8217;t been doing anything
 537 strange, and that it will have created a local .<code>git</code> directory setup for
 538 your new project. You will now have a .<code>git</code> directory, and you can
 539 inspect that with <em>ls</em>. For your new empty project, it should show you
 540 three entries, among other things:</p>
 541 </div>
 542 <div class="ulist">
 543 <ul>
 544 <li>
 545 <p>a file called <code>HEAD</code>, that has <code>ref:</code> <code>refs/heads/master</code> in it.
 546 This is similar to a symbolic link and points at
 547 <code>refs/heads/master</code> relative to the <code>HEAD</code> file.</p>
 548 <div class="paragraph">
 549 <p>Don&#8217;t worry about the fact that the file that the <code>HEAD</code> link points to
 550 doesn&#8217;t even exist yet&#8201;&#8212;&#8201;you haven&#8217;t created the commit that will
 551 start your <code>HEAD</code> development branch yet.</p>
 552 </div>
 553 </li>
 554 <li>
 555 <p>a subdirectory called <code>objects</code>, which will contain all the
 556 objects of your project. You should never have any real reason to
 557 look at the objects directly, but you might want to know that these
 558 objects are what contains all the real <em>data</em> in your repository.</p>
 559 </li>
 560 <li>
 561 <p>a subdirectory called <code>refs</code>, which contains references to objects.</p>
 562 </li>
 563 </ul>
 564 </div>
 565 <div class="paragraph">
 566 <p>In particular, the <code>refs</code> subdirectory will contain two other
 567 subdirectories, named <code>heads</code> and <code>tags</code> respectively. They do
 568 exactly what their names imply: they contain references to any number
 569 of different <em>heads</em> of development (aka <em>branches</em>), and to any
 570 <em>tags</em> that you have created to name specific versions in your
 571 repository.</p>
 572 </div>
 573 <div class="paragraph">
 574 <p>One note: the special <code>master</code> head is the default branch, which is
 575 why the .<code>git/HEAD</code> file was created points to it even if it
 576 doesn&#8217;t yet exist. Basically, the <code>HEAD</code> link is supposed to always
 577 point to the branch you are working on right now, and you always
 578 start out expecting to work on the <code>master</code> branch.</p>
 579 </div>
 580 <div class="paragraph">
 581 <p>However, this is only a convention, and you can name your branches
 582 anything you want, and don&#8217;t have to ever even <em>have</em> a <code>master</code>
 583 branch. A number of the Git tools will assume that .<code>git/HEAD</code> is
 584 valid, though.</p>
 585 </div>
 586 <div class="admonitionblock note">
 587 <table>
 588 <tr>
 589 <td class="icon">
 590 <div class="title">Note</div>
 591 </td>
 592 <td class="content">
 593 An <em>object</em> is identified by its 160-bit SHA-1 hash, aka <em>object name</em>,
 594 and a reference to an object is always the 40-byte hex
 595 representation of that SHA-1 name. The files in the <code>refs</code>
 596 subdirectory are expected to contain these hex references
 597 (usually with a final \n at the end), and you should thus
 598 expect to see a number of 41-byte files containing these
 599 references in these <code>refs</code> subdirectories when you actually start
 600 populating your tree.
 601 </td>
 602 </tr>
 603 </table>
 604 </div>
 605 <div class="admonitionblock note">
 606 <table>
 607 <tr>
 608 <td class="icon">
 609 <div class="title">Note</div>
 610 </td>
 611 <td class="content">
 612 An advanced user may want to take a look at <a href="gitrepository-layout.html">gitrepository-layout(5)</a>
 613 after finishing this tutorial.
 614 </td>
 615 </tr>
 616 </table>
 617 </div>
 618 <div class="paragraph">
 619 <p>You have now created your first Git repository. Of course, since it&#8217;s
 620 empty, that&#8217;s not very useful, so let&#8217;s start populating it with data.</p>
 621 </div>
 622 </div>
 623 </div>
 624 <div class="sect1">
 625 <h2 id="_populating_a_git_repository">Populating a Git repository</h2>
 626 <div class="sectionbody">
 627 <div class="paragraph">
 628 <p>We&#8217;ll keep this simple and stupid, so we&#8217;ll start off with populating a
 629 few trivial files just to get a feel for it.</p>
 630 </div>
 631 <div class="paragraph">
 632 <p>Start off with just creating any random files that you want to maintain
 633 in your Git repository. We&#8217;ll start off with a few bad examples, just to
 634 get a feel for how this works:</p>
 635 </div>
 636 <div class="listingblock">
 637 <div class="content">
 638 <pre>$ echo "Hello World" &gt;hello
 639 $ echo "Silly example" &gt;example</pre>
 640 </div>
 641 </div>
 642 <div class="paragraph">
 643 <p>you have now created two files in your working tree (aka <em>working directory</em>),
 644 but to actually check in your hard work, you will have to go through two steps:</p>
 645 </div>
 646 <div class="ulist">
 647 <ul>
 648 <li>
 649 <p>fill in the <em>index</em> file (aka <em>cache</em>) with the information about your
 650 working tree state.</p>
 651 </li>
 652 <li>
 653 <p>commit that index file as an object.</p>
 654 </li>
 655 </ul>
 656 </div>
 657 <div class="paragraph">
 658 <p>The first step is trivial: when you want to tell Git about any changes
 659 to your working tree, you use the <em>git update-index</em> program. That
 660 program normally just takes a list of filenames you want to update, but
 661 to avoid trivial mistakes, it refuses to add new entries to the index
 662 (or remove existing ones) unless you explicitly tell it that you&#8217;re
 663 adding a new entry with the <code>--add</code> flag (or removing an entry with the
 664 <code>--remove</code>) flag.</p>
 665 </div>
 666 <div class="paragraph">
 667 <p>So to populate the index with the two files you just created, you can do</p>
 668 </div>
 669 <div class="listingblock">
 670 <div class="content">
 671 <pre>$ git update-index --add hello example</pre>
 672 </div>
 673 </div>
 674 <div class="paragraph">
 675 <p>and you have now told Git to track those two files.</p>
 676 </div>
 677 <div class="paragraph">
 678 <p>In fact, as you did that, if you now look into your object directory,
 679 you&#8217;ll notice that Git will have added two new objects to the object
 680 database. If you did exactly the steps above, you should now be able to do</p>
 681 </div>
 682 <div class="listingblock">
 683 <div class="content">
 684 <pre>$ ls .git/objects/??/*</pre>
 685 </div>
 686 </div>
 687 <div class="paragraph">
 688 <p>and see two files:</p>
 689 </div>
 690 <div class="listingblock">
 691 <div class="content">
 692 <pre>.git/objects/55/7db03de997c86a4a028e1ebd3a1ceb225be238
 693 .git/objects/f2/4c74a2e500f5ee1332c86b94199f52b1d1d962</pre>
 694 </div>
 695 </div>
 696 <div class="paragraph">
 697 <p>which correspond with the objects with names of <code>557db..</code>. and
 698 <code>f24c7..</code>. respectively.</p>
 699 </div>
 700 <div class="paragraph">
 701 <p>If you want to, you can use <em>git cat-file</em> to look at those objects, but
 702 you&#8217;ll have to use the object name, not the filename of the object:</p>
 703 </div>
 704 <div class="listingblock">
 705 <div class="content">
 706 <pre>$ git cat-file -t 557db03de997c86a4a028e1ebd3a1ceb225be238</pre>
 707 </div>
 708 </div>
 709 <div class="paragraph">
 710 <p>where the <code>-t</code> tells <em>git cat-file</em> to tell you what the "type" of the
 711 object is. Git will tell you that you have a "blob" object (i.e., just a
 712 regular file), and you can see the contents with</p>
 713 </div>
 714 <div class="listingblock">
 715 <div class="content">
 716 <pre>$ git cat-file blob 557db03</pre>
 717 </div>
 718 </div>
 719 <div class="paragraph">
 720 <p>which will print out "Hello World". The object <code>557db03</code> is nothing
 721 more than the contents of your file <code>hello</code>.</p>
 722 </div>
 723 <div class="admonitionblock note">
 724 <table>
 725 <tr>
 726 <td class="icon">
 727 <div class="title">Note</div>
 728 </td>
 729 <td class="content">
 730 Don&#8217;t confuse that object with the file <code>hello</code> itself. The
 731 object is literally just those specific <strong>contents</strong> of the file, and
 732 however much you later change the contents in file <code>hello</code>, the object
 733 we just looked at will never change. Objects are immutable.
 734 </td>
 735 </tr>
 736 </table>
 737 </div>
 738 <div class="admonitionblock note">
 739 <table>
 740 <tr>
 741 <td class="icon">
 742 <div class="title">Note</div>
 743 </td>
 744 <td class="content">
 745 The second example demonstrates that you can
 746 abbreviate the object name to only the first several
 747 hexadecimal digits in most places.
 748 </td>
 749 </tr>
 750 </table>
 751 </div>
 752 <div class="paragraph">
 753 <p>Anyway, as we mentioned previously, you normally never actually take a
 754 look at the objects themselves, and typing long 40-character hex
 755 names is not something you&#8217;d normally want to do. The above digression
 756 was just to show that <em>git update-index</em> did something magical, and
 757 actually saved away the contents of your files into the Git object
 758 database.</p>
 759 </div>
 760 <div class="paragraph">
 761 <p>Updating the index did something else too: it created a .<code>git/index</code>
 762 file. This is the index that describes your current working tree, and
 763 something you should be very aware of. Again, you normally never worry
 764 about the index file itself, but you should be aware of the fact that
 765 you have not actually really "checked in" your files into Git so far,
 766 you&#8217;ve only <strong>told</strong> Git about them.</p>
 767 </div>
 768 <div class="paragraph">
 769 <p>However, since Git knows about them, you can now start using some of the
 770 most basic Git commands to manipulate the files or look at their status.</p>
 771 </div>
 772 <div class="paragraph">
 773 <p>In particular, let&#8217;s not even check in the two files into Git yet, we&#8217;ll
 774 start off by adding another line to <code>hello</code> first:</p>
 775 </div>
 776 <div class="listingblock">
 777 <div class="content">
 778 <pre>$ echo "It's a new day for git" &gt;&gt;hello</pre>
 779 </div>
 780 </div>
 781 <div class="paragraph">
 782 <p>and you can now, since you told Git about the previous state of <code>hello</code>, ask
 783 Git what has changed in the tree compared to your old index, using the
 784 <em>git diff-files</em> command:</p>
 785 </div>
 786 <div class="listingblock">
 787 <div class="content">
 788 <pre>$ git diff-files</pre>
 789 </div>
 790 </div>
 791 <div class="paragraph">
 792 <p>Oops. That wasn&#8217;t very readable. It just spit out its own internal
 793 version of a <em>diff</em>, but that internal version really just tells you
 794 that it has noticed that "hello" has been modified, and that the old object
 795 contents it had have been replaced with something else.</p>
 796 </div>
 797 <div class="paragraph">
 798 <p>To make it readable, we can tell <em>git diff-files</em> to output the
 799 differences as a patch, using the <code>-p</code> flag:</p>
 800 </div>
 801 <div class="listingblock">
 802 <div class="content">
 803 <pre>$ git diff-files -p
 804 diff --git a/hello b/hello
 805 index 557db03..263414f 100644
 806 --- a/hello
 807 +++ b/hello
 808 @@ -1 +1,2 @@
 809  Hello World
 810 +It's a new day for git</pre>
 811 </div>
 812 </div>
 813 <div class="paragraph">
 814 <p>i.e. the diff of the change we caused by adding another line to <code>hello</code>.</p>
 815 </div>
 816 <div class="paragraph">
 817 <p>In other words, <em>git diff-files</em> always shows us the difference between
 818 what is recorded in the index, and what is currently in the working
 819 tree. That&#8217;s very useful.</p>
 820 </div>
 821 <div class="paragraph">
 822 <p>A common shorthand for <code>git</code> <code>diff-files</code> <code>-p</code> is to just write <code>git</code>
 823 <code>diff</code>, which will do the same thing.</p>
 824 </div>
 825 <div class="listingblock">
 826 <div class="content">
 827 <pre>$ git diff
 828 diff --git a/hello b/hello
 829 index 557db03..263414f 100644
 830 --- a/hello
 831 +++ b/hello
 832 @@ -1 +1,2 @@
 833  Hello World
 834 +It's a new day for git</pre>
 835 </div>
 836 </div>
 837 </div>
 838 </div>
 839 <div class="sect1">
 840 <h2 id="_committing_git_state">Committing Git state</h2>
 841 <div class="sectionbody">
 842 <div class="paragraph">
 843 <p>Now, we want to go to the next stage in Git, which is to take the files
 844 that Git knows about in the index, and commit them as a real tree. We do
 845 that in two phases: creating a <em>tree</em> object, and committing that <em>tree</em>
 846 object as a <em>commit</em> object together with an explanation of what the
 847 tree was all about, along with information of how we came to that state.</p>
 848 </div>
 849 <div class="paragraph">
 850 <p>Creating a tree object is trivial, and is done with <em>git write-tree</em>.
 851 There are no options or other input: <code>git</code> <code>write-tree</code> will take the
 852 current index state, and write an object that describes that whole
 853 index. In other words, we&#8217;re now tying together all the different
 854 filenames with their contents (and their permissions), and we&#8217;re
 855 creating the equivalent of a Git "directory" object:</p>
 856 </div>
 857 <div class="listingblock">
 858 <div class="content">
 859 <pre>$ git write-tree</pre>
 860 </div>
 861 </div>
 862 <div class="paragraph">
 863 <p>and this will just output the name of the resulting tree, in this case
 864 (if you have done exactly as I&#8217;ve described) it should be</p>
 865 </div>
 866 <div class="listingblock">
 867 <div class="content">
 868 <pre>8988da15d077d4829fc51d8544c097def6644dbb</pre>
 869 </div>
 870 </div>
 871 <div class="paragraph">
 872 <p>which is another incomprehensible object name. Again, if you want to,
 873 you can use <code>git</code> <code>cat-file</code> <code>-t</code> <code>8988d..</code>. to see that this time the object
 874 is not a "blob" object, but a "tree" object (you can also use
 875 <code>git</code> <code>cat-file</code> to actually output the raw object contents, but you&#8217;ll see
 876 mainly a binary mess, so that&#8217;s less interesting).</p>
 877 </div>
 878 <div class="paragraph">
 879 <p>However&#8201;&#8212;&#8201;normally you&#8217;d never use <em>git write-tree</em> on its own, because
 880 normally you always commit a tree into a commit object using the
 881 <em>git commit-tree</em> command. In fact, it&#8217;s easier to not actually use
 882 <em>git write-tree</em> on its own at all, but to just pass its result in as an
 883 argument to <em>git commit-tree</em>.</p>
 884 </div>
 885 <div class="paragraph">
 886 <p><em>git commit-tree</em> normally takes several arguments&#8201;&#8212;&#8201;it wants to know
 887 what the <em>parent</em> of a commit was, but since this is the first commit
 888 ever in this new repository, and it has no parents, we only need to pass in
 889 the object name of the tree. However, <em>git commit-tree</em> also wants to get a
 890 commit message on its standard input, and it will write out the resulting
 891 object name for the commit to its standard output.</p>
 892 </div>
 893 <div class="paragraph">
 894 <p>And this is where we create the .<code>git/refs/heads/master</code> file
 895 which is pointed at by <code>HEAD</code>. This file is supposed to contain
 896 the reference to the top-of-tree of the master branch, and since
 897 that&#8217;s exactly what <em>git commit-tree</em> spits out, we can do this
 898 all with a sequence of simple shell commands:</p>
 899 </div>
 900 <div class="listingblock">
 901 <div class="content">
 902 <pre>$ tree=$(git write-tree)
 903 $ commit=$(echo 'Initial commit' | git commit-tree $tree)
 904 $ git update-ref HEAD $commit</pre>
 905 </div>
 906 </div>
 907 <div class="paragraph">
 908 <p>In this case this creates a totally new commit that is not related to
 909 anything else. Normally you do this only <strong>once</strong> for a project ever, and
 910 all later commits will be parented on top of an earlier commit.</p>
 911 </div>
 912 <div class="paragraph">
 913 <p>Again, normally you&#8217;d never actually do this by hand. There is a
 914 helpful script called <code>git</code> <code>commit</code> that will do all of this for you. So
 915 you could have just written <code>git</code> <code>commit</code>
 916 instead, and it would have done the above magic scripting for you.</p>
 917 </div>
 918 </div>
 919 </div>
 920 <div class="sect1">
 921 <h2 id="_making_a_change">Making a change</h2>
 922 <div class="sectionbody">
 923 <div class="paragraph">
 924 <p>Remember how we did the <em>git update-index</em> on file <code>hello</code> and then we
 925 changed <code>hello</code> afterward, and could compare the new state of <code>hello</code> with the
 926 state we saved in the index file?</p>
 927 </div>
 928 <div class="paragraph">
 929 <p>Further, remember how I said that <em>git write-tree</em> writes the contents
 930 of the <strong>index</strong> file to the tree, and thus what we just committed was in
 931 fact the <strong>original</strong> contents of the file <code>hello</code>, not the new ones. We did
 932 that on purpose, to show the difference between the index state, and the
 933 state in the working tree, and how they don&#8217;t have to match, even
 934 when we commit things.</p>
 935 </div>
 936 <div class="paragraph">
 937 <p>As before, if we do <code>git</code> <code>diff-files</code> <code>-p</code> in our git-tutorial project,
 938 we&#8217;ll still see the same difference we saw last time: the index file
 939 hasn&#8217;t changed by the act of committing anything. However, now that we
 940 have committed something, we can also learn to use a new command:
 941 <em>git diff-index</em>.</p>
 942 </div>
 943 <div class="paragraph">
 944 <p>Unlike <em>git diff-files</em>, which showed the difference between the index
 945 file and the working tree, <em>git diff-index</em> shows the differences
 946 between a committed <strong>tree</strong> and either the index file or the working
 947 tree. In other words, <em>git diff-index</em> wants a tree to be diffed
 948 against, and before we did the commit, we couldn&#8217;t do that, because we
 949 didn&#8217;t have anything to diff against.</p>
 950 </div>
 951 <div class="paragraph">
 952 <p>But now we can do</p>
 953 </div>
 954 <div class="listingblock">
 955 <div class="content">
 956 <pre>$ git diff-index -p HEAD</pre>
 957 </div>
 958 </div>
 959 <div class="paragraph">
 960 <p>(where <code>-p</code> has the same meaning as it did in <em>git diff-files</em>), and it
 961 will show us the same difference, but for a totally different reason.
 962 Now we&#8217;re comparing the working tree not against the index file,
 963 but against the tree we just wrote. It just so happens that those two
 964 are obviously the same, so we get the same result.</p>
 965 </div>
 966 <div class="paragraph">
 967 <p>Again, because this is a common operation, you can also just shorthand
 968 it with</p>
 969 </div>
 970 <div class="listingblock">
 971 <div class="content">
 972 <pre>$ git diff HEAD</pre>
 973 </div>
 974 </div>
 975 <div class="paragraph">
 976 <p>which ends up doing the above for you.</p>
 977 </div>
 978 <div class="paragraph">
 979 <p>In other words, <em>git diff-index</em> normally compares a tree against the
 980 working tree, but when given the <code>--cached</code> flag, it is told to
 981 instead compare against just the index cache contents, and ignore the
 982 current working tree state entirely. Since we just wrote the index
 983 file to HEAD, doing <code>git</code> <code>diff-index</code> <code>--cached</code> <code>-p</code> <code>HEAD</code> should thus return
 984 an empty set of differences, and that&#8217;s exactly what it does.</p>
 985 </div>
 986 <div class="admonitionblock note">
 987 <table>
 988 <tr>
 989 <td class="icon">
 990 <div class="title">Note</div>
 991 </td>
 992 <td class="content">
 993 <div class="paragraph">
 994 <p><em>git diff-index</em> really always uses the index for its
 995 comparisons, and saying that it compares a tree against the working
 996 tree is thus not strictly accurate. In particular, the list of
 997 files to compare (the "meta-data") <strong>always</strong> comes from the index file,
 998 regardless of whether the <code>--cached</code> flag is used or not. The <code>--cached</code>
 999 flag really only determines whether the file <strong>contents</strong> to be compared
1000 come from the working tree or not.</p>
1001 </div>
1002 <div class="paragraph">
1003 <p>This is not hard to understand, as soon as you realize that Git simply
1004 never knows (or cares) about files that it is not told about
1005 explicitly. Git will never go <strong>looking</strong> for files to compare, it
1006 expects you to tell it what the files are, and that&#8217;s what the index
1007 is there for.</p>
1008 </div>
1009 </td>
1010 </tr>
1011 </table>
1012 </div>
1013 <div class="paragraph">
1014 <p>However, our next step is to commit the <strong>change</strong> we did, and again, to
1015 understand what&#8217;s going on, keep in mind the difference between "working
1016 tree contents", "index file" and "committed tree". We have changes
1017 in the working tree that we want to commit, and we always have to
1018 work through the index file, so the first thing we need to do is to
1019 update the index cache:</p>
1020 </div>
1021 <div class="listingblock">
1022 <div class="content">
1023 <pre>$ git update-index hello</pre>
1024 </div>
1025 </div>
1026 <div class="paragraph">
1027 <p>(note how we didn&#8217;t need the <code>--add</code> flag this time, since Git knew
1028 about the file already).</p>
1029 </div>
1030 <div class="paragraph">
1031 <p>Note what happens to the different <em>git diff-*</em> versions here.
1032 After we&#8217;ve updated <code>hello</code> in the index, <code>git</code> <code>diff-files</code> <code>-p</code> now shows no
1033 differences, but <code>git</code> <code>diff-index</code> <code>-p</code> <code>HEAD</code> still <strong>does</strong> show that the
1034 current state is different from the state we committed. In fact, now
1035 <em>git diff-index</em> shows the same difference whether we use the <code>--cached</code>
1036 flag or not, since now the index is coherent with the working tree.</p>
1037 </div>
1038 <div class="paragraph">
1039 <p>Now, since we&#8217;ve updated <code>hello</code> in the index, we can commit the new
1040 version. We could do it by writing the tree by hand again, and
1041 committing the tree (this time we&#8217;d have to use the <code>-p</code> <code>HEAD</code> flag to
1042 tell commit that the HEAD was the <strong>parent</strong> of the new commit, and that
1043 this wasn&#8217;t an initial commit any more), but you&#8217;ve done that once
1044 already, so let&#8217;s just use the helpful script this time:</p>
1045 </div>
1046 <div class="listingblock">
1047 <div class="content">
1048 <pre>$ git commit</pre>
1049 </div>
1050 </div>
1051 <div class="paragraph">
1052 <p>which starts an editor for you to write the commit message and tells you
1053 a bit about what you have done.</p>
1054 </div>
1055 <div class="paragraph">
1056 <p>Write whatever message you want, and all the lines that start with <em>#</em>
1057 will be pruned out, and the rest will be used as the commit message for
1058 the change. If you decide you don&#8217;t want to commit anything after all at
1059 this point (you can continue to edit things and update the index), you
1060 can just leave an empty message. Otherwise <code>git</code> <code>commit</code> will commit
1061 the change for you.</p>
1062 </div>
1063 <div class="paragraph">
1064 <p>You&#8217;ve now made your first real Git commit. And if you&#8217;re interested in
1065 looking at what <code>git</code> <code>commit</code> really does, feel free to investigate:
1066 it&#8217;s a few very simple shell scripts to generate the helpful (?) commit
1067 message headers, and a few one-liners that actually do the
1068 commit itself (<em>git commit</em>).</p>
1069 </div>
1070 </div>
1071 </div>
1072 <div class="sect1">
1073 <h2 id="_inspecting_changes">Inspecting Changes</h2>
1074 <div class="sectionbody">
1075 <div class="paragraph">
1076 <p>While creating changes is useful, it&#8217;s even more useful if you can tell
1077 later what changed. The most useful command for this is another of the
1078 <em>diff</em> family, namely <em>git diff-tree</em>.</p>
1079 </div>
1080 <div class="paragraph">
1081 <p><em>git diff-tree</em> can be given two arbitrary trees, and it will tell you the
1082 differences between them. Perhaps even more commonly, though, you can
1083 give it just a single commit object, and it will figure out the parent
1084 of that commit itself, and show the difference directly. Thus, to get
1085 the same diff that we&#8217;ve already seen several times, we can now do</p>
1086 </div>
1087 <div class="listingblock">
1088 <div class="content">
1089 <pre>$ git diff-tree -p HEAD</pre>
1090 </div>
1091 </div>
1092 <div class="paragraph">
1093 <p>(again, <code>-p</code> means to show the difference as a human-readable patch),
1094 and it will show what the last commit (in <code>HEAD</code>) actually changed.</p>
1095 </div>
1096 <div class="admonitionblock note">
1097 <table>
1098 <tr>
1099 <td class="icon">
1100 <div class="title">Note</div>
1101 </td>
1102 <td class="content">
1103 <div class="paragraph">
1104 <p>Here is an ASCII art by Jon Loeliger that illustrates how
1105 various <em>diff-*</em> commands compare things.</p>
1106 </div>
1107 <div class="literalblock">
1108 <div class="content">
1109 <pre>            diff-tree
1110              +----+
1111              |    |
1112              |    |
1113              V    V
1114           +-----------+
1115           | Object DB |
1116           |  Backing  |
1117           |   Store   |
1118           +-----------+
1119             ^    ^
1120             |    |
1121             |    |  diff-index --cached
1122             |    |
1123 diff-index  |    V
1124             |  +-----------+
1125             |  |   Index   |
1126             |  |  "cache"  |
1127             |  +-----------+
1128             |    ^
1129             |    |
1130             |    |  diff-files
1131             |    |
1132             V    V
1133           +-----------+
1134           |  Working  |
1135           | Directory |
1136           +-----------+</pre>
1137 </div>
1138 </div>
1139 </td>
1140 </tr>
1141 </table>
1142 </div>
1143 <div class="paragraph">
1144 <p>More interestingly, you can also give <em>git diff-tree</em> the <code>--pretty</code> flag,
1145 which tells it to also show the commit message and author and date of the
1146 commit, and you can tell it to show a whole series of diffs.
1147 Alternatively, you can tell it to be "silent", and not show the diffs at
1148 all, but just show the actual commit message.</p>
1149 </div>
1150 <div class="paragraph">
1151 <p>In fact, together with the <em>git rev-list</em> program (which generates a
1152 list of revisions), <em>git diff-tree</em> ends up being a veritable fount of
1153 changes.  You can emulate <code>git</code> <code>log</code>, <code>git</code> <code>log</code> <code>-p</code>, etc. with a trivial
1154 script that pipes the output of <code>git</code> <code>rev-list</code> to <code>git</code> <code>diff-tree</code> <code>--stdin</code>,
1155 which was exactly how early versions of <code>git</code> <code>log</code> were implemented.</p>
1156 </div>
1157 </div>
1158 </div>
1159 <div class="sect1">
1160 <h2 id="_tagging_a_version">Tagging a version</h2>
1161 <div class="sectionbody">
1162 <div class="paragraph">
1163 <p>In Git, there are two kinds of tags, a "light" one, and an "annotated tag".</p>
1164 </div>
1165 <div class="paragraph">
1166 <p>A "light" tag is technically nothing more than a branch, except we put
1167 it in the .<code>git/refs/tags/</code> subdirectory instead of calling it a <code>head</code>.
1168 So the simplest form of tag involves nothing more than</p>
1169 </div>
1170 <div class="listingblock">
1171 <div class="content">
1172 <pre>$ git tag my-first-tag</pre>
1173 </div>
1174 </div>
1175 <div class="paragraph">
1176 <p>which just writes the current <code>HEAD</code> into the .<code>git/refs/tags/my-first-tag</code>
1177 file, after which point you can then use this symbolic name for that
1178 particular state. You can, for example, do</p>
1179 </div>
1180 <div class="listingblock">
1181 <div class="content">
1182 <pre>$ git diff my-first-tag</pre>
1183 </div>
1184 </div>
1185 <div class="paragraph">
1186 <p>to diff your current state against that tag which at this point will
1187 obviously be an empty diff, but if you continue to develop and commit
1188 stuff, you can use your tag as an "anchor-point" to see what has changed
1189 since you tagged it.</p>
1190 </div>
1191 <div class="paragraph">
1192 <p>An "annotated tag" is actually a real Git object, and contains not only a
1193 pointer to the state you want to tag, but also a small tag name and
1194 message, along with optionally a PGP signature that says that yes,
1195 you really did
1196 that tag. You create these annotated tags with either the <code>-a</code> or
1197 <code>-s</code> flag to <em>git tag</em>:</p>
1198 </div>
1199 <div class="listingblock">
1200 <div class="content">
1201 <pre>$ git tag -s &lt;tagname&gt;</pre>
1202 </div>
1203 </div>
1204 <div class="paragraph">
1205 <p>which will sign the current <code>HEAD</code> (but you can also give it another
1206 argument that specifies the thing to tag, e.g., you could have tagged the
1207 current <code>mybranch</code> point by using <code>git</code> <code>tag</code> <em>&lt;tagname&gt;</em> <code>mybranch</code>).</p>
1208 </div>
1209 <div class="paragraph">
1210 <p>You normally only do signed tags for major releases or things
1211 like that, while the light-weight tags are useful for any marking you
1212 want to do&#8201;&#8212;&#8201;any time you decide that you want to remember a certain
1213 point, just create a private tag for it, and you have a nice symbolic
1214 name for the state at that point.</p>
1215 </div>
1216 </div>
1217 </div>
1218 <div class="sect1">
1219 <h2 id="_copying_repositories">Copying repositories</h2>
1220 <div class="sectionbody">
1221 <div class="paragraph">
1222 <p>Git repositories are normally totally self-sufficient and relocatable.
1223 Unlike CVS, for example, there is no separate notion of
1224 "repository" and "working tree". A Git repository normally <strong>is</strong> the
1225 working tree, with the local Git information hidden in the .<code>git</code>
1226 subdirectory. There is nothing else. What you see is what you got.</p>
1227 </div>
1228 <div class="admonitionblock note">
1229 <table>
1230 <tr>
1231 <td class="icon">
1232 <div class="title">Note</div>
1233 </td>
1234 <td class="content">
1235 You can tell Git to split the Git internal information from
1236 the directory that it tracks, but we&#8217;ll ignore that for now: it&#8217;s not
1237 how normal projects work, and it&#8217;s really only meant for special uses.
1238 So the mental model of "the Git information is always tied directly to
1239 the working tree that it describes" may not be technically 100%
1240 accurate, but it&#8217;s a good model for all normal use.
1241 </td>
1242 </tr>
1243 </table>
1244 </div>
1245 <div class="paragraph">
1246 <p>This has two implications:</p>
1247 </div>
1248 <div class="ulist">
1249 <ul>
1250 <li>
1251 <p>if you grow bored with the tutorial repository you created (or you&#8217;ve
1252 made a mistake and want to start all over), you can just do simple</p>
1253 <div class="listingblock">
1254 <div class="content">
1255 <pre>$ rm -rf git-tutorial</pre>
1256 </div>
1257 </div>
1258 <div class="paragraph">
1259 <p>and it will be gone. There&#8217;s no external repository, and there&#8217;s no
1260 history outside the project you created.</p>
1261 </div>
1262 </li>
1263 <li>
1264 <p>if you want to move or duplicate a Git repository, you can do so. There
1265 is <em>git clone</em> command, but if all you want to do is just to
1266 create a copy of your repository (with all the full history that
1267 went along with it), you can do so with a regular
1268 <code>cp</code> <code>-a</code> <code>git-tutorial</code> <code>new-git-tutorial</code>.</p>
1269 <div class="paragraph">
1270 <p>Note that when you&#8217;ve moved or copied a Git repository, your Git index
1271 file (which caches various information, notably some of the "stat"
1272 information for the files involved) will likely need to be refreshed.
1273 So after you do a <code>cp</code> <code>-a</code> to create a new copy, you&#8217;ll want to do</p>
1274 </div>
1275 <div class="listingblock">
1276 <div class="content">
1277 <pre>$ git update-index --refresh</pre>
1278 </div>
1279 </div>
1280 <div class="paragraph">
1281 <p>in the new repository to make sure that the index file is up to date.</p>
1282 </div>
1283 </li>
1284 </ul>
1285 </div>
1286 <div class="paragraph">
1287 <p>Note that the second point is true even across machines. You can
1288 duplicate a remote Git repository with <strong>any</strong> regular copy mechanism, be it
1289 <em>scp</em>, <em>rsync</em> or <em>wget</em>.</p>
1290 </div>
1291 <div class="paragraph">
1292 <p>When copying a remote repository, you&#8217;ll want to at a minimum update the
1293 index cache when you do this, and especially with other peoples'
1294 repositories you often want to make sure that the index cache is in some
1295 known state (you don&#8217;t know <strong>what</strong> they&#8217;ve done and not yet checked in),
1296 so usually you&#8217;ll precede the <em>git update-index</em> with a</p>
1297 </div>
1298 <div class="listingblock">
1299 <div class="content">
1300 <pre>$ git read-tree --reset HEAD
1301 $ git update-index --refresh</pre>
1302 </div>
1303 </div>
1304 <div class="paragraph">
1305 <p>which will force a total index re-build from the tree pointed to by <code>HEAD</code>.
1306 It resets the index contents to <code>HEAD</code>, and then the <em>git update-index</em>
1307 makes sure to match up all index entries with the checked-out files.
1308 If the original repository had uncommitted changes in its
1309 working tree, <code>git</code> <code>update-index</code> <code>--refresh</code> notices them and
1310 tells you they need to be updated.</p>
1311 </div>
1312 <div class="paragraph">
1313 <p>The above can also be written as simply</p>
1314 </div>
1315 <div class="listingblock">
1316 <div class="content">
1317 <pre>$ git reset</pre>
1318 </div>
1319 </div>
1320 <div class="paragraph">
1321 <p>and in fact a lot of the common Git command combinations can be scripted
1322 with the <code>git</code> <code>xyz</code> interfaces.  You can learn things by just looking
1323 at what the various git scripts do.  For example, <code>git</code> <code>reset</code> used to be
1324 the above two lines implemented in <em>git reset</em>, but some things like
1325 <em>git status</em> and <em>git commit</em> are slightly more complex scripts around
1326 the basic Git commands.</p>
1327 </div>
1328 <div class="paragraph">
1329 <p>Many (most?) public remote repositories will not contain any of
1330 the checked out files or even an index file, and will <strong>only</strong> contain the
1331 actual core Git files. Such a repository usually doesn&#8217;t even have the
1332 .<code>git</code> subdirectory, but has all the Git files directly in the
1333 repository.</p>
1334 </div>
1335 <div class="paragraph">
1336 <p>To create your own local live copy of such a "raw" Git repository, you&#8217;d
1337 first create your own subdirectory for the project, and then copy the
1338 raw repository contents into the .<code>git</code> directory. For example, to
1339 create your own copy of the Git repository, you&#8217;d do the following</p>
1340 </div>
1341 <div class="listingblock">
1342 <div class="content">
1343 <pre>$ mkdir my-git
1344 $ cd my-git
1345 $ rsync -rL rsync://rsync.kernel.org/pub/scm/git/git.git/ .git</pre>
1346 </div>
1347 </div>
1348 <div class="paragraph">
1349 <p>followed by</p>
1350 </div>
1351 <div class="listingblock">
1352 <div class="content">
1353 <pre>$ git read-tree HEAD</pre>
1354 </div>
1355 </div>
1356 <div class="paragraph">
1357 <p>to populate the index. However, now you have populated the index, and
1358 you have all the Git internal files, but you will notice that you don&#8217;t
1359 actually have any of the working tree files to work on. To get
1360 those, you&#8217;d check them out with</p>
1361 </div>
1362 <div class="listingblock">
1363 <div class="content">
1364 <pre>$ git checkout-index -u -a</pre>
1365 </div>
1366 </div>
1367 <div class="paragraph">
1368 <p>where the <code>-u</code> flag means that you want the checkout to keep the index
1369 up to date (so that you don&#8217;t have to refresh it afterward), and the
1370 <code>-a</code> flag means "check out all files" (if you have a stale copy or an
1371 older version of a checked out tree you may also need to add the <code>-f</code>
1372 flag first, to tell <em>git checkout-index</em> to <strong>force</strong> overwriting of any old
1373 files).</p>
1374 </div>
1375 <div class="paragraph">
1376 <p>Again, this can all be simplified with</p>
1377 </div>
1378 <div class="listingblock">
1379 <div class="content">
1380 <pre>$ git clone git://git.kernel.org/pub/scm/git/git.git/ my-git
1381 $ cd my-git
1382 $ git checkout</pre>
1383 </div>
1384 </div>
1385 <div class="paragraph">
1386 <p>which will end up doing all of the above for you.</p>
1387 </div>
1388 <div class="paragraph">
1389 <p>You have now successfully copied somebody else&#8217;s (mine) remote
1390 repository, and checked it out.</p>
1391 </div>
1392 </div>
1393 </div>
1394 <div class="sect1">
1395 <h2 id="_creating_a_new_branch">Creating a new branch</h2>
1396 <div class="sectionbody">
1397 <div class="paragraph">
1398 <p>Branches in Git are really nothing more than pointers into the Git
1399 object database from within the .<code>git/refs/</code> subdirectory, and as we
1400 already discussed, the <code>HEAD</code> branch is nothing but a symlink to one of
1401 these object pointers.</p>
1402 </div>
1403 <div class="paragraph">
1404 <p>You can at any time create a new branch by just picking an arbitrary
1405 point in the project history, and just writing the SHA-1 name of that
1406 object into a file under .<code>git/refs/heads/</code>. You can use any filename you
1407 want (and indeed, subdirectories), but the convention is that the
1408 "normal" branch is called <code>master</code>. That&#8217;s just a convention, though,
1409 and nothing enforces it.</p>
1410 </div>
1411 <div class="paragraph">
1412 <p>To show that as an example, let&#8217;s go back to the git-tutorial repository we
1413 used earlier, and create a branch in it. You do that by simply just
1414 saying that you want to check out a new branch:</p>
1415 </div>
1416 <div class="listingblock">
1417 <div class="content">
1418 <pre>$ git switch -c mybranch</pre>
1419 </div>
1420 </div>
1421 <div class="paragraph">
1422 <p>will create a new branch based at the current <code>HEAD</code> position, and switch
1423 to it.</p>
1424 </div>
1425 <div class="admonitionblock note">
1426 <table>
1427 <tr>
1428 <td class="icon">
1429 <div class="title">Note</div>
1430 </td>
1431 <td class="content">
1432 <div class="paragraph">
1433 <p>If you make the decision to start your new branch at some
1434 other point in the history than the current <code>HEAD</code>, you can do so by
1435 just telling <em>git switch</em> what the base of the checkout would be.
1436 In other words, if you have an earlier tag or branch, you&#8217;d just do</p>
1437 </div>
1438 <div class="listingblock">
1439 <div class="content">
1440 <pre>$ git switch -c mybranch earlier-commit</pre>
1441 </div>
1442 </div>
1443 <div class="paragraph">
1444 <p>and it would create the new branch <code>mybranch</code> at the earlier commit,
1445 and check out the state at that time.</p>
1446 </div>
1447 </td>
1448 </tr>
1449 </table>
1450 </div>
1451 <div class="paragraph">
1452 <p>You can always just jump back to your original <code>master</code> branch by doing</p>
1453 </div>
1454 <div class="listingblock">
1455 <div class="content">
1456 <pre>$ git switch master</pre>
1457 </div>
1458 </div>
1459 <div class="paragraph">
1460 <p>(or any other branch-name, for that matter) and if you forget which
1461 branch you happen to be on, a simple</p>
1462 </div>
1463 <div class="listingblock">
1464 <div class="content">
1465 <pre>$ cat .git/HEAD</pre>
1466 </div>
1467 </div>
1468 <div class="paragraph">
1469 <p>will tell you where it&#8217;s pointing.  To get the list of branches
1470 you have, you can say</p>
1471 </div>
1472 <div class="listingblock">
1473 <div class="content">
1474 <pre>$ git branch</pre>
1475 </div>
1476 </div>
1477 <div class="paragraph">
1478 <p>which used to be nothing more than a simple script around <code>ls</code> <code>.git/refs/heads</code>.
1479 There will be an asterisk in front of the branch you are currently on.</p>
1480 </div>
1481 <div class="paragraph">
1482 <p>Sometimes you may wish to create a new branch <em>without</em> actually
1483 checking it out and switching to it. If so, just use the command</p>
1484 </div>
1485 <div class="listingblock">
1486 <div class="content">
1487 <pre>$ git branch &lt;branchname&gt; [startingpoint]</pre>
1488 </div>
1489 </div>
1490 <div class="paragraph">
1491 <p>which will simply <em>create</em> the branch, but will not do anything further.
1492 You can then later&#8201;&#8212;&#8201;once you decide that you want to actually develop
1493 on that branch&#8201;&#8212;&#8201;switch to that branch with a regular <em>git switch</em>
1494 with the branchname as the argument.</p>
1495 </div>
1496 </div>
1497 </div>
1498 <div class="sect1">
1499 <h2 id="_merging_two_branches">Merging two branches</h2>
1500 <div class="sectionbody">
1501 <div class="paragraph">
1502 <p>One of the ideas of having a branch is that you do some (possibly
1503 experimental) work in it, and eventually merge it back to the main
1504 branch. So assuming you created the above <code>mybranch</code> that started out
1505 being the same as the original <code>master</code> branch, let&#8217;s make sure we&#8217;re in
1506 that branch, and do some work there.</p>
1507 </div>
1508 <div class="listingblock">
1509 <div class="content">
1510 <pre>$ git switch mybranch
1511 $ echo "Work, work, work" &gt;&gt;hello
1512 $ git commit -m "Some work." -i hello</pre>
1513 </div>
1514 </div>
1515 <div class="paragraph">
1516 <p>Here, we just added another line to <code>hello</code>, and we used a shorthand for
1517 doing both <code>git</code> <code>update-index</code> <code>hello</code> and <code>git</code> <code>commit</code> by just giving the
1518 filename directly to <code>git</code> <code>commit</code>, with an <code>-i</code> flag (it tells
1519 Git to <em>include</em> that file in addition to what you have done to
1520 the index file so far when making the commit).  The <code>-m</code> flag is to give the
1521 commit log message from the command line.</p>
1522 </div>
1523 <div class="paragraph">
1524 <p>Now, to make it a bit more interesting, let&#8217;s assume that somebody else
1525 does some work in the original branch, and simulate that by going back
1526 to the master branch, and editing the same file differently there:</p>
1527 </div>
1528 <div class="listingblock">
1529 <div class="content">
1530 <pre>$ git switch master</pre>
1531 </div>
1532 </div>
1533 <div class="paragraph">
1534 <p>Here, take a moment to look at the contents of <code>hello</code>, and notice how they
1535 don&#8217;t contain the work we just did in <code>mybranch</code>&#8201;&#8212;&#8201;because that work
1536 hasn&#8217;t happened in the <code>master</code> branch at all. Then do</p>
1537 </div>
1538 <div class="listingblock">
1539 <div class="content">
1540 <pre>$ echo "Play, play, play" &gt;&gt;hello
1541 $ echo "Lots of fun" &gt;&gt;example
1542 $ git commit -m "Some fun." -i hello example</pre>
1543 </div>
1544 </div>
1545 <div class="paragraph">
1546 <p>since the master branch is obviously in a much better mood.</p>
1547 </div>
1548 <div class="paragraph">
1549 <p>Now, you&#8217;ve got two branches, and you decide that you want to merge the
1550 work done. Before we do that, let&#8217;s introduce a cool graphical tool that
1551 helps you view what&#8217;s going on:</p>
1552 </div>
1553 <div class="listingblock">
1554 <div class="content">
1555 <pre>$ gitk --all</pre>
1556 </div>
1557 </div>
1558 <div class="paragraph">
1559 <p>will show you graphically both of your branches (that&#8217;s what the <code>--all</code>
1560 means: normally it will just show you your current <code>HEAD</code>) and their
1561 histories. You can also see exactly how they came to be from a common
1562 source.</p>
1563 </div>
1564 <div class="paragraph">
1565 <p>Anyway, let&#8217;s exit <em>gitk</em> (<code>^Q</code> or the File menu), and decide that we want
1566 to merge the work we did on the <code>mybranch</code> branch into the <code>master</code>
1567 branch (which is currently our <code>HEAD</code> too). To do that, there&#8217;s a nice
1568 script called <em>git merge</em>, which wants to know which branches you want
1569 to resolve and what the merge is all about:</p>
1570 </div>
1571 <div class="listingblock">
1572 <div class="content">
1573 <pre>$ git merge -m "Merge work in mybranch" mybranch</pre>
1574 </div>
1575 </div>
1576 <div class="paragraph">
1577 <p>where the first argument is going to be used as the commit message if
1578 the merge can be resolved automatically.</p>
1579 </div>
1580 <div class="paragraph">
1581 <p>Now, in this case we&#8217;ve intentionally created a situation where the
1582 merge will need to be fixed up by hand, though, so Git will do as much
1583 of it as it can automatically (which in this case is just merge the <code>example</code>
1584 file, which had no differences in the <code>mybranch</code> branch), and say:</p>
1585 </div>
1586 <div class="listingblock">
1587 <div class="content">
1588 <pre>        Auto-merging hello
1589         CONFLICT (content): Merge conflict in hello
1590         Automatic merge failed; fix conflicts and then commit the result.</pre>
1591 </div>
1592 </div>
1593 <div class="paragraph">
1594 <p>It tells you that it did an "Automatic merge", which
1595 failed due to conflicts in <code>hello</code>.</p>
1596 </div>
1597 <div class="paragraph">
1598 <p>Not to worry. It left the (trivial) conflict in <code>hello</code> in the same form you
1599 should already be well used to if you&#8217;ve ever used CVS, so let&#8217;s just
1600 open <code>hello</code> in our editor (whatever that may be), and fix it up somehow.
1601 I&#8217;d suggest just making it so that <code>hello</code> contains all four lines:</p>
1602 </div>
1603 <div class="listingblock">
1604 <div class="content">
1605 <pre>Hello World
1606 It's a new day for git
1607 Play, play, play
1608 Work, work, work</pre>
1609 </div>
1610 </div>
1611 <div class="paragraph">
1612 <p>and once you&#8217;re happy with your manual merge, just do a</p>
1613 </div>
1614 <div class="listingblock">
1615 <div class="content">
1616 <pre>$ git commit -i hello</pre>
1617 </div>
1618 </div>
1619 <div class="paragraph">
1620 <p>which will very loudly warn you that you&#8217;re now committing a merge
1621 (which is correct, so never mind), and you can write a small merge
1622 message about your adventures in <em>git merge</em>-land.</p>
1623 </div>
1624 <div class="paragraph">
1625 <p>After you&#8217;re done, start up <code>gitk</code> <code>--all</code> to see graphically what the
1626 history looks like. Notice that <code>mybranch</code> still exists, and you can
1627 switch to it, and continue to work with it if you want to. The
1628 <code>mybranch</code> branch will not contain the merge, but next time you merge it
1629 from the <code>master</code> branch, Git will know how you merged it, so you&#8217;ll not
1630 have to do <em>that</em> merge again.</p>
1631 </div>
1632 <div class="paragraph">
1633 <p>Another useful tool, especially if you do not always work in X-Window
1634 environment, is <code>git</code> <code>show-branch</code>.</p>
1635 </div>
1636 <div class="listingblock">
1637 <div class="content">
1638 <pre>$ git show-branch --topo-order --more=1 master mybranch
1639 * [master] Merge work in mybranch
1640  ! [mybranch] Some work.
1641 --
1642 -  [master] Merge work in mybranch
1643 *+ [mybranch] Some work.
1644 *  [master^] Some fun.</pre>
1645 </div>
1646 </div>
1647 <div class="paragraph">
1648 <p>The first two lines indicate that it is showing the two branches
1649 with the titles of their top-of-the-tree commits, you are currently on
1650 <code>master</code> branch (notice the asterisk * character), and the first
1651 column for the later output lines is used to show commits contained in the
1652 <code>master</code> branch, and the second column for the <code>mybranch</code>
1653 branch. Three commits are shown along with their titles.
1654 All of them have non blank characters in the first column (*
1655 shows an ordinary commit on the current branch, <code>-</code> is a merge commit), which
1656 means they are now part of the <code>master</code> branch. Only the "Some
1657 work" commit has the plus <code>+</code> character in the second column,
1658 because <code>mybranch</code> has not been merged to incorporate these
1659 commits from the master branch.  The string inside brackets
1660 before the commit log message is a short name you can use to
1661 name the commit.  In the above example, <em>master</em> and <em>mybranch</em>
1662 are branch heads.  <em>master^</em> is the first parent of <em>master</em>
1663 branch head.  Please see <a href="gitrevisions.html">gitrevisions(7)</a> if you want to
1664 see more complex cases.</p>
1665 </div>
1666 <div class="admonitionblock note">
1667 <table>
1668 <tr>
1669 <td class="icon">
1670 <div class="title">Note</div>
1671 </td>
1672 <td class="content">
1673 Without the <em>--more=1</em> option, <em>git show-branch</em> would not output the
1674 <em>[master^]</em> commit, as <em>[mybranch]</em> commit is a common ancestor of
1675 both <em>master</em> and <em>mybranch</em> tips.  Please see <a href="git-show-branch.html">git-show-branch(1)</a>
1676 for details.
1677 </td>
1678 </tr>
1679 </table>
1680 </div>
1681 <div class="admonitionblock note">
1682 <table>
1683 <tr>
1684 <td class="icon">
1685 <div class="title">Note</div>
1686 </td>
1687 <td class="content">
1688 If there were more commits on the <em>master</em> branch after the merge, the
1689 merge commit itself would not be shown by <em>git show-branch</em> by
1690 default.  You would need to provide <code>--sparse</code> option to make the
1691 merge commit visible in this case.
1692 </td>
1693 </tr>
1694 </table>
1695 </div>
1696 <div class="paragraph">
1697 <p>Now, let&#8217;s pretend you are the one who did all the work in
1698 <code>mybranch</code>, and the fruit of your hard work has finally been merged
1699 to the <code>master</code> branch. Let&#8217;s go back to <code>mybranch</code>, and run
1700 <em>git merge</em> to get the "upstream changes" back to your branch.</p>
1701 </div>
1702 <div class="listingblock">
1703 <div class="content">
1704 <pre>$ git switch mybranch
1705 $ git merge -m "Merge upstream changes." master</pre>
1706 </div>
1707 </div>
1708 <div class="paragraph">
1709 <p>This outputs something like this (the actual commit object names
1710 would be different)</p>
1711 </div>
1712 <div class="listingblock">
1713 <div class="content">
1714 <pre>Updating from ae3a2da... to a80b4aa....
1715 Fast-forward (no commit created; -m option ignored)
1716  example | 1 +
1717  hello   | 1 +
1718  2 files changed, 2 insertions(+)</pre>
1719 </div>
1720 </div>
1721 <div class="paragraph">
1722 <p>Because your branch did not contain anything more than what had
1723 already been merged into the <code>master</code> branch, the merge operation did
1724 not actually do a merge. Instead, it just updated the top of
1725 the tree of your branch to that of the <code>master</code> branch. This is
1726 often called <em>fast-forward</em> merge.</p>
1727 </div>
1728 <div class="paragraph">
1729 <p>You can run <code>gitk</code> <code>--all</code> again to see how the commit ancestry
1730 looks like, or run <em>show-branch</em>, which tells you this.</p>
1731 </div>
1732 <div class="listingblock">
1733 <div class="content">
1734 <pre>$ git show-branch master mybranch
1735 ! [master] Merge work in mybranch
1736  * [mybranch] Merge work in mybranch
1737 --
1738 -- [master] Merge work in mybranch</pre>
1739 </div>
1740 </div>
1741 </div>
1742 </div>
1743 <div class="sect1">
1744 <h2 id="_merging_external_work">Merging external work</h2>
1745 <div class="sectionbody">
1746 <div class="paragraph">
1747 <p>It&#8217;s usually much more common that you merge with somebody else than
1748 merging with your own branches, so it&#8217;s worth pointing out that Git
1749 makes that very easy too, and in fact, it&#8217;s not that different from
1750 doing a <em>git merge</em>. In fact, a remote merge ends up being nothing
1751 more than "fetch the work from a remote repository into a temporary tag"
1752 followed by a <em>git merge</em>.</p>
1753 </div>
1754 <div class="paragraph">
1755 <p>Fetching from a remote repository is done by, unsurprisingly,
1756 <em>git fetch</em>:</p>
1757 </div>
1758 <div class="listingblock">
1759 <div class="content">
1760 <pre>$ git fetch &lt;remote-repository&gt;</pre>
1761 </div>
1762 </div>
1763 <div class="paragraph">
1764 <p>One of the following transports can be used to name the
1765 repository to download from:</p>
1766 </div>
1767 <div class="dlist">
1768 <dl>
1769 <dt class="hdlist1">SSH</dt>
1770 <dd>
1771 <p><code>remote.machine:/path/to/repo.git/</code> or</p>
1772 <div class="paragraph">
1773 <p><code>ssh://remote.machine/path/to/repo.git/</code></p>
1774 </div>
1775 <div class="paragraph">
1776 <p>This transport can be used for both uploading and downloading,
1777 and requires you to have a log-in privilege over <code>ssh</code> to the
1778 remote machine.  It finds out the set of objects the other side
1779 lacks by exchanging the head commits both ends have and
1780 transfers (close to) minimum set of objects.  It is by far the
1781 most efficient way to exchange Git objects between repositories.</p>
1782 </div>
1783 </dd>
1784 <dt class="hdlist1">Local directory</dt>
1785 <dd>
1786 <p><code>/path/to/repo.git/</code></p>
1787 <div class="paragraph">
1788 <p>This transport is the same as SSH transport but uses <em>sh</em> to run
1789 both ends on the local machine instead of running other end on
1790 the remote machine via <em>ssh</em>.</p>
1791 </div>
1792 </dd>
1793 <dt class="hdlist1">Git Native</dt>
1794 <dd>
1795 <p><code>git://remote.machine/path/to/repo.git/</code></p>
1796 <div class="paragraph">
1797 <p>This transport was designed for anonymous downloading.  Like SSH
1798 transport, it finds out the set of objects the downstream side
1799 lacks and transfers (close to) minimum set of objects.</p>
1800 </div>
1801 </dd>
1802 <dt class="hdlist1">HTTP(S)</dt>
1803 <dd>
1804 <p><code>http://remote.machine/path/to/repo.git/</code></p>
1805 <div class="paragraph">
1806 <p>Downloader from http and https URL
1807 first obtains the topmost commit object name from the remote site
1808 by looking at the specified refname under <code>repo.git/refs/</code> directory,
1809 and then tries to obtain the
1810 commit object by downloading from <code>repo.git/objects/xx/xxx..</code>.
1811 using the object name of that commit object.  Then it reads the
1812 commit object to find out its parent commits and the associate
1813 tree object; it repeats this process until it gets all the
1814 necessary objects.  Because of this behavior, they are
1815 sometimes also called <em>commit walkers</em>.</p>
1816 </div>
1817 <div class="paragraph">
1818 <p>The <em>commit walkers</em> are sometimes also called <em>dumb
1819 transports</em>, because they do not require any Git aware smart
1820 server like Git Native transport does.  Any stock HTTP server
1821 that does not even support directory index would suffice.  But
1822 you must prepare your repository with <em>git update-server-info</em>
1823 to help dumb transport downloaders.</p>
1824 </div>
1825 </dd>
1826 </dl>
1827 </div>
1828 <div class="paragraph">
1829 <p>Once you fetch from the remote repository, you <code>merge</code> that
1830 with your current branch.</p>
1831 </div>
1832 <div class="paragraph">
1833 <p>However&#8201;&#8212;&#8201;it&#8217;s such a common thing to <code>fetch</code> and then
1834 immediately <code>merge</code>, that it&#8217;s called <code>git</code> <code>pull</code>, and you can
1835 simply do</p>
1836 </div>
1837 <div class="listingblock">
1838 <div class="content">
1839 <pre>$ git pull &lt;remote-repository&gt;</pre>
1840 </div>
1841 </div>
1842 <div class="paragraph">
1843 <p>and optionally give a branch-name for the remote end as a second
1844 argument.</p>
1845 </div>
1846 <div class="admonitionblock note">
1847 <table>
1848 <tr>
1849 <td class="icon">
1850 <div class="title">Note</div>
1851 </td>
1852 <td class="content">
1853 You could do without using any branches at all, by
1854 keeping as many local repositories as you would like to have
1855 branches, and merging between them with <em>git pull</em>, just like
1856 you merge between branches. The advantage of this approach is
1857 that it lets you keep a set of files for each <code>branch</code> checked
1858 out and you may find it easier to switch back and forth if you
1859 juggle multiple lines of development simultaneously. Of
1860 course, you will pay the price of more disk usage to hold
1861 multiple working trees, but disk space is cheap these days.
1862 </td>
1863 </tr>
1864 </table>
1865 </div>
1866 <div class="paragraph">
1867 <p>It is likely that you will be pulling from the same remote
1868 repository from time to time. As a short hand, you can store
1869 the remote repository URL in the local repository&#8217;s config file
1870 like this:</p>
1871 </div>
1872 <div class="listingblock">
1873 <div class="content">
1874 <pre>$ git config remote.linus.url https://git.kernel.org/pub/scm/git/git.git/</pre>
1875 </div>
1876 </div>
1877 <div class="paragraph">
1878 <p>and use the "linus" keyword with <em>git pull</em> instead of the full URL.</p>
1879 </div>
1880 <div class="paragraph">
1881 <p>Examples.</p>
1882 </div>
1883 <div class="olist arabic">
1884 <ol class="arabic">
1885 <li>
1886 <p><code>git</code> <code>pull</code> <code>linus</code></p>
1887 </li>
1888 <li>
1889 <p><code>git</code> <code>pull</code> <code>linus</code> <code>tag</code> <code>v0.99.1</code></p>
1890 </li>
1891 </ol>
1892 </div>
1893 <div class="paragraph">
1894 <p>the above are equivalent to:</p>
1895 </div>
1896 <div class="olist arabic">
1897 <ol class="arabic">
1898 <li>
1899 <p><code>git</code> <code>pull</code> <code>http://www.kernel.org/pub/scm/git/git.git/</code> <code>HEAD</code></p>
1900 </li>
1901 <li>
1902 <p><code>git</code> <code>pull</code> <code>http://www.kernel.org/pub/scm/git/git.git/</code> <code>tag</code> <code>v0.99.1</code></p>
1903 </li>
1904 </ol>
1905 </div>
1906 </div>
1907 </div>
1908 <div class="sect1">
1909 <h2 id="_how_does_the_merge_work">How does the merge work?</h2>
1910 <div class="sectionbody">
1911 <div class="paragraph">
1912 <p>We said this tutorial shows what plumbing does to help you cope
1913 with the porcelain that isn&#8217;t flushing, but we so far did not
1914 talk about how the merge really works.  If you are following
1915 this tutorial the first time, I&#8217;d suggest to skip to "Publishing
1916 your work" section and come back here later.</p>
1917 </div>
1918 <div class="paragraph">
1919 <p>OK, still with me?  To give us an example to look at, let&#8217;s go
1920 back to the earlier repository with "hello" and "example" file,
1921 and bring ourselves back to the pre-merge state:</p>
1922 </div>
1923 <div class="listingblock">
1924 <div class="content">
1925 <pre>$ git show-branch --more=2 master mybranch
1926 ! [master] Merge work in mybranch
1927  * [mybranch] Merge work in mybranch
1928 --
1929 -- [master] Merge work in mybranch
1930 +* [master^2] Some work.
1931 +* [master^] Some fun.</pre>
1932 </div>
1933 </div>
1934 <div class="paragraph">
1935 <p>Remember, before running <em>git merge</em>, our <code>master</code> head was at
1936 "Some fun." commit, while our <code>mybranch</code> head was at "Some
1937 work." commit.</p>
1938 </div>
1939 <div class="listingblock">
1940 <div class="content">
1941 <pre>$ git switch -C mybranch master^2
1942 $ git switch master
1943 $ git reset --hard master^</pre>
1944 </div>
1945 </div>
1946 <div class="paragraph">
1947 <p>After rewinding, the commit structure should look like this:</p>
1948 </div>
1949 <div class="listingblock">
1950 <div class="content">
1951 <pre>$ git show-branch
1952 * [master] Some fun.
1953  ! [mybranch] Some work.
1954 --
1955 *  [master] Some fun.
1956  + [mybranch] Some work.
1957 *+ [master^] Initial commit</pre>
1958 </div>
1959 </div>
1960 <div class="paragraph">
1961 <p>Now we are ready to experiment with the merge by hand.</p>
1962 </div>
1963 <div class="paragraph">
1964 <p><code>git</code> <code>merge</code> command, when merging two branches, uses 3-way merge
1965 algorithm.  First, it finds the common ancestor between them.
1966 The command it uses is <em>git merge-base</em>:</p>
1967 </div>
1968 <div class="listingblock">
1969 <div class="content">
1970 <pre>$ mb=$(git merge-base HEAD mybranch)</pre>
1971 </div>
1972 </div>
1973 <div class="paragraph">
1974 <p>The command writes the commit object name of the common ancestor
1975 to the standard output, so we captured its output to a variable,
1976 because we will be using it in the next step.  By the way, the common
1977 ancestor commit is the "Initial commit" commit in this case.  You can
1978 tell it by:</p>
1979 </div>
1980 <div class="listingblock">
1981 <div class="content">
1982 <pre>$ git name-rev --name-only --tags $mb
1983 my-first-tag</pre>
1984 </div>
1985 </div>
1986 <div class="paragraph">
1987 <p>After finding out a common ancestor commit, the second step is
1988 this:</p>
1989 </div>
1990 <div class="listingblock">
1991 <div class="content">
1992 <pre>$ git read-tree -m -u $mb HEAD mybranch</pre>
1993 </div>
1994 </div>
1995 <div class="paragraph">
1996 <p>This is the same <em>git read-tree</em> command we have already seen,
1997 but it takes three trees, unlike previous examples.  This reads
1998 the contents of each tree into different <em>stage</em> in the index
1999 file (the first tree goes to stage 1, the second to stage 2,
2000 etc.).  After reading three trees into three stages, the paths
2001 that are the same in all three stages are <em>collapsed</em> into stage
2002 0.  Also paths that are the same in two of three stages are
2003 collapsed into stage 0, taking the SHA-1 from either stage 2 or
2004 stage 3, whichever is different from stage 1 (i.e. only one side
2005 changed from the common ancestor).</p>
2006 </div>
2007 <div class="paragraph">
2008 <p>After <em>collapsing</em> operation, paths that are different in three
2009 trees are left in non-zero stages.  At this point, you can
2010 inspect the index file with this command:</p>
2011 </div>
2012 <div class="listingblock">
2013 <div class="content">
2014 <pre>$ git ls-files --stage
2015 100644 7f8b141b65fdcee47321e399a2598a235a032422 0       example
2016 100644 557db03de997c86a4a028e1ebd3a1ceb225be238 1       hello
2017 100644 ba42a2a96e3027f3333e13ede4ccf4498c3ae942 2       hello
2018 100644 cc44c73eb783565da5831b4d820c962954019b69 3       hello</pre>
2019 </div>
2020 </div>
2021 <div class="paragraph">
2022 <p>In our example of only two files, we did not have unchanged
2023 files so only <em>example</em> resulted in collapsing.  But in real-life
2024 large projects, when only a small number of files change in one commit,
2025 this <em>collapsing</em> tends to trivially merge most of the paths
2026 fairly quickly, leaving only a handful of real changes in non-zero
2027 stages.</p>
2028 </div>
2029 <div class="paragraph">
2030 <p>To look at only non-zero stages, use <code>--unmerged</code> flag:</p>
2031 </div>
2032 <div class="listingblock">
2033 <div class="content">
2034 <pre>$ git ls-files --unmerged
2035 100644 557db03de997c86a4a028e1ebd3a1ceb225be238 1       hello
2036 100644 ba42a2a96e3027f3333e13ede4ccf4498c3ae942 2       hello
2037 100644 cc44c73eb783565da5831b4d820c962954019b69 3       hello</pre>
2038 </div>
2039 </div>
2040 <div class="paragraph">
2041 <p>The next step of merging is to merge these three versions of the
2042 file, using 3-way merge.  This is done by giving
2043 <em>git merge-one-file</em> command as one of the arguments to
2044 <em>git merge-index</em> command:</p>
2045 </div>
2046 <div class="listingblock">
2047 <div class="content">
2048 <pre>$ git merge-index git-merge-one-file hello
2049 Auto-merging hello
2050 ERROR: Merge conflict in hello
2051 fatal: merge program failed</pre>
2052 </div>
2053 </div>
2054 <div class="paragraph">
2055 <p><em>git merge-one-file</em> script is called with parameters to
2056 describe those three versions, and is responsible to leave the
2057 merge results in the working tree.
2058 It is a fairly straightforward shell script, and
2059 eventually calls <em>merge</em> program from RCS suite to perform a
2060 file-level 3-way merge.  In this case, <em>merge</em> detects
2061 conflicts, and the merge result with conflict marks is left in
2062 the working tree..  This can be seen if you run <code>ls-files</code>
2063 <code>--stage</code> again at this point:</p>
2064 </div>
2065 <div class="listingblock">
2066 <div class="content">
2067 <pre>$ git ls-files --stage
2068 100644 7f8b141b65fdcee47321e399a2598a235a032422 0       example
2069 100644 557db03de997c86a4a028e1ebd3a1ceb225be238 1       hello
2070 100644 ba42a2a96e3027f3333e13ede4ccf4498c3ae942 2       hello
2071 100644 cc44c73eb783565da5831b4d820c962954019b69 3       hello</pre>
2072 </div>
2073 </div>
2074 <div class="paragraph">
2075 <p>This is the state of the index file and the working file after
2076 <em>git merge</em> returns control back to you, leaving the conflicting
2077 merge for you to resolve.  Notice that the path <code>hello</code> is still
2078 unmerged, and what you see with <em>git diff</em> at this point is
2079 differences since stage 2 (i.e. your version).</p>
2080 </div>
2081 </div>
2082 </div>
2083 <div class="sect1">
2084 <h2 id="_publishing_your_work">Publishing your work</h2>
2085 <div class="sectionbody">
2086 <div class="paragraph">
2087 <p>So, we can use somebody else&#8217;s work from a remote repository, but
2088 how can <strong>you</strong> prepare a repository to let other people pull from
2089 it?</p>
2090 </div>
2091 <div class="paragraph">
2092 <p>You do your real work in your working tree that has your
2093 primary repository hanging under it as its .<code>git</code> subdirectory.
2094 You <strong>could</strong> make that repository accessible remotely and ask
2095 people to pull from it, but in practice that is not the way
2096 things are usually done. A recommended way is to have a public
2097 repository, make it reachable by other people, and when the
2098 changes you made in your primary working tree are in good shape,
2099 update the public repository from it. This is often called
2100 <em>pushing</em>.</p>
2101 </div>
2102 <div class="admonitionblock note">
2103 <table>
2104 <tr>
2105 <td class="icon">
2106 <div class="title">Note</div>
2107 </td>
2108 <td class="content">
2109 This public repository could further be mirrored, and that is
2110 how Git repositories at <code>kernel.org</code> are managed.
2111 </td>
2112 </tr>
2113 </table>
2114 </div>
2115 <div class="paragraph">
2116 <p>Publishing the changes from your local (private) repository to
2117 your remote (public) repository requires a write privilege on
2118 the remote machine. You need to have an SSH account there to
2119 run a single command, <em>git-receive-pack</em>.</p>
2120 </div>
2121 <div class="paragraph">
2122 <p>First, you need to create an empty repository on the remote
2123 machine that will house your public repository. This empty
2124 repository will be populated and be kept up to date by pushing
2125 into it later. Obviously, this repository creation needs to be
2126 done only once.</p>
2127 </div>
2128 <div class="admonitionblock note">
2129 <table>
2130 <tr>
2131 <td class="icon">
2132 <div class="title">Note</div>
2133 </td>
2134 <td class="content">
2135 <em>git push</em> uses a pair of commands,
2136 <em>git send-pack</em> on your local machine, and <em>git-receive-pack</em>
2137 on the remote machine. The communication between the two over
2138 the network internally uses an SSH connection.
2139 </td>
2140 </tr>
2141 </table>
2142 </div>
2143 <div class="paragraph">
2144 <p>Your private repository&#8217;s Git directory is usually .<code>git</code>, but
2145 your public repository is often named after the project name,
2146 i.e. <em>&lt;project&gt;</em><code>.git</code>. Let&#8217;s create such a public repository for
2147 project <code>my-git</code>. After logging into the remote machine, create
2148 an empty directory:</p>
2149 </div>
2150 <div class="listingblock">
2151 <div class="content">
2152 <pre>$ mkdir my-git.git</pre>
2153 </div>
2154 </div>
2155 <div class="paragraph">
2156 <p>Then, make that directory into a Git repository by running
2157 <em>git init</em>, but this time, since its name is not the usual
2158 .<code>git</code>, we do things slightly differently:</p>
2159 </div>
2160 <div class="listingblock">
2161 <div class="content">
2162 <pre>$ GIT_DIR=my-git.git git init</pre>
2163 </div>
2164 </div>
2165 <div class="paragraph">
2166 <p>Make sure this directory is available for others you want your
2167 changes to be pulled via the transport of your choice. Also
2168 you need to make sure that you have the <em>git-receive-pack</em>
2169 program on the <code>$PATH</code>.</p>
2170 </div>
2171 <div class="admonitionblock note">
2172 <table>
2173 <tr>
2174 <td class="icon">
2175 <div class="title">Note</div>
2176 </td>
2177 <td class="content">
2178 Many installations of sshd do not invoke your shell as the login
2179 shell when you directly run programs; what this means is that if
2180 your login shell is <em>bash</em>, only .<code>bashrc</code> is read and not
2181 .<code>bash_profile</code>. As a workaround, make sure .<code>bashrc</code> sets up
2182 <code>$PATH</code> so that you can run <em>git-receive-pack</em> program.
2183 </td>
2184 </tr>
2185 </table>
2186 </div>
2187 <div class="admonitionblock note">
2188 <table>
2189 <tr>
2190 <td class="icon">
2191 <div class="title">Note</div>
2192 </td>
2193 <td class="content">
2194 If you plan to publish this repository to be accessed over http,
2195 you should do <code>mv</code> <code>my-git.git/hooks/post-update.sample</code>
2196 <code>my-git.git/hooks/post-update</code> at this point.
2197 This makes sure that every time you push into this
2198 repository, <code>git</code> <code>update-server-info</code> is run.
2199 </td>
2200 </tr>
2201 </table>
2202 </div>
2203 <div class="paragraph">
2204 <p>Your "public repository" is now ready to accept your changes.
2205 Come back to the machine you have your private repository. From
2206 there, run this command:</p>
2207 </div>
2208 <div class="listingblock">
2209 <div class="content">
2210 <pre>$ git push &lt;public-host&gt;:/path/to/my-git.git master</pre>
2211 </div>
2212 </div>
2213 <div class="paragraph">
2214 <p>This synchronizes your public repository to match the named
2215 branch head (i.e. <code>master</code> in this case) and objects reachable
2216 from them in your current repository.</p>
2217 </div>
2218 <div class="paragraph">
2219 <p>As a real example, this is how I update my public Git
2220 repository. Kernel.org mirror network takes care of the
2221 propagation to other publicly visible machines:</p>
2222 </div>
2223 <div class="listingblock">
2224 <div class="content">
2225 <pre>$ git push master.kernel.org:/pub/scm/git/git.git/</pre>
2226 </div>
2227 </div>
2228 </div>
2229 </div>
2230 <div class="sect1">
2231 <h2 id="_packing_your_repository">Packing your repository</h2>
2232 <div class="sectionbody">
2233 <div class="paragraph">
2234 <p>Earlier, we saw that one file under .<code>git/objects/</code>??/ directory
2235 is stored for each Git object you create. This representation
2236 is efficient to create atomically and safely, but
2237 not so convenient to transport over the network. Since Git objects are
2238 immutable once they are created, there is a way to optimize the
2239 storage by "packing them together". The command</p>
2240 </div>
2241 <div class="listingblock">
2242 <div class="content">
2243 <pre>$ git repack</pre>
2244 </div>
2245 </div>
2246 <div class="paragraph">
2247 <p>will do it for you. If you followed the tutorial examples, you
2248 would have accumulated about 17 objects in .<code>git/objects/</code>??/
2249 directories by now. <em>git repack</em> tells you how many objects it
2250 packed, and stores the packed file in the .<code>git/objects/pack</code>
2251 directory.</p>
2252 </div>
2253 <div class="admonitionblock note">
2254 <table>
2255 <tr>
2256 <td class="icon">
2257 <div class="title">Note</div>
2258 </td>
2259 <td class="content">
2260 You will see two files, <code>pack-</code>*.<code>pack</code> and <code>pack-</code>*.<code>idx</code>,
2261 in .<code>git/objects/pack</code> directory. They are closely related to
2262 each other, and if you ever copy them by hand to a different
2263 repository for whatever reason, you should make sure you copy
2264 them together. The former holds all the data from the objects
2265 in the pack, and the latter holds the index for random
2266 access.
2267 </td>
2268 </tr>
2269 </table>
2270 </div>
2271 <div class="paragraph">
2272 <p>If you are paranoid, running <em>git verify-pack</em> command would
2273 detect if you have a corrupt pack, but do not worry too much.
2274 Our programs are always perfect ;-).</p>
2275 </div>
2276 <div class="paragraph">
2277 <p>Once you have packed objects, you do not need to leave the
2278 unpacked objects that are contained in the pack file anymore.</p>
2279 </div>
2280 <div class="listingblock">
2281 <div class="content">
2282 <pre>$ git prune-packed</pre>
2283 </div>
2284 </div>
2285 <div class="paragraph">
2286 <p>would remove them for you.</p>
2287 </div>
2288 <div class="paragraph">
2289 <p>You can try running <code>find</code> <code>.git/objects</code> <code>-type</code> <code>f</code> before and after
2290 you run <code>git</code> <code>prune-packed</code> if you are curious.  Also <code>git</code>
2291 <code>count-objects</code> would tell you how many unpacked objects are in
2292 your repository and how much space they are consuming.</p>
2293 </div>
2294 <div class="admonitionblock note">
2295 <table>
2296 <tr>
2297 <td class="icon">
2298 <div class="title">Note</div>
2299 </td>
2300 <td class="content">
2301 <code>git</code> <code>pull</code> is slightly cumbersome for HTTP transport, as a
2302 packed repository may contain relatively few objects in a
2303 relatively large pack. If you expect many HTTP pulls from your
2304 public repository you might want to repack &amp; prune often, or
2305 never.
2306 </td>
2307 </tr>
2308 </table>
2309 </div>
2310 <div class="paragraph">
2311 <p>If you run <code>git</code> <code>repack</code> again at this point, it will say
2312 "Nothing new to pack.". Once you continue your development and
2313 accumulate the changes, running <code>git</code> <code>repack</code> again will create a
2314 new pack, that contains objects created since you packed your
2315 repository the last time. We recommend that you pack your project
2316 soon after the initial import (unless you are starting your
2317 project from scratch), and then run <code>git</code> <code>repack</code> every once in a
2318 while, depending on how active your project is.</p>
2319 </div>
2320 <div class="paragraph">
2321 <p>When a repository is synchronized via <code>git</code> <code>push</code> and <code>git</code> <code>pull</code>
2322 objects packed in the source repository are usually stored
2323 unpacked in the destination.
2324 While this allows you to use different packing strategies on
2325 both ends, it also means you may need to repack both
2326 repositories every once in a while.</p>
2327 </div>
2328 </div>
2329 </div>
2330 <div class="sect1">
2331 <h2 id="_working_with_others">Working with Others</h2>
2332 <div class="sectionbody">
2333 <div class="paragraph">
2334 <p>Although Git is a truly distributed system, it is often
2335 convenient to organize your project with an informal hierarchy
2336 of developers. Linux kernel development is run this way. There
2337 is a nice illustration (page 17, "Merges to Mainline") in
2338 <a href="https://web.archive.org/web/20120915203609/http://www.xenotime.net/linux/mentor/linux-mentoring-2006.pdf">Randy Dunlap&#8217;s presentation</a>.</p>
2339 </div>
2340 <div class="paragraph">
2341 <p>It should be stressed that this hierarchy is purely <strong>informal</strong>.
2342 There is nothing fundamental in Git that enforces the "chain of
2343 patch flow" this hierarchy implies. You do not have to pull
2344 from only one remote repository.</p>
2345 </div>
2346 <div class="paragraph">
2347 <p>A recommended workflow for a "project lead" goes like this:</p>
2348 </div>
2349 <div class="olist arabic">
2350 <ol class="arabic">
2351 <li>
2352 <p>Prepare your primary repository on your local machine. Your
2353 work is done there.</p>
2354 </li>
2355 <li>
2356 <p>Prepare a public repository accessible to others.</p>
2357 <div class="paragraph">
2358 <p>If other people are pulling from your repository over dumb
2359 transport protocols (HTTP), you need to keep this repository
2360 <em>dumb transport friendly</em>.  After <code>git</code> <code>init</code>,
2361 <code>$GIT_DIR/hooks/post-update.sample</code> copied from the standard templates
2362 would contain a call to <em>git update-server-info</em>
2363 but you need to manually enable the hook with
2364 <code>mv</code> <code>post-update.sample</code> <code>post-update</code>.  This makes sure
2365 <em>git update-server-info</em> keeps the necessary files up to date.</p>
2366 </div>
2367 </li>
2368 <li>
2369 <p>Push into the public repository from your primary
2370 repository.</p>
2371 </li>
2372 <li>
2373 <p><em>git repack</em> the public repository. This establishes a big
2374 pack that contains the initial set of objects as the
2375 baseline, and possibly <em>git prune</em> if the transport
2376 used for pulling from your repository supports packed
2377 repositories.</p>
2378 </li>
2379 <li>
2380 <p>Keep working in your primary repository. Your changes
2381 include modifications of your own, patches you receive via
2382 e-mails, and merges resulting from pulling the "public"
2383 repositories of your "subsystem maintainers".</p>
2384 <div class="paragraph">
2385 <p>You can repack this private repository whenever you feel like.</p>
2386 </div>
2387 </li>
2388 <li>
2389 <p>Push your changes to the public repository, and announce it
2390 to the public.</p>
2391 </li>
2392 <li>
2393 <p>Every once in a while, <em>git repack</em> the public repository.
2394 Go back to step 5. and continue working.</p>
2395 </li>
2396 </ol>
2397 </div>
2398 <div class="paragraph">
2399 <p>A recommended work cycle for a "subsystem maintainer" who works
2400 on that project and has an own "public repository" goes like this:</p>
2401 </div>
2402 <div class="olist arabic">
2403 <ol class="arabic">
2404 <li>
2405 <p>Prepare your work repository, by running <em>git clone</em> on the public
2406 repository of the "project lead". The URL used for the
2407 initial cloning is stored in the remote.origin.url
2408 configuration variable.</p>
2409 </li>
2410 <li>
2411 <p>Prepare a public repository accessible to others, just like
2412 the "project lead" person does.</p>
2413 </li>
2414 <li>
2415 <p>Copy over the packed files from "project lead" public
2416 repository to your public repository, unless the "project
2417 lead" repository lives on the same machine as yours.  In the
2418 latter case, you can use <code>objects/info/alternates</code> file to
2419 point at the repository you are borrowing from.</p>
2420 </li>
2421 <li>
2422 <p>Push into the public repository from your primary
2423 repository. Run <em>git repack</em>, and possibly <em>git prune</em> if the
2424 transport used for pulling from your repository supports
2425 packed repositories.</p>
2426 </li>
2427 <li>
2428 <p>Keep working in your primary repository. Your changes
2429 include modifications of your own, patches you receive via
2430 e-mails, and merges resulting from pulling the "public"
2431 repositories of your "project lead" and possibly your
2432 "sub-subsystem maintainers".</p>
2433 <div class="paragraph">
2434 <p>You can repack this private repository whenever you feel
2435 like.</p>
2436 </div>
2437 </li>
2438 <li>
2439 <p>Push your changes to your public repository, and ask your
2440 "project lead" and possibly your "sub-subsystem
2441 maintainers" to pull from it.</p>
2442 </li>
2443 <li>
2444 <p>Every once in a while, <em>git repack</em> the public repository.
2445 Go back to step 5. and continue working.</p>
2446 </li>
2447 </ol>
2448 </div>
2449 <div class="paragraph">
2450 <p>A recommended work cycle for an "individual developer" who does
2451 not have a "public" repository is somewhat different. It goes
2452 like this:</p>
2453 </div>
2454 <div class="olist arabic">
2455 <ol class="arabic">
2456 <li>
2457 <p>Prepare your work repository, by <em>git clone</em> the public
2458 repository of the "project lead" (or a "subsystem
2459 maintainer", if you work on a subsystem). The URL used for
2460 the initial cloning is stored in the remote.origin.url
2461 configuration variable.</p>
2462 </li>
2463 <li>
2464 <p>Do your work in your repository on <em>master</em> branch.</p>
2465 </li>
2466 <li>
2467 <p>Run <code>git</code> <code>fetch</code> <code>origin</code> from the public repository of your
2468 upstream every once in a while. This does only the first
2469 half of <code>git</code> <code>pull</code> but does not merge. The head of the
2470 public repository is stored in .<code>git/refs/remotes/origin/master</code>.</p>
2471 </li>
2472 <li>
2473 <p>Use <code>git</code> <code>cherry</code> <code>origin</code> to see which ones of your patches
2474 were accepted, and/or use <code>git</code> <code>rebase</code> <code>origin</code> to port your
2475 unmerged changes forward to the updated upstream.</p>
2476 </li>
2477 <li>
2478 <p>Use <code>git</code> <code>format-patch</code> <code>origin</code> to prepare patches for e-mail
2479 submission to your upstream and send it out. Go back to
2480 step 2. and continue.</p>
2481 </li>
2482 </ol>
2483 </div>
2484 </div>
2485 </div>
2486 <div class="sect1">
2487 <h2 id="_working_with_others_shared_repository_style">Working with Others, Shared Repository Style</h2>
2488 <div class="sectionbody">
2489 <div class="paragraph">
2490 <p>If you are coming from a CVS background, the style of cooperation
2491 suggested in the previous section may be new to you. You do not
2492 have to worry. Git supports the "shared public repository" style of
2493 cooperation you are probably more familiar with as well.</p>
2494 </div>
2495 <div class="paragraph">
2496 <p>See <a href="gitcvs-migration.html">gitcvs-migration(7)</a> for the details.</p>
2497 </div>
2498 </div>
2499 </div>
2500 <div class="sect1">
2501 <h2 id="_bundling_your_work_together">Bundling your work together</h2>
2502 <div class="sectionbody">
2503 <div class="paragraph">
2504 <p>It is likely that you will be working on more than one thing at
2505 a time.  It is easy to manage those more-or-less independent tasks
2506 using branches with Git.</p>
2507 </div>
2508 <div class="paragraph">
2509 <p>We have already seen how branches work previously,
2510 with "fun and work" example using two branches.  The idea is the
2511 same if there are more than two branches.  Let&#8217;s say you started
2512 out from "master" head, and have some new code in the "master"
2513 branch, and two independent fixes in the "commit-fix" and
2514 "diff-fix" branches:</p>
2515 </div>
2516 <div class="listingblock">
2517 <div class="content">
2518 <pre>$ git show-branch
2519 ! [commit-fix] Fix commit message normalization.
2520  ! [diff-fix] Fix rename detection.
2521   * [master] Release candidate #1
2522 ---
2523  +  [diff-fix] Fix rename detection.
2524  +  [diff-fix~1] Better common substring algorithm.
2525 +   [commit-fix] Fix commit message normalization.
2526   * [master] Release candidate #1
2527 ++* [diff-fix~2] Pretty-print messages.</pre>
2528 </div>
2529 </div>
2530 <div class="paragraph">
2531 <p>Both fixes are tested well, and at this point, you want to merge
2532 in both of them.  You could merge in <em>diff-fix</em> first and then
2533 <em>commit-fix</em> next, like this:</p>
2534 </div>
2535 <div class="listingblock">
2536 <div class="content">
2537 <pre>$ git merge -m "Merge fix in diff-fix" diff-fix
2538 $ git merge -m "Merge fix in commit-fix" commit-fix</pre>
2539 </div>
2540 </div>
2541 <div class="paragraph">
2542 <p>Which would result in:</p>
2543 </div>
2544 <div class="listingblock">
2545 <div class="content">
2546 <pre>$ git show-branch
2547 ! [commit-fix] Fix commit message normalization.
2548  ! [diff-fix] Fix rename detection.
2549   * [master] Merge fix in commit-fix
2550 ---
2551   - [master] Merge fix in commit-fix
2552 + * [commit-fix] Fix commit message normalization.
2553   - [master~1] Merge fix in diff-fix
2554  +* [diff-fix] Fix rename detection.
2555  +* [diff-fix~1] Better common substring algorithm.
2556   * [master~2] Release candidate #1
2557 ++* [master~3] Pretty-print messages.</pre>
2558 </div>
2559 </div>
2560 <div class="paragraph">
2561 <p>However, there is no particular reason to merge in one branch
2562 first and the other next, when what you have are a set of truly
2563 independent changes (if the order mattered, then they are not
2564 independent by definition).  You could instead merge those two
2565 branches into the current branch at once.  First let&#8217;s undo what
2566 we just did and start over.  We would want to get the master
2567 branch before these two merges by resetting it to <em>master~2</em>:</p>
2568 </div>
2569 <div class="listingblock">
2570 <div class="content">
2571 <pre>$ git reset --hard master~2</pre>
2572 </div>
2573 </div>
2574 <div class="paragraph">
2575 <p>You can make sure <code>git</code> <code>show-branch</code> matches the state before
2576 those two <em>git merge</em> you just did.  Then, instead of running
2577 two <em>git merge</em> commands in a row, you would merge these two
2578 branch heads (this is known as <em>making an Octopus</em>):</p>
2579 </div>
2580 <div class="listingblock">
2581 <div class="content">
2582 <pre>$ git merge commit-fix diff-fix
2583 $ git show-branch
2584 ! [commit-fix] Fix commit message normalization.
2585  ! [diff-fix] Fix rename detection.
2586   * [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
2587 ---
2588   - [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
2589 + * [commit-fix] Fix commit message normalization.
2590  +* [diff-fix] Fix rename detection.
2591  +* [diff-fix~1] Better common substring algorithm.
2592   * [master~1] Release candidate #1
2593 ++* [master~2] Pretty-print messages.</pre>
2594 </div>
2595 </div>
2596 <div class="paragraph">
2597 <p>Note that you should not do Octopus just because you can.  An octopus
2598 is a valid thing to do and often makes it easier to view the
2599 commit history if you are merging more than two independent
2600 changes at the same time.  However, if you have merge conflicts
2601 with any of the branches you are merging in and need to hand
2602 resolve, that is an indication that the development happened in
2603 those branches were not independent after all, and you should
2604 merge two at a time, documenting how you resolved the conflicts,
2605 and the reason why you preferred changes made in one side over
2606 the other.  Otherwise it would make the project history harder
2607 to follow, not easier.</p>
2608 </div>
2609 </div>
2610 </div>
2611 <div class="sect1">
2612 <h2 id="_see_also">SEE ALSO</h2>
2613 <div class="sectionbody">
2614 <div class="paragraph">
2615 <p><a href="gittutorial.html">gittutorial(7)</a>,
2616 <a href="gittutorial-2.html">gittutorial-2(7)</a>,
2617 <a href="gitcvs-migration.html">gitcvs-migration(7)</a>,
2618 <a href="git-help.html">git-help(1)</a>,
2619 <a href="giteveryday.html">giteveryday(7)</a>,
2620 <a href="user-manual.html">The Git User&#8217;s Manual</a></p>
2621 </div>
2622 </div>
2623 </div>
2624 <div class="sect1">
2625 <h2 id="_git">GIT</h2>
2626 <div class="sectionbody">
2627 <div class="paragraph">
2628 <p>Part of the <a href="git.html">git(1)</a> suite</p>
2629 </div>
2630 </div>
2631 </div>
2632 </div>
2633 <div id="footer">
2634 <div id="footer-text">
2635 Last updated 2023-12-18 14:49:41 -0800
2636 </div>
2637 </div>
2638 </body>
2639 </html>