1469 lines
65 KiB
HTML
1469 lines
65 KiB
HTML
<!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-03-17 07:09:38 UTC
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html> |