| <!DOCTYPE html> |
| <html xmlns="http://www.w3.org/1999/xhtml" lang="en"> |
| <head> |
| <meta charset="UTF-8"/> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge"/> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"/> |
| <meta name="generator" content="Asciidoctor 2.0.23"/> |
| <title>gitformat-pack(5)</title> |
| <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"/> |
| <style> |
| /*! Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */ |
| /* Uncomment the following line when using as a custom stylesheet */ |
| /* @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"; */ |
| html{font-family:sans-serif;-webkit-text-size-adjust:100%} |
| a{background:none} |
| a:focus{outline:thin dotted} |
| a:active,a:hover{outline:0} |
| h1{font-size:2em;margin:.67em 0} |
| b,strong{font-weight:bold} |
| abbr{font-size:.9em} |
| abbr[title]{cursor:help;border-bottom:1px dotted #dddddf;text-decoration:none} |
| dfn{font-style:italic} |
| hr{height:0} |
| mark{background:#ff0;color:#000} |
| code,kbd,pre,samp{font-family:monospace;font-size:1em} |
| pre{white-space:pre-wrap} |
| q{quotes:"\201C" "\201D" "\2018" "\2019"} |
| small{font-size:80%} |
| sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline} |
| sup{top:-.5em} |
| sub{bottom:-.25em} |
| img{border:0} |
| svg:not(:root){overflow:hidden} |
| figure{margin:0} |
| audio,video{display:inline-block} |
| audio:not([controls]){display:none;height:0} |
| fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em} |
| legend{border:0;padding:0} |
| button,input,select,textarea{font-family:inherit;font-size:100%;margin:0} |
| button,input{line-height:normal} |
| button,select{text-transform:none} |
| button,html input[type=button],input[type=reset],input[type=submit]{-webkit-appearance:button;cursor:pointer} |
| button[disabled],html input[disabled]{cursor:default} |
| input[type=checkbox],input[type=radio]{padding:0} |
| button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0} |
| textarea{overflow:auto;vertical-align:top} |
| table{border-collapse:collapse;border-spacing:0} |
| *,::before,::after{box-sizing:border-box} |
| html,body{font-size:100%} |
| 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} |
| a:hover{cursor:pointer} |
| img,object,embed{max-width:100%;height:auto} |
| object,embed{height:100%} |
| img{-ms-interpolation-mode:bicubic} |
| .left{float:left!important} |
| .right{float:right!important} |
| .text-left{text-align:left!important} |
| .text-right{text-align:right!important} |
| .text-center{text-align:center!important} |
| .text-justify{text-align:justify!important} |
| .hide{display:none} |
| img,object,svg{display:inline-block;vertical-align:middle} |
| textarea{height:auto;min-height:50px} |
| select{width:100%} |
| .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} |
| 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} |
| a{color:#2156a5;text-decoration:underline;line-height:inherit} |
| a:hover,a:focus{color:#1d4b8f} |
| a img{border:0} |
| p{line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility} |
| p aside{font-size:.875em;line-height:1.35;font-style:italic} |
| 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} |
| 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} |
| h1{font-size:2.125em} |
| h2{font-size:1.6875em} |
| h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em} |
| h4,h5{font-size:1.125em} |
| h6{font-size:1em} |
| hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em} |
| em,i{font-style:italic;line-height:inherit} |
| strong,b{font-weight:bold;line-height:inherit} |
| small{font-size:60%;line-height:inherit} |
| code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)} |
| ul,ol,dl{line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit} |
| ul,ol{margin-left:1.5em} |
| ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0} |
| ul.circle{list-style-type:circle} |
| ul.disc{list-style-type:disc} |
| ul.square{list-style-type:square} |
| ul.circle ul:not([class]),ul.disc ul:not([class]),ul.square ul:not([class]){list-style:inherit} |
| ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0} |
| dl dt{margin-bottom:.3125em;font-weight:bold} |
| dl dd{margin-bottom:1.25em} |
| blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd} |
| blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)} |
| @media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2} |
| h1{font-size:2.75em} |
| h2{font-size:2.3125em} |
| h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em} |
| h4{font-size:1.4375em}} |
| table{background:#fff;margin-bottom:1.25em;border:1px solid #dedede;word-wrap:normal} |
| table thead,table tfoot{background:#f7f8f7} |
| 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} |
| table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)} |
| table tr.even,table tr.alt{background:#f8f8f7} |
| table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{line-height:1.6} |
| h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em} |
| h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400} |
| .center{margin-left:auto;margin-right:auto} |
| .stretch{width:100%} |
| .clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table} |
| .clearfix::after,.float-group::after{clear:both} |
| :not(pre).nobreak{word-wrap:normal} |
| :not(pre).nowrap{white-space:nowrap} |
| :not(pre).pre-wrap{white-space:pre-wrap} |
| :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} |
| pre{color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;line-height:1.45;text-rendering:optimizeSpeed} |
| pre code,pre pre{color:inherit;font-size:inherit;line-height:inherit} |
| pre>code{display:block} |
| pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal} |
| em em{font-style:normal} |
| strong strong{font-weight:400} |
| .keyseq{color:rgba(51,51,51,.8)} |
| 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} |
| .keyseq kbd:first-child{margin-left:0} |
| .keyseq kbd:last-child{margin-right:0} |
| .menuseq,.menuref{color:#000} |
| .menuseq b:not(.caret),.menuref{font-weight:inherit} |
| .menuseq{word-spacing:-.02em} |
| .menuseq b.caret{font-size:1.25em;line-height:.8} |
| .menuseq i.caret{font-weight:bold;text-align:center;width:.45em} |
| b.button::before,b.button::after{position:relative;top:-1px;font-weight:400} |
| b.button::before{content:"[";padding:0 3px 0 2px} |
| b.button::after{content:"]";padding:0 2px 0 3px} |
| p a>code:hover{color:rgba(0,0,0,.9)} |
| #header,#content,#footnotes,#footer{width:100%;margin:0 auto;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em} |
| #header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table} |
| #header::after,#content::after,#footnotes::after,#footer::after{clear:both} |
| #content{margin-top:1.25em} |
| #content::before{content:none} |
| #header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0} |
| #header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf} |
| #header>h1:only-child{border-bottom:1px solid #dddddf;padding-bottom:8px} |
| #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} |
| #header .details span:first-child{margin-left:-.125em} |
| #header .details span.email a{color:rgba(0,0,0,.85)} |
| #header .details br{display:none} |
| #header .details br+span::before{content:"\00a0\2013\00a0"} |
| #header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)} |
| #header .details br+span#revremark::before{content:"\00a0|\00a0"} |
| #header #revnumber{text-transform:capitalize} |
| #header #revnumber::after{content:"\00a0"} |
| #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} |
| #toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em} |
| #toc>ul{margin-left:.125em} |
| #toc ul.sectlevel0>li>a{font-style:italic} |
| #toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0} |
| #toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none} |
| #toc li{line-height:1.3334;margin-top:.3334em} |
| #toc a{text-decoration:none} |
| #toc a:active{text-decoration:underline} |
| #toctitle{color:#7a2518;font-size:1.2em} |
| @media screen and (min-width:768px){#toctitle{font-size:1.375em} |
| body.toc2{padding-left:15em;padding-right:0} |
| body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px} |
| #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} |
| #toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em} |
| #toc.toc2>ul{font-size:.9em;margin-bottom:0} |
| #toc.toc2 ul ul{margin-left:0;padding-left:1em} |
| #toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em} |
| body.toc2.toc-right{padding-left:0;padding-right:15em} |
| body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}} |
| @media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0} |
| #toc.toc2{width:20em} |
| #toc.toc2 #toctitle{font-size:1.375em} |
| #toc.toc2>ul{font-size:.95em} |
| #toc.toc2 ul ul{padding-left:1.25em} |
| body.toc2.toc-right{padding-left:0;padding-right:20em}} |
| #content #toc{border:1px solid #e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;border-radius:4px} |
| #content #toc>:first-child{margin-top:0} |
| #content #toc>:last-child{margin-bottom:0} |
| #footer{max-width:none;background:rgba(0,0,0,.8);padding:1.25em} |
| #footer-text{color:hsla(0,0%,100%,.8);line-height:1.44} |
| #content{margin-bottom:.625em} |
| .sect1{padding-bottom:.625em} |
| @media screen and (min-width:768px){#content{margin-bottom:1.25em} |
| .sect1{padding-bottom:1.25em}} |
| .sect1:last-child{padding-bottom:0} |
| .sect1+.sect1{border-top:1px solid #e7e7e9} |
| #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} |
| #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} |
| #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} |
| #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} |
| #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} |
| details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em} |
| details{margin-left:1.25rem} |
| details>summary{cursor:pointer;display:block;position:relative;line-height:1.6;margin-bottom:.625rem;outline:none;-webkit-tap-highlight-color:transparent} |
| details>summary::-webkit-details-marker{display:none} |
| 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%)} |
| details[open]>summary::before{border:solid transparent;border-top:solid;border-width:.5em .3em 0;transform:translateY(15%)} |
| details>summary::after{content:"";width:1.25rem;height:1em;position:absolute;top:.3em;left:-1.25rem} |
| .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} |
| table.tableblock.fit-content>caption.title{white-space:nowrap;width:0} |
| .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)} |
| .admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%} |
| .admonitionblock>table td.icon{text-align:center;width:80px} |
| .admonitionblock>table td.icon img{max-width:none} |
| .admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase} |
| .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} |
| .admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0} |
| .exampleblock>.content{border:1px solid #e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;border-radius:4px} |
| .sidebarblock{border:1px solid #dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;border-radius:4px} |
| .sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center} |
| .exampleblock>.content>:first-child,.sidebarblock>.content>:first-child{margin-top:0} |
| .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} |
| .literalblock pre,.listingblock>.content>pre{border-radius:4px;overflow-x:auto;padding:1em;font-size:.8125em} |
| @media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}} |
| @media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}} |
| .literalblock pre,.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class=highlight],.listingblock>.content>pre[class^="highlight "]{background:#f7f7f8} |
| .literalblock.output pre{color:#f7f7f8;background:rgba(0,0,0,.9)} |
| .listingblock>.content{position:relative} |
| .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} |
| .listingblock:hover code[data-lang]::before{display:block} |
| .listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:inherit;opacity:.5} |
| .listingblock.terminal pre .command:not([data-prompt])::before{content:"$"} |
| .listingblock pre.highlightjs{padding:0} |
| .listingblock pre.highlightjs>code{padding:1em;border-radius:4px} |
| .listingblock pre.prettyprint{border-width:0} |
| .prettyprint{background:#f7f7f8} |
| pre.prettyprint .linenums{line-height:1.45;margin-left:2em} |
| pre.prettyprint li{background:none;list-style-type:inherit;padding-left:0} |
| pre.prettyprint li code[data-lang]::before{opacity:1} |
| pre.prettyprint li:not(:first-child) code[data-lang]::before{display:none} |
| table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none} |
| table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal} |
| table.linenotable td.code{padding-left:.75em} |
| 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} |
| pre.pygments span.linenos{display:inline-block;margin-right:.75em} |
| .quoteblock{margin:0 1em 1.25em 1.5em;display:table} |
| .quoteblock:not(.excerpt)>.title{margin-left:-1.5em;margin-bottom:.75em} |
| .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} |
| .quoteblock blockquote{margin:0;padding:0;border:0} |
| .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)} |
| .quoteblock blockquote>.paragraph:last-child p{margin-bottom:0} |
| .quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right} |
| .verseblock{margin:0 1em 1.25em} |
| .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} |
| .verseblock pre strong{font-weight:400} |
| .verseblock .attribution{margin-top:1.25rem;margin-left:.5ex} |
| .quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic} |
| .quoteblock .attribution br,.verseblock .attribution br{display:none} |
| .quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)} |
| .quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none} |
| .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} |
| .quoteblock.abstract{margin:0 1em 1.25em;display:block} |
| .quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center} |
| .quoteblock.excerpt>blockquote,.quoteblock .quoteblock{padding:0 0 .25em 1em;border-left:.25em solid #dddddf} |
| .quoteblock.excerpt,.quoteblock .quoteblock{margin-left:0} |
| .quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem} |
| .quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;font-size:.85rem;text-align:left;margin-right:0} |
| p.tableblock:last-child{margin-bottom:0} |
| td.tableblock>.content{margin-bottom:1.25em;word-wrap:anywhere} |
| td.tableblock>.content>:last-child{margin-bottom:-1.25em} |
| table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede} |
| table.grid-all>*>tr>*{border-width:1px} |
| table.grid-cols>*>tr>*{border-width:0 1px} |
| table.grid-rows>*>tr>*{border-width:1px 0} |
| table.frame-all{border-width:1px} |
| table.frame-ends{border-width:1px 0} |
| table.frame-sides{border-width:0 1px} |
| table.frame-none>colgroup+*>:first-child>*,table.frame-sides>colgroup+*>:first-child>*{border-top-width:0} |
| table.frame-none>:last-child>:last-child>*,table.frame-sides>:last-child>:last-child>*{border-bottom-width:0} |
| table.frame-none>*>tr>:first-child,table.frame-ends>*>tr>:first-child{border-left-width:0} |
| table.frame-none>*>tr>:last-child,table.frame-ends>*>tr>:last-child{border-right-width:0} |
| 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} |
| th.halign-left,td.halign-left{text-align:left} |
| th.halign-right,td.halign-right{text-align:right} |
| th.halign-center,td.halign-center{text-align:center} |
| th.valign-top,td.valign-top{vertical-align:top} |
| th.valign-bottom,td.valign-bottom{vertical-align:bottom} |
| th.valign-middle,td.valign-middle{vertical-align:middle} |
| table thead th,table tfoot th{font-weight:bold} |
| tbody tr th{background:#f7f8f7} |
| tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold} |
| p.tableblock>code:only-child{background:none;padding:0} |
| p.tableblock{font-size:1em} |
| ol{margin-left:1.75em} |
| ul li ol{margin-left:1.5em} |
| dl dd{margin-left:1.125em} |
| dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0} |
| li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em} |
| ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none} |
| ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em} |
| ul.unstyled,ol.unstyled{margin-left:0} |
| li>p:empty:only-child::before{content:"";display:inline-block} |
| ul.checklist>li>p:first-child{margin-left:-1em} |
| 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} |
| ul.checklist>li>p:first-child>input[type=checkbox]:first-child{margin-right:.25em} |
| ul.inline{display:flex;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em} |
| ul.inline>li{margin-left:1.25em} |
| .unstyled dl dt{font-weight:400;font-style:normal} |
| ol.arabic{list-style-type:decimal} |
| ol.decimal{list-style-type:decimal-leading-zero} |
| ol.loweralpha{list-style-type:lower-alpha} |
| ol.upperalpha{list-style-type:upper-alpha} |
| ol.lowerroman{list-style-type:lower-roman} |
| ol.upperroman{list-style-type:upper-roman} |
| ol.lowergreek{list-style-type:lower-greek} |
| .hdlist>table,.colist>table{border:0;background:none} |
| .hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none} |
| td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em} |
| td.hdlist1{font-weight:bold;padding-bottom:1.25em} |
| td.hdlist2{word-wrap:anywhere} |
| .literalblock+.colist,.listingblock+.colist{margin-top:-.5em} |
| .colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top} |
| .colist td:not([class]):first-child img{max-width:none} |
| .colist td:not([class]):last-child{padding:.25em 0} |
| .thumb,.th{line-height:0;display:inline-block;border:4px solid #fff;box-shadow:0 0 0 1px #ddd} |
| .imageblock.left{margin:.25em .625em 1.25em 0} |
| .imageblock.right{margin:.25em 0 1.25em .625em} |
| .imageblock>.title{margin-bottom:0} |
| .imageblock.thumb,.imageblock.th{border-width:6px} |
| .imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em} |
| .image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0} |
| .image.left{margin-right:.625em} |
| .image.right{margin-left:.625em} |
| a.image{text-decoration:none;display:inline-block} |
| a.image object{pointer-events:none} |
| sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super} |
| sup.footnote a,sup.footnoteref a{text-decoration:none} |
| sup.footnote a:active,sup.footnoteref a:active,#footnotes .footnote a:first-of-type:active{text-decoration:underline} |
| #footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em} |
| #footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0} |
| #footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em} |
| #footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em} |
| #footnotes .footnote:last-of-type{margin-bottom:0} |
| #content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0} |
| div.unbreakable{page-break-inside:avoid} |
| .big{font-size:larger} |
| .small{font-size:smaller} |
| .underline{text-decoration:underline} |
| .overline{text-decoration:overline} |
| .line-through{text-decoration:line-through} |
| .aqua{color:#00bfbf} |
| .aqua-background{background:#00fafa} |
| .black{color:#000} |
| .black-background{background:#000} |
| .blue{color:#0000bf} |
| .blue-background{background:#0000fa} |
| .fuchsia{color:#bf00bf} |
| .fuchsia-background{background:#fa00fa} |
| .gray{color:#606060} |
| .gray-background{background:#7d7d7d} |
| .green{color:#006000} |
| .green-background{background:#007d00} |
| .lime{color:#00bf00} |
| .lime-background{background:#00fa00} |
| .maroon{color:#600000} |
| .maroon-background{background:#7d0000} |
| .navy{color:#000060} |
| .navy-background{background:#00007d} |
| .olive{color:#606000} |
| .olive-background{background:#7d7d00} |
| .purple{color:#600060} |
| .purple-background{background:#7d007d} |
| .red{color:#bf0000} |
| .red-background{background:#fa0000} |
| .silver{color:#909090} |
| .silver-background{background:#bcbcbc} |
| .teal{color:#006060} |
| .teal-background{background:#007d7d} |
| .white{color:#bfbfbf} |
| .white-background{background:#fafafa} |
| .yellow{color:#bfbf00} |
| .yellow-background{background:#fafa00} |
| span.icon>.fa{cursor:default} |
| a span.icon>.fa{cursor:inherit} |
| .admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default} |
| .admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c} |
| .admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111} |
| .admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900} |
| .admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400} |
| .admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000} |
| .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} |
| .conum[data-value] *{color:#fff!important} |
| .conum[data-value]+b{display:none} |
| .conum[data-value]::after{content:attr(data-value)} |
| pre .conum[data-value]{position:relative;top:-.125em} |
| b.conum *{color:inherit!important} |
| .conum:not([data-value]):empty{display:none} |
| dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility} |
| h1,h2,p,td.content,span.alt,summary{letter-spacing:-.01em} |
| p strong,td.content strong,div.footnote strong{letter-spacing:-.005em} |
| p,blockquote,dt,td.content,td.hdlist1,span.alt,summary{font-size:1.0625rem} |
| p{margin-bottom:1.25rem} |
| .sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em} |
| .exampleblock>.content{background:#fffef7;border-color:#e0e0dc;box-shadow:0 1px 4px #e0e0dc} |
| .print-only{display:none!important} |
| @page{margin:1.25cm .75cm} |
| @media print{*{box-shadow:none!important;text-shadow:none!important} |
| html{font-size:80%} |
| a{color:inherit!important;text-decoration:underline!important} |
| a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important} |
| a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em} |
| abbr[title]{border-bottom:1px dotted} |
| abbr[title]::after{content:" (" attr(title) ")"} |
| pre,blockquote,tr,img,object,svg{page-break-inside:avoid} |
| thead{display:table-header-group} |
| svg{max-width:100%} |
| p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3} |
| h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid} |
| #header,#content,#footnotes,#footer{max-width:none} |
| #toc,.sidebarblock,.exampleblock>.content{background:none!important} |
| #toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important} |
| body.book #header{text-align:center} |
| body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em} |
| body.book #header .details{border:0!important;display:block;padding:0!important} |
| body.book #header .details span:first-child{margin-left:0!important} |
| body.book #header .details br{display:block} |
| body.book #header .details br+span::before{content:none!important} |
| body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important} |
| body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always} |
| .listingblock code[data-lang]::before{display:block} |
| #footer{padding:0 .9375em} |
| .hide-on-print{display:none!important} |
| .print-only{display:block!important} |
| .hide-for-print{display:none!important} |
| .show-for-print{display:inherit!important}} |
| @media amzn-kf8,print{#header>h1:first-child{margin-top:1.25rem} |
| .sect1{padding:0!important} |
| .sect1+.sect1{border:0} |
| #footer{background:none} |
| #footer-text{color:rgba(0,0,0,.6);font-size:.9em}} |
| @media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}} |
| </style> |
| <style> |
| pre>code { |
| display: inline; |
| } |
| </style> |
| </head> |
| <body class="manpage"> |
| <div id="header"> |
| <h1>gitformat-pack(5) Manual Page</h1> |
| <h2 id="_name">NAME</h2> |
| <div class="sectionbody"> |
| <p>gitformat-pack - Git pack format</p> |
| </div> |
| </div> |
| <div id="content"> |
| <div class="sect1"> |
| <h2 id="_synopsis">SYNOPSIS</h2> |
| <div class="sectionbody"> |
| <div class="verseblock"> |
| <pre class="content">$GIT_DIR/objects/pack/pack-<strong>.{pack,idx} |
| $GIT_DIR/objects/pack/pack-</strong>.rev |
| $GIT_DIR/objects/pack/pack-*.mtimes |
| $GIT_DIR/objects/pack/multi-pack-index</pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_description">DESCRIPTION</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The Git pack format is how Git stores most of its primary repository |
| data. Over the lifetime of a repository, loose objects (if any) and |
| smaller packs are consolidated into larger pack(s). See |
| <a href="git-gc.html">git-gc(1)</a> and <a href="git-pack-objects.html">git-pack-objects(1)</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The pack format is also used over-the-wire, see |
| e.g. <a href="gitprotocol-v2.html">gitprotocol-v2(5)</a>, as well as being a part of |
| other container formats in the case of <a href="gitformat-bundle.html">gitformat-bundle(5)</a>.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_checksums_and_object_ids">Checksums and object IDs</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>In a repository using the traditional SHA-1, pack checksums, index checksums, |
| and object IDs (object names) mentioned below are all computed using SHA-1. |
| Similarly, in SHA-256 repositories, these values are computed using SHA-256.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_pack_pack_files_have_the_following_format">pack-*.pack files have the following format:</h2> |
| <div class="sectionbody"> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>A header appears at the beginning and consists of the following:</p> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>4-byte signature: |
| The signature is: {'P', 'A', 'C', 'K'}</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> 4-byte version number (network byte order): |
| Git currently accepts version number 2 or 3 but |
| generates version 2 only.</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>4-byte number of objects contained in the pack (network byte order)</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>Observation: we cannot have more than 4G versions ;-) and |
| more than 4G objects in a pack.</pre> |
| </div> |
| </div> |
| </li> |
| <li> |
| <p>The header is followed by a number of object entries, each of |
| which looks like this:</p> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>(undeltified representation) |
| n-byte type and length (3-bit type, (n-1)*7+4-bit length) |
| compressed data</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> (deltified representation) |
| n-byte type and length (3-bit type, (n-1)*7+4-bit length) |
| base object name if OBJ_REF_DELTA or a negative relative |
| offset from the delta object's position in the pack if this |
| is an OBJ_OFS_DELTA object |
| compressed delta data</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>Observation: the length of each object is encoded in a variable |
| length format and is not constrained to 32-bit or anything.</pre> |
| </div> |
| </div> |
| </li> |
| <li> |
| <p>The trailer records a pack checksum of all of the above.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="sect2"> |
| <h3 id="_object_types">Object types</h3> |
| <div class="paragraph"> |
| <p>Valid object types are:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>OBJ_COMMIT (1)</p> |
| </li> |
| <li> |
| <p>OBJ_TREE (2)</p> |
| </li> |
| <li> |
| <p>OBJ_BLOB (3)</p> |
| </li> |
| <li> |
| <p>OBJ_TAG (4)</p> |
| </li> |
| <li> |
| <p>OBJ_OFS_DELTA (6)</p> |
| </li> |
| <li> |
| <p>OBJ_REF_DELTA (7)</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Type 5 is reserved for future expansion. Type 0 is invalid.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_size_encoding">Size encoding</h3> |
| <div class="paragraph"> |
| <p>This document uses the following "size encoding" of non-negative |
| integers: From each byte, the seven least significant bits are |
| used to form the resulting integer. As long as the most significant |
| bit is 1, this process continues; the byte with MSB 0 provides the |
| last seven bits. The seven-bit chunks are concatenated. Later |
| values are more significant.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This size encoding should not be confused with the "offset encoding", |
| which is also used in this document.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_deltified_representation">Deltified representation</h3> |
| <div class="paragraph"> |
| <p>Conceptually there are only four object types: commit, tree, tag and |
| blob. However to save space, an object could be stored as a "delta" of |
| another "base" object. These representations are assigned new types |
| ofs-delta and ref-delta, which is only valid in a pack file.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Both ofs-delta and ref-delta store the "delta" to be applied to |
| another object (called <em>base object</em>) to reconstruct the object. The |
| difference between them is, ref-delta directly encodes base object |
| name. If the base object is in the same pack, ofs-delta encodes |
| the offset of the base object in the pack instead.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The base object could also be deltified if it’s in the same pack. |
| Ref-delta can also refer to an object outside the pack (i.e. the |
| so-called "thin pack"). When stored on disk however, the pack should |
| be self contained to avoid cyclic dependency.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The delta data starts with the size of the base object and the |
| size of the object to be reconstructed. These sizes are |
| encoded using the size encoding from above. The remainder of |
| the delta data is a sequence of instructions to reconstruct the object |
| from the base object. If the base object is deltified, it must be |
| converted to canonical form first. Each instruction appends more and |
| more data to the target object until it’s complete. There are two |
| supported instructions so far: one for copying a byte range from the |
| source object and one for inserting new data embedded in the |
| instruction itself.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Each instruction has variable length. Instruction type is determined |
| by the seventh bit of the first octet. The following diagrams follow |
| the convention in RFC 1951 (Deflate compressed data format).</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_instruction_to_copy_from_base_object">Instruction to copy from base object</h4> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>+----------+---------+---------+---------+---------+-------+-------+-------+ |
| | 1xxxxxxx | offset1 | offset2 | offset3 | offset4 | size1 | size2 | size3 | |
| +----------+---------+---------+---------+---------+-------+-------+-------+</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This is the instruction format to copy a byte range from the source |
| object. It encodes the offset to copy from and the number of bytes to |
| copy. Offset and size are in little-endian order.</p> |
| </div> |
| <div class="paragraph"> |
| <p>All offset and size bytes are optional. This is to reduce the |
| instruction size when encoding small offsets or sizes. The first seven |
| bits in the first octet determine which of the next seven octets is |
| present. If bit zero is set, offset1 is present. If bit one is set |
| offset2 is present and so on.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Note that a more compact instruction does not change offset and size |
| encoding. For example, if only offset2 is omitted like below, offset3 |
| still contains bits 16-23. It does not become offset2 and contains |
| bits 8-15 even if it’s right next to offset1.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>+----------+---------+---------+ |
| | 10000101 | offset1 | offset3 | |
| +----------+---------+---------+</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>In its most compact form, this instruction only takes up one byte |
| (0x80) with both offset and size omitted, which will have default |
| values zero. There is another exception: size zero is automatically |
| converted to 0x10000.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_instruction_to_add_new_data">Instruction to add new data</h4> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>+----------+============+ |
| | 0xxxxxxx | data | |
| +----------+============+</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This is the instruction to construct the target object without the base |
| object. The following data is appended to the target object. The first |
| seven bits of the first octet determine the size of data in |
| bytes. The size must be non-zero.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_reserved_instruction">Reserved instruction</h4> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>+----------+============ |
| | 00000000 | |
| +----------+============</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This is the instruction reserved for future expansion.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_original_version_1_pack_idx_files_have_the_following_format">Original (version 1) pack-*.idx files have the following format:</h2> |
| <div class="sectionbody"> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The header consists of 256 4-byte network byte order |
| integers. N-th entry of this table records the number of |
| objects in the corresponding pack, the first byte of whose |
| object name is less than or equal to N. This is called the |
| <em>first-level fan-out</em> table.</p> |
| </li> |
| <li> |
| <p>The header is followed by sorted 24-byte entries, one entry |
| per object in the pack. Each entry is:</p> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>4-byte network byte order integer, recording where the |
| object is stored in the packfile as the offset from the |
| beginning.</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>one object name of the appropriate size.</pre> |
| </div> |
| </div> |
| </li> |
| <li> |
| <p>The file is concluded with a trailer:</p> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>A copy of the pack checksum at the end of the corresponding |
| packfile.</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>Index checksum of all of the above.</pre> |
| </div> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Pack Idx file:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> -- +--------------------------------+ |
| fanout | fanout[0] = 2 (for example) |-. |
| table +--------------------------------+ | |
| | fanout[1] | | |
| +--------------------------------+ | |
| | fanout[2] | | |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| | fanout[255] = total objects |---. |
| -- +--------------------------------+ | | |
| main | offset | | | |
| index | object name 00XXXXXXXXXXXXXXXX | | | |
| table +--------------------------------+ | | |
| | offset | | | |
| | object name 00XXXXXXXXXXXXXXXX | | | |
| +--------------------------------+<+ | |
| .-| offset | | |
| | | object name 01XXXXXXXXXXXXXXXX | | |
| | +--------------------------------+ | |
| | | offset | | |
| | | object name 01XXXXXXXXXXXXXXXX | | |
| | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| | | offset | | |
| | | object name FFXXXXXXXXXXXXXXXX | | |
| --| +--------------------------------+<--+ |
| trailer | | packfile checksum | |
| | +--------------------------------+ |
| | | idxfile checksum | |
| | +--------------------------------+ |
| .-------. |
| | |
| Pack file entry: <+</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> packed object header: |
| 1-byte size extension bit (MSB) |
| type (next 3 bit) |
| size0 (lower 4-bit) |
| n-byte sizeN (as long as MSB is set, each 7-bit) |
| size0..sizeN form 4+7+7+..+7 bit integer, size0 |
| is the least significant part, and sizeN is the |
| most significant part. |
| packed object data: |
| If it is not DELTA, then deflated bytes (the size above |
| is the size before compression). |
| If it is REF_DELTA, then |
| base object name (the size above is the |
| size of the delta data that follows). |
| delta data, deflated. |
| If it is OFS_DELTA, then |
| n-byte offset (see below) interpreted as a negative |
| offset from the type-byte of the header of the |
| ofs-delta entry (the size above is the size of |
| the delta data that follows). |
| delta data, deflated.</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> offset encoding: |
| n bytes with MSB set in all but the last one. |
| The offset is then the number constructed by |
| concatenating the lower 7 bit of each byte, and |
| for n >= 2 adding 2^7 + 2^14 + ... + 2^(7*(n-1)) |
| to the result.</pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_version_2_pack_idx_files_support_packs_larger_than_4_gib_and">Version 2 pack-*.idx files support packs larger than 4 GiB, and</h2> |
| <div class="sectionbody"> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>have some other reorganizations. They have the format:</pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>A 4-byte magic number <em>\377tOc</em> which is an unreasonable |
| fanout[0] value.</p> |
| </li> |
| <li> |
| <p>A 4-byte version number (= 2)</p> |
| </li> |
| <li> |
| <p>A 256-entry fan-out table just like v1.</p> |
| </li> |
| <li> |
| <p>A table of sorted object names. These are packed together |
| without offset values to reduce the cache footprint of the |
| binary search for a specific object name.</p> |
| </li> |
| <li> |
| <p>A table of 4-byte CRC32 values of the packed object data. |
| This is new in v2 so compressed data can be copied directly |
| from pack to pack during repacking without undetected |
| data corruption.</p> |
| </li> |
| <li> |
| <p>A table of 4-byte offset values (in network byte order). |
| These are usually 31-bit pack file offsets, but large |
| offsets are encoded as an index into the next table with |
| the msbit set.</p> |
| </li> |
| <li> |
| <p>A table of 8-byte offset entries (empty for pack files less |
| than 2 GiB). Pack files are organized with heavily used |
| objects toward the front, so most object references should |
| not need to refer to this table.</p> |
| </li> |
| <li> |
| <p>The same trailer as a v1 pack file:</p> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>A copy of the pack checksum at the end of the |
| corresponding packfile.</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>Index checksum of all of the above.</pre> |
| </div> |
| </div> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_pack_rev_files_have_the_format">pack-*.rev files have the format:</h2> |
| <div class="sectionbody"> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>A 4-byte magic number <em>0x52494458</em> (<em>RIDX</em>).</p> |
| </li> |
| <li> |
| <p>A 4-byte version identifier (= 1).</p> |
| </li> |
| <li> |
| <p>A 4-byte hash function identifier (= 1 for SHA-1, 2 for SHA-256).</p> |
| </li> |
| <li> |
| <p>A table of index positions (one per packed object, num_objects in |
| total, each a 4-byte unsigned integer in network order), sorted by |
| their corresponding offsets in the packfile.</p> |
| </li> |
| <li> |
| <p>A trailer, containing a:</p> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>checksum of the corresponding packfile, and</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>a checksum of all of the above.</pre> |
| </div> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>All 4-byte numbers are in network order.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_pack_mtimes_files_have_the_format">pack-*.mtimes files have the format:</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>All 4-byte numbers are in network byte order.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>A 4-byte magic number <em>0x4d544d45</em> (<em>MTME</em>).</p> |
| </li> |
| <li> |
| <p>A 4-byte version identifier (= 1).</p> |
| </li> |
| <li> |
| <p>A 4-byte hash function identifier (= 1 for SHA-1, 2 for SHA-256).</p> |
| </li> |
| <li> |
| <p>A table of 4-byte unsigned integers. The ith value is the |
| modification time (mtime) of the ith object in the corresponding |
| pack by lexicographic (index) order. The mtimes count standard |
| epoch seconds.</p> |
| </li> |
| <li> |
| <p>A trailer, containing a checksum of the corresponding packfile, |
| and a checksum of all of the above (each having length according |
| to the specified hash function).</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_multi_pack_index_midx_files_have_the_following_format">multi-pack-index (MIDX) files have the following format:</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The multi-pack-index files refer to multiple pack-files and loose objects.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In order to allow extensions that add extra data to the MIDX, we organize |
| the body into "chunks" and provide a lookup table at the beginning of the |
| body. The header includes certain length values, such as the number of packs, |
| the number of base MIDX files, hash lengths and types.</p> |
| </div> |
| <div class="paragraph"> |
| <p>All 4-byte numbers are in network order.</p> |
| </div> |
| <div class="paragraph"> |
| <p>HEADER:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>4-byte signature: |
| The signature is: {'M', 'I', 'D', 'X'}</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>1-byte version number: |
| Git only writes or recognizes version 1.</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>1-byte Object Id Version |
| We infer the length of object IDs (OIDs) from this value: |
| 1 => SHA-1 |
| 2 => SHA-256 |
| If the hash type does not match the repository's hash algorithm, |
| the multi-pack-index file should be ignored with a warning |
| presented to the user.</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>1-byte number of "chunks"</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>1-byte number of base multi-pack-index files: |
| This value is currently always zero.</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>4-byte number of pack files</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>CHUNK LOOKUP:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>(C + 1) * 12 bytes providing the chunk offsets: |
| First 4 bytes describe chunk id. Value 0 is a terminating label. |
| Other 8 bytes provide offset in current file for chunk to start. |
| (Chunks are provided in file-order, so you can infer the length |
| using the next chunk position if necessary.)</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>The CHUNK LOOKUP matches the table of contents from |
| the chunk-based file format, see linkgit:gitformat-chunk[5].</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>The remaining data in the body is described one chunk at a time, and |
| these chunks may be given in any order. Chunks are required unless |
| otherwise specified.</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>CHUNK DATA:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>Packfile Names (ID: {'P', 'N', 'A', 'M'}) |
| Store the names of packfiles as a sequence of NUL-terminated |
| strings. There is no extra padding between the filenames, |
| and they are listed in lexicographic order. The chunk itself |
| is padded at the end with between 0 and 3 NUL bytes to make the |
| chunk size a multiple of 4 bytes.</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>Bitmapped Packfiles (ID: {'B', 'T', 'M', 'P'}) |
| Stores a table of two 4-byte unsigned integers in network order. |
| Each table entry corresponds to a single pack (in the order that |
| they appear above in the `PNAM` chunk). The values for each table |
| entry are as follows: |
| - The first bit position (in pseudo-pack order, see below) to |
| contain an object from that pack. |
| - The number of bits whose objects are selected from that pack.</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>OID Fanout (ID: {'O', 'I', 'D', 'F'}) |
| The ith entry, F[i], stores the number of OIDs with first |
| byte at most i. Thus F[255] stores the total |
| number of objects.</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>OID Lookup (ID: {'O', 'I', 'D', 'L'}) |
| The OIDs for all objects in the MIDX are stored in lexicographic |
| order in this chunk.</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>Object Offsets (ID: {'O', 'O', 'F', 'F'}) |
| Stores two 4-byte values for every object. |
| 1: The pack-int-id for the pack storing this object. |
| 2: The offset within the pack. |
| If all offsets are less than 2^32, then the large offset chunk |
| will not exist and offsets are stored as in IDX v1. |
| If there is at least one offset value larger than 2^32-1, then |
| the large offset chunk must exist, and offsets larger than |
| 2^31-1 must be stored in it instead. If the large offset chunk |
| exists and the 31st bit is on, then removing that bit reveals |
| the row in the large offsets containing the 8-byte offset of |
| this object.</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>[Optional] Object Large Offsets (ID: {'L', 'O', 'F', 'F'}) |
| 8-byte offsets into large packfiles.</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>[Optional] Bitmap pack order (ID: {'R', 'I', 'D', 'X'}) |
| A list of MIDX positions (one per object in the MIDX, num_objects in |
| total, each a 4-byte unsigned integer in network byte order), sorted |
| according to their relative bitmap/pseudo-pack positions.</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>TRAILER:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>Index checksum of the above contents.</pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_multi_pack_index_reverse_indexes">multi-pack-index reverse indexes</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Similar to the pack-based reverse index, the multi-pack index can also |
| be used to generate a reverse index.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Instead of mapping between offset, pack-, and index position, this |
| reverse index maps between an object’s position within the MIDX, and |
| that object’s position within a pseudo-pack that the MIDX describes |
| (i.e., the ith entry of the multi-pack reverse index holds the MIDX |
| position of ith object in pseudo-pack order).</p> |
| </div> |
| <div class="paragraph"> |
| <p>To clarify the difference between these orderings, consider a multi-pack |
| reachability bitmap (which does not yet exist, but is what we are |
| building towards here). Each bit needs to correspond to an object in the |
| MIDX, and so we need an efficient mapping from bit position to MIDX |
| position.</p> |
| </div> |
| <div class="paragraph"> |
| <p>One solution is to let bits occupy the same position in the oid-sorted |
| index stored by the MIDX. But because oids are effectively random, their |
| resulting reachability bitmaps would have no locality, and thus compress |
| poorly. (This is the reason that single-pack bitmaps use the pack |
| ordering, and not the .idx ordering, for the same purpose.)</p> |
| </div> |
| <div class="paragraph"> |
| <p>So we’d like to define an ordering for the whole MIDX based around |
| pack ordering, which has far better locality (and thus compresses more |
| efficiently). We can think of a pseudo-pack created by the concatenation |
| of all of the packs in the MIDX. E.g., if we had a MIDX with three packs |
| (a, b, c), with 10, 15, and 20 objects respectively, we can imagine an |
| ordering of the objects like:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>|a,0|a,1|...|a,9|b,0|b,1|...|b,14|c,0|c,1|...|c,19|</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>where the ordering of the packs is defined by the MIDX’s pack list, |
| and then the ordering of objects within each pack is the same as the |
| order in the actual packfile.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Given the list of packs and their counts of objects, you can |
| naïvely reconstruct that pseudo-pack ordering (e.g., the object at |
| position 27 must be (c,1) because packs "a" and "b" consumed 25 of the |
| slots). But there’s a catch. Objects may be duplicated between packs, in |
| which case the MIDX only stores one pointer to the object (and thus we’d |
| want only one slot in the bitmap).</p> |
| </div> |
| <div class="paragraph"> |
| <p>Callers could handle duplicates themselves by reading objects in order |
| of their bit-position, but that’s linear in the number of objects, and |
| much too expensive for ordinary bitmap lookups. Building a reverse index |
| solves this, since it is the logical inverse of the index, and that |
| index has already removed duplicates. But, building a reverse index on |
| the fly can be expensive. Since we already have an on-disk format for |
| pack-based reverse indexes, let’s reuse it for the MIDX’s pseudo-pack, |
| too.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Objects from the MIDX are ordered as follows to string together the |
| pseudo-pack. Let <code>pack</code>(<code>o</code>) return the pack from which <code>o</code> was selected |
| by the MIDX, and define an ordering of packs based on their numeric ID |
| (as stored by the MIDX). Let <code>offset</code>(<code>o</code>) return the object offset of <code>o</code> |
| within <code>pack</code>(<code>o</code>). Then, compare <code>o1</code> and <code>o2</code> as follows:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If one of <code>pack</code>(<code>o1</code>) and <code>pack</code>(<code>o2</code>) is preferred and the other |
| is not, then the preferred one sorts first.</p> |
| <div class="paragraph"> |
| <p>(This is a detail that allows the MIDX bitmap to determine which |
| pack should be used by the pack-reuse mechanism, since it can ask |
| the MIDX for the pack containing the object at bit position 0).</p> |
| </div> |
| </li> |
| <li> |
| <p>If <code>pack</code>(<code>o1</code>) ≠<code>pack</code>(<code>o2</code>), then sort the two objects in descending |
| order based on the pack ID.</p> |
| </li> |
| <li> |
| <p>Otherwise, <code>pack</code>(<code>o1</code>) <code>=</code> <code>pack</code>(<code>o2</code>), and the objects are sorted in |
| pack-order (i.e., <code>o1</code> sorts ahead of <code>o2</code> exactly when <code>offset</code>(<code>o1</code>) |
| < <code>offset</code>(<code>o2</code>)).</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>In short, a MIDX’s pseudo-pack is the de-duplicated concatenation of |
| objects in packs stored by the MIDX, laid out in pack order, and the |
| packs arranged in MIDX order (with the preferred pack coming first).</p> |
| </div> |
| <div class="paragraph"> |
| <p>The MIDX’s reverse index is stored in the optional <em>RIDX</em> chunk within |
| the MIDX itself.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_btmp_chunk"><code>BTMP</code> chunk</h3> |
| <div class="paragraph"> |
| <p>The Bitmapped Packfiles (<code>BTMP</code>) chunk encodes additional information |
| about the objects in the multi-pack index’s reachability bitmap. Recall |
| that objects from the MIDX are arranged in "pseudo-pack" order (see |
| above) for reachability bitmaps.</p> |
| </div> |
| <div class="paragraph"> |
| <p>From the example above, suppose we have packs "a", "b", and "c", with |
| 10, 15, and 20 objects, respectively. In pseudo-pack order, those would |
| be arranged as follows:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>|a,0|a,1|...|a,9|b,0|b,1|...|b,14|c,0|c,1|...|c,19|</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>When working with single-pack bitmaps (or, equivalently, multi-pack |
| reachability bitmaps with a preferred pack), <a href="git-pack-objects.html">git-pack-objects(1)</a> |
| performs “verbatim” reuse, attempting to reuse chunks of the bitmapped |
| or preferred packfile instead of adding objects to the packing list.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When a chunk of bytes is reused from an existing pack, any objects |
| contained therein do not need to be added to the packing list, saving |
| memory and CPU time. But a chunk from an existing packfile can only be |
| reused when the following conditions are met:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The chunk contains only objects which were requested by the caller |
| (i.e. does not contain any objects which the caller didn’t ask for |
| explicitly or implicitly).</p> |
| </li> |
| <li> |
| <p>All objects stored in non-thin packs as offset- or reference-deltas |
| also include their base object in the resulting pack.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>BTMP</code> chunk encodes the necessary information in order to implement |
| multi-pack reuse over a set of packfiles as described above. |
| Specifically, the <code>BTMP</code> chunk encodes three pieces of information (all |
| 32-bit unsigned integers in network byte-order) for each packfile <code>p</code> |
| that is stored in the MIDX, as follows:</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>bitmap_pos</code></dt> |
| <dd> |
| <p>The first bit position (in pseudo-pack order) in the |
| multi-pack index’s reachability bitmap occupied by an object from <code>p</code>.</p> |
| </dd> |
| <dt class="hdlist1"><code>bitmap_nr</code></dt> |
| <dd> |
| <p>The number of bit positions (including the one at |
| <code>bitmap_pos</code>) that encode objects from that pack <code>p</code>.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p>For example, the <code>BTMP</code> chunk corresponding to the above example (with |
| packs “a”, “b”, and “c”) would look like:</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 20%;"/> |
| <col style="width: 40%;"/> |
| <col style="width: 40%;"/> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top"></th> |
| <th class="tableblock halign-left valign-top"><code>bitmap_pos</code></th> |
| <th class="tableblock halign-left valign-top"><code>bitmap_nr</code></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">packfile “a”</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>0</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>10</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">packfile “b”</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>10</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>15</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">packfile “c”</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>25</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>20</code></p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>With this information in place, we can treat each packfile as |
| individually reusable in the same fashion as verbatim pack reuse is |
| performed on individual packs prior to the implementation of the <code>BTMP</code> |
| chunk.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_cruft_packs">cruft packs</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The cruft packs feature offer an alternative to Git’s traditional mechanism of |
| removing unreachable objects. This document provides an overview of Git’s |
| pruning mechanism, and how a cruft pack can be used instead to accomplish the |
| same.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_background">Background</h3> |
| <div class="paragraph"> |
| <p>To remove unreachable objects from your repository, Git offers <code>git</code> <code>repack</code> <code>-Ad</code> |
| (see <a href="git-repack.html">git-repack(1)</a>). Quoting from the documentation:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre>[...] unreachable objects in a previous pack become loose, unpacked objects, |
| instead of being left in the old pack. [...] loose unreachable objects will be |
| pruned according to normal expiry rules with the next 'git gc' invocation.</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Unreachable objects aren’t removed immediately, since doing so could race with |
| an incoming push which may reference an object which is about to be deleted. |
| Instead, those unreachable objects are stored as loose objects and stay that way |
| until they are older than the expiration window, at which point they are removed |
| by <a href="git-prune.html">git-prune(1)</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Git must store these unreachable objects loose in order to keep track of their |
| per-object mtimes. If these unreachable objects were written into one big pack, |
| then either freshening that pack (because an object contained within it was |
| re-written) or creating a new pack of unreachable objects would cause the pack’s |
| mtime to get updated, and the objects within it would never leave the expiration |
| window. Instead, objects are stored loose in order to keep track of the |
| individual object mtimes and avoid a situation where all cruft objects are |
| freshened at once.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This can lead to undesirable situations when a repository contains many |
| unreachable objects which have not yet left the grace period. Having large |
| directories in the shards of .<code>git/objects</code> can lead to decreased performance in |
| the repository. But given enough unreachable objects, this can lead to inode |
| starvation and degrade the performance of the whole system. Since we |
| can never pack those objects, these repositories often take up a large amount of |
| disk space, since we can only zlib compress them, but not store them in delta |
| chains.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_cruft_packs_2">Cruft packs</h3> |
| <div class="paragraph"> |
| <p>A cruft pack eliminates the need for storing unreachable objects in a loose |
| state by including the per-object mtimes in a separate file alongside a single |
| pack containing all loose objects.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A cruft pack is written by <code>git</code> <code>repack</code> <code>--cruft</code> when generating a new pack. |
| <a href="git-pack-objects.html">git-pack-objects(1)</a>'s <code>--cruft</code> option. Note that <code>git</code> <code>repack</code> <code>--cruft</code> |
| is a classic all-into-one repack, meaning that everything in the resulting pack is |
| reachable, and everything else is unreachable. Once written, the <code>--cruft</code> |
| option instructs <code>git</code> <code>repack</code> to generate another pack containing only objects |
| not packed in the previous step (which equates to packing all unreachable |
| objects together). This progresses as follows:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Enumerate every object, marking any object which is (a) not contained in a |
| kept-pack, and (b) whose mtime is within the grace period as a traversal |
| tip.</p> |
| </li> |
| <li> |
| <p>Perform a reachability traversal based on the tips gathered in the previous |
| step, adding every object along the way to the pack.</p> |
| </li> |
| <li> |
| <p>Write the pack out, along with a .<code>mtimes</code> file that records the per-object |
| timestamps.</p> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p>This mode is invoked internally by <a href="git-repack.html">git-repack(1)</a> when instructed to |
| write a cruft pack. Crucially, the set of in-core kept packs is exactly the set |
| of packs which will not be deleted by the repack; in other words, they contain |
| all of the repository’s reachable objects.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When a repository already has a cruft pack, <code>git</code> <code>repack</code> <code>--cruft</code> typically only |
| adds objects to it. An exception to this is when <code>git</code> <code>repack</code> is given the |
| <code>--cruft-expiration</code> option, which allows the generated cruft pack to omit |
| expired objects instead of waiting for <a href="git-gc.html">git-gc(1)</a> to expire those objects |
| later on.</p> |
| </div> |
| <div class="paragraph"> |
| <p>It is <a href="git-gc.html">git-gc(1)</a> that is typically responsible for removing expired |
| unreachable objects.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_alternatives">Alternatives</h3> |
| <div class="paragraph"> |
| <p>Notable alternatives to this design include:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The location of the per-object mtime data.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>On the location of mtime data, a new auxiliary file tied to the pack was chosen |
| to avoid complicating the .<code>idx</code> format. If the .<code>idx</code> format were ever to gain |
| support for optional chunks of data, it may make sense to consolidate the |
| .<code>mtimes</code> format into the .<code>idx</code> itself.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_git">GIT</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Part of the <a href="git.html">git(1)</a> suite</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div id="footer"> |
| <div id="footer-text"> |
| Last updated 2025-06-20 18:10:42 -0700 |
| </div> |
| </div> |
| </body> |
| </html> |
