| <!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>git-fast-import(1)</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>git-fast-import(1) Manual Page</h1> |
| <h2 id="_name">NAME</h2> |
| <div class="sectionbody"> |
| <p>git-fast-import - Backend for fast Git data importers</p> |
| </div> |
| </div> |
| <div id="content"> |
| <div class="sect1"> |
| <h2 id="_synopsis">SYNOPSIS</h2> |
| <div class="sectionbody"> |
| <div class="verseblock"> |
| <pre class="content">frontend | <em>git fast-import</em> [<options>]</pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_description">DESCRIPTION</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>This program is usually not what the end user wants to run directly. |
| Most end users want to use one of the existing frontend programs, |
| which parses a specific type of foreign source and feeds the contents |
| stored there to <em>git fast-import</em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>fast-import reads a mixed command/data stream from standard input and |
| writes one or more packfiles directly into the current repository. |
| When EOF is received on standard input, fast import writes out |
| updated branch and tag refs, fully updating the current repository |
| with the newly imported data.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The fast-import backend itself can import into an empty repository (one that |
| has already been initialized by <em>git init</em>) or incrementally |
| update an existing populated repository. Whether or not incremental |
| imports are supported from a particular foreign source depends on |
| the frontend program in use.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_options">OPTIONS</h2> |
| <div class="sectionbody"> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">--force</dt> |
| <dd> |
| <p>Force updating modified existing branches, even if doing |
| so would cause commits to be lost (as the new commit does |
| not contain the old commit).</p> |
| </dd> |
| <dt class="hdlist1">--quiet</dt> |
| <dd> |
| <p>Disable the output shown by --stats, making fast-import usually |
| be silent when it is successful. However, if the import stream |
| has directives intended to show user output (e.g. <code>progress</code> |
| directives), the corresponding messages will still be shown.</p> |
| </dd> |
| <dt class="hdlist1">--stats</dt> |
| <dd> |
| <p>Display some basic statistics about the objects fast-import has |
| created, the packfiles they were stored into, and the |
| memory used by fast-import during this run. Showing this output |
| is currently the default, but can be disabled with --quiet.</p> |
| </dd> |
| <dt class="hdlist1">--allow-unsafe-features</dt> |
| <dd> |
| <p>Many command-line options can be provided as part of the |
| fast-import stream itself by using the <code>feature</code> or <code>option</code> |
| commands. However, some of these options are unsafe (e.g., |
| allowing fast-import to access the filesystem outside of the |
| repository). These options are disabled by default, but can be |
| allowed by providing this option on the command line. This |
| currently impacts only the <code>export-marks</code>, <code>import-marks</code>, and |
| <code>import-marks-if-exists</code> feature commands.</p> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>Only enable this option if you trust the program generating the |
| fast-import stream! This option is enabled automatically for |
| remote-helpers that use the `import` capability, as they are |
| already trusted to run their own code.</pre> |
| </div> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| <div class="sect2"> |
| <h3 id="_options_for_frontends">Options for Frontends</h3> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">--cat-blob-fd=<fd></dt> |
| <dd> |
| <p>Write responses to <code>get-mark</code>, <code>cat-blob</code>, and <code>ls</code> queries to the |
| file descriptor <fd> instead of <code>stdout</code>. Allows <code>progress</code> |
| output intended for the end-user to be separated from other |
| output.</p> |
| </dd> |
| <dt class="hdlist1">--date-format=<fmt></dt> |
| <dd> |
| <p>Specify the type of dates the frontend will supply to |
| fast-import within <code>author</code>, <code>committer</code> and <code>tagger</code> commands. |
| See “Date Formats” below for details about which formats |
| are supported, and their syntax.</p> |
| </dd> |
| <dt class="hdlist1">--done</dt> |
| <dd> |
| <p>Terminate with error if there is no <code>done</code> command at the end of |
| the stream. This option might be useful for detecting errors |
| that cause the frontend to terminate before it has started to |
| write a stream.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_locations_of_marks_files">Locations of Marks Files</h3> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">--export-marks=<file></dt> |
| <dd> |
| <p>Dumps the internal marks table to <file> when complete. |
| Marks are written one per line as <code>:markid</code> <code>SHA-1</code>. |
| Frontends can use this file to validate imports after they |
| have been completed, or to save the marks table across |
| incremental runs. As <file> is only opened and truncated |
| at checkpoint (or completion) the same path can also be |
| safely given to --import-marks.</p> |
| </dd> |
| <dt class="hdlist1">--import-marks=<file></dt> |
| <dd> |
| <p>Before processing any input, load the marks specified in |
| <file>. The input file must exist, must be readable, and |
| must use the same format as produced by --export-marks. |
| Multiple options may be supplied to import more than one |
| set of marks. If a mark is defined to different values, |
| the last file wins.</p> |
| </dd> |
| <dt class="hdlist1">--import-marks-if-exists=<file></dt> |
| <dd> |
| <p>Like --import-marks but instead of erroring out, silently |
| skips the file if it does not exist.</p> |
| </dd> |
| <dt class="hdlist1">--[no-]relative-marks</dt> |
| <dd> |
| <p>After specifying --relative-marks the paths specified |
| with --import-marks= and --export-marks= are relative |
| to an internal directory in the current repository. |
| In git-fast-import this means that the paths are relative |
| to the .git/info/fast-import directory. However, other |
| importers may use a different location.</p> |
| <div class="paragraph"> |
| <p>Relative and non-relative marks may be combined by interweaving |
| --(no-)-relative-marks with the --(import|export)-marks= options.</p> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_submodule_rewriting">Submodule Rewriting</h3> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">--rewrite-submodules-from=<name>:<file></dt> |
| <dt class="hdlist1">--rewrite-submodules-to=<name>:<file></dt> |
| <dd> |
| <p> Rewrite the object IDs for the submodule specified by <name> from the values |
| used in the from <file> to those used in the to <file>. The from marks should |
| have been created by <code>git</code> <code>fast-export</code>, and the to marks should have been |
| created by <code>git</code> <code>fast-import</code> when importing that same submodule.</p> |
| <div class="paragraph"> |
| <p><name> may be any arbitrary string not containing a colon character, but the |
| same value must be used with both options when specifying corresponding marks. |
| Multiple submodules may be specified with different values for <name>. It is an |
| error not to use these options in corresponding pairs.</p> |
| </div> |
| <div class="paragraph"> |
| <p>These options are primarily useful when converting a repository from one hash |
| algorithm to another; without them, fast-import will fail if it encounters a |
| submodule because it has no way of writing the object ID into the new hash |
| algorithm.</p> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_performance_and_compression_tuning">Performance and Compression Tuning</h3> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">--active-branches=<n></dt> |
| <dd> |
| <p>Maximum number of branches to maintain active at once. |
| See “Memory Utilization” below for details. Default is 5.</p> |
| </dd> |
| <dt class="hdlist1">--big-file-threshold=<n></dt> |
| <dd> |
| <p>Maximum size of a blob that fast-import will attempt to |
| create a delta for, expressed in bytes. The default is 512m |
| (512 MiB). Some importers may wish to lower this on systems |
| with constrained memory.</p> |
| </dd> |
| <dt class="hdlist1">--depth=<n></dt> |
| <dd> |
| <p>Maximum delta depth, for blob and tree deltification. |
| Default is 50.</p> |
| </dd> |
| <dt class="hdlist1">--export-pack-edges=<file></dt> |
| <dd> |
| <p>After creating a packfile, print a line of data to |
| <file> listing the filename of the packfile and the last |
| commit on each branch that was written to that packfile. |
| This information may be useful after importing projects |
| whose total object set exceeds the 4 GiB packfile limit, |
| as these commits can be used as edge points during calls |
| to <em>git pack-objects</em>.</p> |
| </dd> |
| <dt class="hdlist1">--max-pack-size=<n></dt> |
| <dd> |
| <p>Maximum size of each output packfile. |
| The default is unlimited.</p> |
| </dd> |
| <dt class="hdlist1">fastimport.unpackLimit</dt> |
| <dd> |
| <p>See <a href="git-config.html">git-config(1)</a></p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_performance">PERFORMANCE</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The design of fast-import allows it to import large projects in a minimum |
| amount of memory usage and processing time. Assuming the frontend |
| is able to keep up with fast-import and feed it a constant stream of data, |
| import times for projects holding 10+ years of history and containing |
| 100,000+ individual commits are generally completed in just 1-2 |
| hours on quite modest (~$2,000 USD) hardware.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Most bottlenecks appear to be in foreign source data access (the |
| source just cannot extract revisions fast enough) or disk IO (fast-import |
| writes as fast as the disk will take the data). Imports will run |
| faster if the source data is stored on a different drive than the |
| destination Git repository (due to less IO contention).</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_development_cost">DEVELOPMENT COST</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>A typical frontend for fast-import tends to weigh in at approximately 200 |
| lines of Perl/Python/Ruby code. Most developers have been able to |
| create working importers in just a couple of hours, even though it |
| is their first exposure to fast-import, and sometimes even to Git. This is |
| an ideal situation, given that most conversion tools are throw-away |
| (use once, and never look back).</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_parallel_operation">PARALLEL OPERATION</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Like <em>git push</em> or <em>git fetch</em>, imports handled by fast-import are safe to |
| run alongside parallel <code>git</code> <code>repack</code> <code>-a</code> <code>-d</code> or <code>git</code> <code>gc</code> invocations, |
| or any other Git operation (including <em>git prune</em>, as loose objects |
| are never used by fast-import).</p> |
| </div> |
| <div class="paragraph"> |
| <p>fast-import does not lock the branch or tag refs it is actively importing. |
| After the import, during its ref update phase, fast-import tests each |
| existing branch ref to verify the update will be a fast-forward |
| update (the commit stored in the ref is contained in the new |
| history of the commit to be written). If the update is not a |
| fast-forward update, fast-import will skip updating that ref and instead |
| prints a warning message. fast-import will always attempt to update all |
| branch refs, and does not stop on the first failure.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Branch updates can be forced with --force, but it’s recommended that |
| this only be used on an otherwise quiet repository. Using --force |
| is not necessary for an initial import into an empty repository.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_technical_discussion">TECHNICAL DISCUSSION</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>fast-import tracks a set of branches in memory. Any branch can be created |
| or modified at any point during the import process by sending a |
| <code>commit</code> command on the input stream. This design allows a frontend |
| program to process an unlimited number of branches simultaneously, |
| generating commits in the order they are available from the source |
| data. It also simplifies the frontend programs considerably.</p> |
| </div> |
| <div class="paragraph"> |
| <p>fast-import does not use or alter the current working directory, or any |
| file within it. (It does however update the current Git repository, |
| as referenced by <code>GIT_DIR</code>.) Therefore an import frontend may use |
| the working directory for its own purposes, such as extracting file |
| revisions from the foreign source. This ignorance of the working |
| directory also allows fast-import to run very quickly, as it does not |
| need to perform any costly file update operations when switching |
| between branches.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_input_format">INPUT FORMAT</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>With the exception of raw file data (which Git does not interpret) |
| the fast-import input format is text (ASCII) based. This text based |
| format simplifies development and debugging of frontend programs, |
| especially when a higher level language such as Perl, Python or |
| Ruby is being used.</p> |
| </div> |
| <div class="paragraph"> |
| <p>fast-import is very strict about its input. Where we say SP below we mean |
| <strong>exactly</strong> one space. Likewise LF means one (and only one) linefeed |
| and HT one (and only one) horizontal tab. |
| Supplying additional whitespace characters will cause unexpected |
| results, such as branch names or file names with leading or trailing |
| spaces in their name, or early termination of fast-import when it encounters |
| unexpected input.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_stream_comments">Stream Comments</h3> |
| <div class="paragraph"> |
| <p>To aid in debugging frontends fast-import ignores any line that |
| begins with # (ASCII pound/hash) up to and including the line |
| ending <code>LF</code>. A comment line may contain any sequence of bytes |
| that does not contain an LF and therefore may be used to include |
| any detailed debugging information that might be specific to the |
| frontend and useful when inspecting a fast-import data stream.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_date_formats">Date Formats</h3> |
| <div class="paragraph"> |
| <p>The following date formats are supported. A frontend should select |
| the format it will use for this import by passing the format name |
| in the --date-format=<fmt> command-line option.</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>raw</code></dt> |
| <dd> |
| <p>This is the Git native format and is <em><time></em> <code>SP</code> <em><offutc></em>. |
| It is also fast-import’s default format, if --date-format was |
| not specified.</p> |
| <div class="paragraph"> |
| <p>The time of the event is specified by <em><time></em> as the number of |
| seconds since the UNIX epoch (midnight, Jan 1, 1970, UTC) and is |
| written as an ASCII decimal integer.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The local offset is specified by <em><offutc></em> as a positive or negative |
| offset from UTC. For example EST (which is 5 hours behind UTC) |
| would be expressed in <em><tz></em> by “-0500” while UTC is “+0000”. |
| The local offset does not affect <em><time></em>; it is used only as an |
| advisement to help formatting routines display the timestamp.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If the local offset is not available in the source material, use |
| “+0000”, or the most common local offset. For example many |
| organizations have a CVS repository which has only ever been accessed |
| by users who are located in the same location and time zone. In this |
| case a reasonable offset from UTC could be assumed.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Unlike the <code>rfc2822</code> format, this format is very strict. Any |
| variation in formatting will cause fast-import to reject the value, |
| and some sanity checks on the numeric values may also be performed.</p> |
| </div> |
| </dd> |
| <dt class="hdlist1"><code>raw-permissive</code></dt> |
| <dd> |
| <p>This is the same as <code>raw</code> except that no sanity checks on |
| the numeric epoch and local offset are performed. This can |
| be useful when trying to filter or import an existing history |
| with e.g. bogus timezone values.</p> |
| </dd> |
| <dt class="hdlist1"><code>rfc2822</code></dt> |
| <dd> |
| <p>This is the standard date format as described by RFC 2822.</p> |
| <div class="paragraph"> |
| <p>An example value is “Tue Feb 6 11:22:18 2007 -0500”. The Git |
| parser is accurate, but a little on the lenient side. It is the |
| same parser used by <em>git am</em> when applying patches |
| received from email.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Some malformed strings may be accepted as valid dates. In some of |
| these cases Git will still be able to obtain the correct date from |
| the malformed string. There are also some types of malformed |
| strings which Git will parse wrong, and yet consider valid. |
| Seriously malformed strings will be rejected.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Unlike the <code>raw</code> format above, the time zone/UTC offset information |
| contained in an RFC 2822 date string is used to adjust the date |
| value to UTC prior to storage. Therefore it is important that |
| this information be as accurate as possible.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If the source material uses RFC 2822 style dates, |
| the frontend should let fast-import handle the parsing and conversion |
| (rather than attempting to do it itself) as the Git parser has |
| been well tested in the wild.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Frontends should prefer the <code>raw</code> format if the source material |
| already uses UNIX-epoch format, can be coaxed to give dates in that |
| format, or its format is easily convertible to it, as there is no |
| ambiguity in parsing.</p> |
| </div> |
| </dd> |
| <dt class="hdlist1"><code>now</code></dt> |
| <dd> |
| <p>Always use the current time and time zone. The literal |
| <code>now</code> must always be supplied for <em><when></em>.</p> |
| <div class="paragraph"> |
| <p>This is a toy format. The current time and time zone of this system |
| is always copied into the identity string at the time it is being |
| created by fast-import. There is no way to specify a different time or |
| time zone.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This particular format is supplied as it’s short to implement and |
| may be useful to a process that wants to create a new commit |
| right now, without needing to use a working directory or |
| <em>git update-index</em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If separate <code>author</code> and <code>committer</code> commands are used in a <code>commit</code> |
| the timestamps may not match, as the system clock will be polled |
| twice (once for each command). The only way to ensure that both |
| author and committer identity information has the same timestamp |
| is to omit <code>author</code> (thus copying from <code>committer</code>) or to use a |
| date format other than <code>now</code>.</p> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_commands">Commands</h3> |
| <div class="paragraph"> |
| <p>fast-import accepts several commands to update the current repository |
| and control the current import process. More detailed discussion |
| (with examples) of each command follows later.</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>commit</code></dt> |
| <dd> |
| <p>Creates a new branch or updates an existing branch by |
| creating a new commit and updating the branch to point at |
| the newly created commit.</p> |
| </dd> |
| <dt class="hdlist1"><code>tag</code></dt> |
| <dd> |
| <p>Creates an annotated tag object from an existing commit or |
| branch. Lightweight tags are not supported by this command, |
| as they are not recommended for recording meaningful points |
| in time.</p> |
| </dd> |
| <dt class="hdlist1"><code>reset</code></dt> |
| <dd> |
| <p>Reset an existing branch (or a new branch) to a specific |
| revision. This command must be used to change a branch to |
| a specific revision without making a commit on it.</p> |
| </dd> |
| <dt class="hdlist1"><code>blob</code></dt> |
| <dd> |
| <p>Convert raw file data into a blob, for future use in a |
| <code>commit</code> command. This command is optional and is not |
| needed to perform an import.</p> |
| </dd> |
| <dt class="hdlist1"><code>alias</code></dt> |
| <dd> |
| <p>Record that a mark refers to a given object without first |
| creating any new object. Using --import-marks and referring |
| to missing marks will cause fast-import to fail, so aliases |
| can provide a way to set otherwise pruned commits to a valid |
| value (e.g. the nearest non-pruned ancestor).</p> |
| </dd> |
| <dt class="hdlist1"><code>checkpoint</code></dt> |
| <dd> |
| <p>Forces fast-import to close the current packfile, generate its |
| unique SHA-1 checksum and index, and start a new packfile. |
| This command is optional and is not needed to perform |
| an import.</p> |
| </dd> |
| <dt class="hdlist1"><code>progress</code></dt> |
| <dd> |
| <p>Causes fast-import to echo the entire line to its own |
| standard output. This command is optional and is not needed |
| to perform an import.</p> |
| </dd> |
| <dt class="hdlist1"><code>done</code></dt> |
| <dd> |
| <p>Marks the end of the stream. This command is optional |
| unless the <code>done</code> feature was requested using the |
| <code>--done</code> command-line option or <code>feature</code> <code>done</code> command.</p> |
| </dd> |
| <dt class="hdlist1"><code>get-mark</code></dt> |
| <dd> |
| <p>Causes fast-import to print the SHA-1 corresponding to a mark |
| to the file descriptor set with <code>--cat-blob-fd</code>, or <code>stdout</code> if |
| unspecified.</p> |
| </dd> |
| <dt class="hdlist1"><code>cat-blob</code></dt> |
| <dd> |
| <p>Causes fast-import to print a blob in <em>cat-file --batch</em> |
| format to the file descriptor set with <code>--cat-blob-fd</code> or |
| <code>stdout</code> if unspecified.</p> |
| </dd> |
| <dt class="hdlist1"><code>ls</code></dt> |
| <dd> |
| <p>Causes fast-import to print a line describing a directory |
| entry in <em>ls-tree</em> format to the file descriptor set with |
| <code>--cat-blob-fd</code> or <code>stdout</code> if unspecified.</p> |
| </dd> |
| <dt class="hdlist1"><code>feature</code></dt> |
| <dd> |
| <p>Enable the specified feature. This requires that fast-import |
| supports the specified feature, and aborts if it does not.</p> |
| </dd> |
| <dt class="hdlist1"><code>option</code></dt> |
| <dd> |
| <p>Specify any of the options listed under OPTIONS that do not |
| change stream semantic to suit the frontend’s needs. This |
| command is optional and is not needed to perform an import.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_commit"><code>commit</code></h3> |
| <div class="paragraph"> |
| <p>Create or update a branch with a new commit, recording one logical |
| change to the project.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> 'commit' SP <ref> LF |
| mark? |
| original-oid? |
| ('author' (SP <name>)? SP LT <email> GT SP <when> LF)? |
| 'committer' (SP <name>)? SP LT <email> GT SP <when> LF |
| ('gpgsig' SP <algo> SP <format> LF data)? |
| ('encoding' SP <encoding> LF)? |
| data |
| ('from' SP <commit-ish> LF)? |
| ('merge' SP <commit-ish> LF)* |
| (filemodify | filedelete | filecopy | filerename | filedeleteall | notemodify)* |
| LF?</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>where <em><ref></em> is the name of the branch to make the commit on. |
| Typically branch names are prefixed with <code>refs/heads/</code> in |
| Git, so importing the CVS branch symbol <code>RELENG-1_0</code> would use |
| <code>refs/heads/RELENG-1_0</code> for the value of <em><ref></em>. The value of |
| <em><ref></em> must be a valid refname in Git. As <code>LF</code> is not valid in |
| a Git refname, no quoting or escaping syntax is supported here.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A <code>mark</code> command may optionally appear, requesting fast-import to save a |
| reference to the newly created commit for future use by the frontend |
| (see below for format). It is very common for frontends to mark |
| every commit they create, thereby allowing future branch creation |
| from any imported commit.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>data</code> command following <code>committer</code> must supply the commit |
| message (see below for <code>data</code> command syntax). To import an empty |
| commit message use a 0 length data. Commit messages are free-form |
| and are not interpreted by Git. Currently they must be encoded in |
| UTF-8, as fast-import does not permit other encodings to be specified.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Zero or more <code>filemodify</code>, <code>filedelete</code>, <code>filecopy</code>, <code>filerename</code>, |
| <code>filedeleteall</code> and <code>notemodify</code> commands |
| may be included to update the contents of the branch prior to |
| creating the commit. These commands may be supplied in any order. |
| However it is recommended that a <code>filedeleteall</code> command precede |
| all <code>filemodify</code>, <code>filecopy</code>, <code>filerename</code> and <code>notemodify</code> commands in |
| the same commit, as <code>filedeleteall</code> wipes the branch clean (see below).</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>LF</code> after the command is optional (it used to be required). Note |
| that for reasons of backward compatibility, if the commit ends with a |
| <code>data</code> command (i.e. it has no <code>from</code>, <code>merge</code>, <code>filemodify</code>, |
| <code>filedelete</code>, <code>filecopy</code>, <code>filerename</code>, <code>filedeleteall</code> or |
| <code>notemodify</code> commands) then two <code>LF</code> commands may appear at the end of |
| the command instead of just one.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_author"><code>author</code></h4> |
| <div class="paragraph"> |
| <p>An <code>author</code> command may optionally appear, if the author information |
| might differ from the committer information. If <code>author</code> is omitted |
| then fast-import will automatically use the committer’s information for |
| the author portion of the commit. See below for a description of |
| the fields in <code>author</code>, as they are identical to <code>committer</code>.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_committer"><code>committer</code></h4> |
| <div class="paragraph"> |
| <p>The <code>committer</code> command indicates who made this commit, and when |
| they made it.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Here <em><name></em> is the person’s display name (for example |
| “Com M Itter”) and <em><email></em> is the person’s email address |
| (“cm@example.com”). <code>LT</code> and <code>GT</code> are the literal less-than (\x3c) |
| and greater-than (\x3e) symbols. These are required to delimit |
| the email address from the other fields in the line. Note that |
| <em><name></em> and <em><email></em> are free-form and may contain any sequence |
| of bytes, except <code>LT</code>, <code>GT</code> and <code>LF</code>. <em><name></em> is typically UTF-8 encoded.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The time of the change is specified by <em><when></em> using the date format |
| that was selected by the --date-format=<fmt> command-line option. |
| See “Date Formats” above for the set of supported formats, and |
| their syntax.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_gpgsig"><code>gpgsig</code></h4> |
| <div class="paragraph"> |
| <p>The optional <code>gpgsig</code> command is used to include a PGP/GPG signature |
| or other cryptographic signature that signs the commit data.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> 'gpgsig' SP <git-hash-algo> SP <signature-format> LF data</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>gpgsig</code> command takes two arguments:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em><git-hash-algo></em> specifies which Git object format this signature |
| applies to, either <code>sha1</code> or <code>sha256</code>. This allows to know which |
| representation of the commit was signed (the SHA-1 or the SHA-256 |
| version) which helps with both signature verification and |
| interoperability between repos with different hash functions.</p> |
| </li> |
| <li> |
| <p><em><signature-format></em> specifies the type of signature, such as |
| <code>openpgp</code>, <code>x509</code>, <code>ssh</code>, or <code>unknown</code>. This is a convenience for |
| tools that process the stream, so they don’t have to parse the ASCII |
| armor to identify the signature type.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>A commit may have at most one signature for the SHA-1 object format |
| (stored in the "gpgsig" header) and one for the SHA-256 object format |
| (stored in the "gpgsig-sha256" header).</p> |
| </div> |
| <div class="paragraph"> |
| <p>See below for a detailed description of the <code>data</code> command which |
| contains the raw signature data.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Signatures are not yet checked in the current implementation |
| though. (Already setting the <code>extensions.compatObjectFormat</code> |
| configuration option might help with verifying both SHA-1 and SHA-256 |
| object format signatures when it will be implemented.)</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| This is highly experimental and the format of the <code>gpgsig</code> |
| command may change in the future without compatibility guarantees. |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_encoding"><code>encoding</code></h4> |
| <div class="paragraph"> |
| <p>The optional <code>encoding</code> command indicates the encoding of the commit |
| message. Most commits are UTF-8 and the encoding is omitted, but this |
| allows importing commit messages into git without first reencoding them.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_from"><code>from</code></h4> |
| <div class="paragraph"> |
| <p>The <code>from</code> command is used to specify the commit to initialize |
| this branch from. This revision will be the first ancestor of the |
| new commit. The state of the tree built at this commit will begin |
| with the state at the <code>from</code> commit, and be altered by the content |
| modifications in this commit.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Omitting the <code>from</code> command in the first commit of a new branch |
| will cause fast-import to create that commit with no ancestor. This |
| tends to be desired only for the initial commit of a project. |
| If the frontend creates all files from scratch when making a new |
| branch, a <code>merge</code> command may be used instead of <code>from</code> to start |
| the commit with an empty tree. |
| Omitting the <code>from</code> command on existing branches is usually desired, |
| as the current commit on that branch is automatically assumed to |
| be the first ancestor of the new commit.</p> |
| </div> |
| <div class="paragraph"> |
| <p>As <code>LF</code> is not valid in a Git refname or SHA-1 expression, no |
| quoting or escaping syntax is supported within <em><commit-ish></em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Here <em><commit-ish></em> is any of the following:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The name of an existing branch already in fast-import’s internal branch |
| table. If fast-import doesn’t know the name, it’s treated as a SHA-1 |
| expression.</p> |
| </li> |
| <li> |
| <p>A mark reference, <code>:</code><em><idnum></em>, where <em><idnum></em> is the mark number.</p> |
| <div class="paragraph"> |
| <p>The reason fast-import uses <code>:</code> to denote a mark reference is this character |
| is not legal in a Git branch name. The leading <code>:</code> makes it easy |
| to distinguish between the mark 42 (<code>:42</code>) and the branch 42 (<code>42</code> |
| or <code>refs/heads/42</code>), or an abbreviated SHA-1 which happened to |
| consist only of base-10 digits.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Marks must be declared (via <code>mark</code>) before they can be used.</p> |
| </div> |
| </li> |
| <li> |
| <p>A complete 40 byte or abbreviated commit SHA-1 in hex.</p> |
| </li> |
| <li> |
| <p>Any valid Git SHA-1 expression that resolves to a commit. See |
| “SPECIFYING REVISIONS” in <a href="gitrevisions.html">gitrevisions(7)</a> for details.</p> |
| </li> |
| <li> |
| <p>The special null SHA-1 (40 zeros) specifies that the branch is to be |
| removed.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The special case of restarting an incremental import from the |
| current branch value should be written as:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre> from refs/heads/branch^0</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>^0</code> suffix is necessary as fast-import does not permit a branch to |
| start from itself, and the branch is created in memory before the |
| <code>from</code> command is even read from the input. Adding <code>^0</code> will force |
| fast-import to resolve the commit through Git’s revision parsing library, |
| rather than its internal branch table, thereby loading in the |
| existing value of the branch.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_merge"><code>merge</code></h4> |
| <div class="paragraph"> |
| <p>Includes one additional ancestor commit. The additional ancestry |
| link does not change the way the tree state is built at this commit. |
| If the <code>from</code> command is |
| omitted when creating a new branch, the first <code>merge</code> commit will be |
| the first ancestor of the current commit, and the branch will start |
| out with no files. An unlimited number of <code>merge</code> commands per |
| commit are permitted by fast-import, thereby establishing an n-way merge.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Here <em><commit-ish></em> is any of the commit specification expressions |
| also accepted by <code>from</code> (see above).</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_filemodify"><code>filemodify</code></h4> |
| <div class="paragraph"> |
| <p>Included in a <code>commit</code> command to add a new file or change the |
| content of an existing file. This command has two different means |
| of specifying the content of the file.</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">External data format</dt> |
| <dd> |
| <p>The data content for the file was already supplied by a prior |
| <code>blob</code> command. The frontend just needs to connect it.</p> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> 'M' SP <mode> SP <dataref> SP <path> LF</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Here usually <em><dataref></em> must be either a mark reference (<code>:</code><em><idnum></em>) |
| set by a prior <code>blob</code> command, or a full 40-byte SHA-1 of an |
| existing Git blob object. If <em><mode></em> is <code>040000</code>` then |
| <em><dataref></em> must be the full 40-byte SHA-1 of an existing |
| Git tree object or a mark reference set with <code>--import-marks</code>.</p> |
| </div> |
| </dd> |
| <dt class="hdlist1">Inline data format</dt> |
| <dd> |
| <p>The data content for the file has not been supplied yet. |
| The frontend wants to supply it as part of this modify |
| command.</p> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> 'M' SP <mode> SP 'inline' SP <path> LF |
| data</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>See below for a detailed description of the <code>data</code> command.</p> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p>In both formats <em><mode></em> is the type of file entry, specified |
| in octal. Git only supports the following modes:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>100644</code> or <code>644</code>: A normal (not-executable) file. The majority |
| of files in most projects use this mode. If in doubt, this is |
| what you want.</p> |
| </li> |
| <li> |
| <p><code>100755</code> or <code>755</code>: A normal, but executable, file.</p> |
| </li> |
| <li> |
| <p><code>120000</code>: A symlink, the content of the file will be the link target.</p> |
| </li> |
| <li> |
| <p><code>160000</code>: A gitlink, SHA-1 of the object refers to a commit in |
| another repository. Git links can only be specified either by SHA or through |
| a commit mark. They are used to implement submodules.</p> |
| </li> |
| <li> |
| <p><code>040000</code>: A subdirectory. Subdirectories can only be specified by |
| SHA or through a tree mark set with <code>--import-marks</code>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>In both formats <em><path></em> is the complete path of the file to be added |
| (if not already existing) or modified (if already existing).</p> |
| </div> |
| <div class="paragraph"> |
| <p>A <em><path></em> can be written as unquoted bytes or a C-style quoted string.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When a <em><path></em> does not start with a double quote ("), it is an |
| unquoted string and is parsed as literal bytes without any escape |
| sequences. However, if the filename contains <code>LF</code> or starts with double |
| quote, it cannot be represented as an unquoted string and must be |
| quoted. Additionally, the source <em><path></em> in <code>filecopy</code> or <code>filerename</code> |
| must be quoted if it contains SP.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When a <em><path></em> starts with a double quote ("), it is a C-style quoted |
| string, where the complete filename is enclosed in a pair of double |
| quotes and escape sequences are used. Certain characters must be escaped |
| by preceding them with a backslash: <code>LF</code> is written as <code>\n</code>, backslash |
| as <code>\\</code>, and double quote as <code>\</code>". Some characters may optionally be |
| written with escape sequences: <code>\a</code> for bell, <code>\b</code> for backspace, <code>\f</code> |
| for form feed, <code>\n</code> for line feed, <code>\r</code> for carriage return, <code>\t</code> for |
| horizontal tab, and <code>\v</code> for vertical tab. Any byte can be written with |
| 3-digit octal codes (e.g., <code>\033</code>). All filenames can be represented as |
| quoted strings.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A <em><path></em> must use UNIX-style directory separators (forward slash <code>/</code>) |
| and its value must be in canonical form. That is it must not:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>contain an empty directory component (e.g. <code>foo//bar</code> is invalid),</p> |
| </li> |
| <li> |
| <p>end with a directory separator (e.g. <code>foo/</code> is invalid),</p> |
| </li> |
| <li> |
| <p>start with a directory separator (e.g. <code>/foo</code> is invalid),</p> |
| </li> |
| <li> |
| <p>contain the special component . or <code>..</code> (e.g. <code>foo/./bar</code> and |
| <code>foo/</code><code>..</code><code>/bar</code> are invalid).</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The root of the tree can be represented by an empty string as <em><path></em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em><path></em> cannot contain NUL, either literally or escaped as <code>\000</code>. |
| It is recommended that <em><path></em> always be encoded using UTF-8.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_filedelete"><code>filedelete</code></h4> |
| <div class="paragraph"> |
| <p>Included in a <code>commit</code> command to remove a file or recursively |
| delete an entire directory from the branch. If the file or directory |
| removal makes its parent directory empty, the parent directory will |
| be automatically removed too. This cascades up the tree until the |
| first non-empty directory or the root is reached.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> 'D' SP <path> LF</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>here <em><path></em> is the complete path of the file or subdirectory to |
| be removed from the branch. |
| See <code>filemodify</code> above for a detailed description of <em><path></em>.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_filecopy"><code>filecopy</code></h4> |
| <div class="paragraph"> |
| <p>Recursively copies an existing file or subdirectory to a different |
| location within the branch. The existing file or directory must |
| exist. If the destination exists it will be completely replaced |
| by the content copied from the source.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> 'C' SP <path> SP <path> LF</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>here the first <em><path></em> is the source location and the second |
| <em><path></em> is the destination. See <code>filemodify</code> above for a detailed |
| description of what <em><path></em> may look like. To use a source path |
| that contains SP the path must be quoted.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A <code>filecopy</code> command takes effect immediately. Once the source |
| location has been copied to the destination any future commands |
| applied to the source location will not impact the destination of |
| the copy.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_filerename"><code>filerename</code></h4> |
| <div class="paragraph"> |
| <p>Renames an existing file or subdirectory to a different location |
| within the branch. The existing file or directory must exist. If |
| the destination exists it will be replaced by the source directory.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> 'R' SP <path> SP <path> LF</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>here the first <em><path></em> is the source location and the second |
| <em><path></em> is the destination. See <code>filemodify</code> above for a detailed |
| description of what <em><path></em> may look like. To use a source path |
| that contains SP the path must be quoted.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A <code>filerename</code> command takes effect immediately. Once the source |
| location has been renamed to the destination any future commands |
| applied to the source location will create new files there and not |
| impact the destination of the rename.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Note that a <code>filerename</code> is the same as a <code>filecopy</code> followed by a |
| <code>filedelete</code> of the source location. There is a slight performance |
| advantage to using <code>filerename</code>, but the advantage is so small |
| that it is never worth trying to convert a delete/add pair in |
| source material into a rename for fast-import. This <code>filerename</code> |
| command is provided just to simplify frontends that already have |
| rename information and don’t want bother with decomposing it into a |
| <code>filecopy</code> followed by a <code>filedelete</code>.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_filedeleteall"><code>filedeleteall</code></h4> |
| <div class="paragraph"> |
| <p>Included in a <code>commit</code> command to remove all files (and also all |
| directories) from the branch. This command resets the internal |
| branch structure to have no files in it, allowing the frontend |
| to subsequently add all interesting files from scratch.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> 'deleteall' LF</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This command is extremely useful if the frontend does not know |
| (or does not care to know) what files are currently on the branch, |
| and therefore cannot generate the proper <code>filedelete</code> commands to |
| update the content.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Issuing a <code>filedeleteall</code> followed by the needed <code>filemodify</code> |
| commands to set the correct content will produce the same results |
| as sending only the needed <code>filemodify</code> and <code>filedelete</code> commands. |
| The <code>filedeleteall</code> approach may however require fast-import to use slightly |
| more memory per active branch (less than 1 MiB for even most large |
| projects); so frontends that can easily obtain only the affected |
| paths for a commit are encouraged to do so.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_notemodify"><code>notemodify</code></h4> |
| <div class="paragraph"> |
| <p>Included in a <code>commit</code> <em><notes-ref></em> command to add a new note |
| annotating a <em><commit-ish></em> or change this annotation contents. |
| Internally it is similar to filemodify 100644 on <em><commit-ish></em> |
| path (maybe split into subdirectories). It’s not advised to |
| use any other commands to write to the <em><notes-ref></em> tree except |
| <code>filedeleteall</code> to delete all existing notes in this tree. |
| This command has two different means of specifying the content |
| of the note.</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">External data format</dt> |
| <dd> |
| <p>The data content for the note was already supplied by a prior |
| <code>blob</code> command. The frontend just needs to connect it to the |
| commit that is to be annotated.</p> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> 'N' SP <dataref> SP <commit-ish> LF</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Here <em><dataref></em> can be either a mark reference (<code>:</code><em><idnum></em>) |
| set by a prior <code>blob</code> command, or a full 40-byte SHA-1 of an |
| existing Git blob object.</p> |
| </div> |
| </dd> |
| <dt class="hdlist1">Inline data format</dt> |
| <dd> |
| <p>The data content for the note has not been supplied yet. |
| The frontend wants to supply it as part of this modify |
| command.</p> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> 'N' SP 'inline' SP <commit-ish> LF |
| data</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>See below for a detailed description of the <code>data</code> command.</p> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p>In both formats <em><commit-ish></em> is any of the commit specification |
| expressions also accepted by <code>from</code> (see above).</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_mark"><code>mark</code></h3> |
| <div class="paragraph"> |
| <p>Arranges for fast-import to save a reference to the current object, allowing |
| the frontend to recall this object at a future point in time, without |
| knowing its SHA-1. Here the current object is the object creation |
| command the <code>mark</code> command appears within. This can be <code>commit</code>, |
| <code>tag</code>, and <code>blob</code>, but <code>commit</code> is the most common usage.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> 'mark' SP ':' <idnum> LF</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>where <em><idnum></em> is the number assigned by the frontend to this mark. |
| The value of <em><idnum></em> is expressed as an ASCII decimal integer. |
| The value 0 is reserved and cannot be used as |
| a mark. Only values greater than or equal to 1 may be used as marks.</p> |
| </div> |
| <div class="paragraph"> |
| <p>New marks are created automatically. Existing marks can be moved |
| to another object simply by reusing the same <em><idnum></em> in another |
| <code>mark</code> command.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_original_oid"><code>original-oid</code></h3> |
| <div class="paragraph"> |
| <p>Provides the name of the object in the original source control system. |
| fast-import will simply ignore this directive, but filter processes |
| which operate on and modify the stream before feeding to fast-import |
| may have uses for this information</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> 'original-oid' SP <object-identifier> LF</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>where <em><object-identifier></em> is any string not containing LF.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_tag"><code>tag</code></h3> |
| <div class="paragraph"> |
| <p>Creates an annotated tag referring to a specific commit. To create |
| lightweight (non-annotated) tags see the <code>reset</code> command below.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> 'tag' SP <name> LF |
| mark? |
| 'from' SP <commit-ish> LF |
| original-oid? |
| 'tagger' (SP <name>)? SP LT <email> GT SP <when> LF |
| data</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>where <em><name></em> is the name of the tag to create.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Tag names are automatically prefixed with <code>refs/tags/</code> when stored |
| in Git, so importing the CVS branch symbol <code>RELENG-1_0-FINAL</code> would |
| use just <code>RELENG-1_0-FINAL</code> for <em><name></em>, and fast-import will write the |
| corresponding ref as <code>refs/tags/RELENG-1_0-FINAL</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The value of <em><name></em> must be a valid refname in Git and therefore |
| may contain forward slashes. As <code>LF</code> is not valid in a Git refname, |
| no quoting or escaping syntax is supported here.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>from</code> command is the same as in the <code>commit</code> command; see |
| above for details.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>tagger</code> command uses the same format as <code>committer</code> within |
| <code>commit</code>; again see above for details.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>data</code> command following <code>tagger</code> must supply the annotated tag |
| message (see below for <code>data</code> command syntax). To import an empty |
| tag message use a 0 length data. Tag messages are free-form and are |
| not interpreted by Git. Currently they must be encoded in UTF-8, |
| as fast-import does not permit other encodings to be specified.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Signing annotated tags during import from within fast-import is not |
| supported. Trying to include your own PGP/GPG signature is not |
| recommended, as the frontend does not (easily) have access to the |
| complete set of bytes which normally goes into such a signature. |
| If signing is required, create lightweight tags from within fast-import with |
| <code>reset</code>, then create the annotated versions of those tags offline |
| with the standard <em>git tag</em> process.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_reset"><code>reset</code></h3> |
| <div class="paragraph"> |
| <p>Creates (or recreates) the named branch, optionally starting from |
| a specific revision. The reset command allows a frontend to issue |
| a new <code>from</code> command for an existing branch, or to create a new |
| branch from an existing commit without creating a new commit.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> 'reset' SP <ref> LF |
| ('from' SP <commit-ish> LF)? |
| LF?</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>For a detailed description of <em><ref></em> and <em><commit-ish></em> see above |
| under <code>commit</code> and <code>from</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>LF</code> after the command is optional (it used to be required).</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>reset</code> command can also be used to create lightweight |
| (non-annotated) tags. For example:</p> |
| </div> |
| <div class="exampleblock"> |
| <div class="content"> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>reset refs/tags/938 |
| from :938</pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>would create the lightweight tag <code>refs/tags/938</code> referring to |
| whatever commit mark <code>:938</code> references.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_blob"><code>blob</code></h3> |
| <div class="paragraph"> |
| <p>Requests writing one file revision to the packfile. The revision |
| is not connected to any commit; this connection must be formed in |
| a subsequent <code>commit</code> command by referencing the blob through an |
| assigned mark.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> 'blob' LF |
| mark? |
| original-oid? |
| data</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The mark command is optional here as some frontends have chosen |
| to generate the Git SHA-1 for the blob on their own, and feed that |
| directly to <code>commit</code>. This is typically more work than it’s worth |
| however, as marks are inexpensive to store and easy to use.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_data"><code>data</code></h3> |
| <div class="paragraph"> |
| <p>Supplies raw data (for use as blob/file content, commit messages, or |
| annotated tag messages) to fast-import. Data can be supplied using an exact |
| byte count or delimited with a terminating line. Real frontends |
| intended for production-quality conversions should always use the |
| exact byte count format, as it is more robust and performs better. |
| The delimited format is intended primarily for testing fast-import.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Comment lines appearing within the <em><raw></em> part of <code>data</code> commands |
| are always taken to be part of the body of the data and are therefore |
| never ignored by fast-import. This makes it safe to import any |
| file/message content whose lines might start with #.</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Exact byte count format</dt> |
| <dd> |
| <p>The frontend must specify the number of bytes of data.</p> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> 'data' SP <count> LF |
| <raw> LF?</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>where <em><count></em> is the exact number of bytes appearing within |
| <em><raw></em>. The value of <em><count></em> is expressed as an ASCII decimal |
| integer. The <code>LF</code> on either side of <em><raw></em> is not |
| included in <em><count></em> and will not be included in the imported data.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>LF</code> after <em><raw></em> is optional (it used to be required) but |
| recommended. Always including it makes debugging a fast-import |
| stream easier as the next command always starts in column 0 |
| of the next line, even if <em><raw></em> did not end with an <code>LF</code>.</p> |
| </div> |
| </dd> |
| <dt class="hdlist1">Delimited format</dt> |
| <dd> |
| <p>A delimiter string is used to mark the end of the data. |
| fast-import will compute the length by searching for the delimiter. |
| This format is primarily useful for testing and is not |
| recommended for real data.</p> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> 'data' SP '<<' <delim> LF |
| <raw> LF |
| <delim> LF |
| LF?</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>where <em><delim></em> is the chosen delimiter string. The string <em><delim></em> |
| must not appear on a line by itself within <em><raw></em>, as otherwise |
| fast-import will think the data ends earlier than it really does. The <code>LF</code> |
| immediately trailing <em><raw></em> is part of <em><raw></em>. This is one of |
| the limitations of the delimited format, it is impossible to supply |
| a data chunk which does not have an LF as its last byte.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>LF</code> after <em><delim></em> <code>LF</code> is optional (it used to be required).</p> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_alias"><code>alias</code></h3> |
| <div class="paragraph"> |
| <p>Record that a mark refers to a given object without first creating any |
| new object.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> 'alias' LF |
| mark |
| 'to' SP <commit-ish> LF |
| LF?</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>For a detailed description of <em><commit-ish></em> see above under <code>from</code>.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_checkpoint"><code>checkpoint</code></h3> |
| <div class="paragraph"> |
| <p>Forces fast-import to close the current packfile, start a new one, and to |
| save out all current branch refs, tags and marks.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> 'checkpoint' LF |
| LF?</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Note that fast-import automatically switches packfiles when the current |
| packfile reaches --max-pack-size, or 4 GiB, whichever limit is |
| smaller. During an automatic packfile switch fast-import does not update |
| the branch refs, tags or marks.</p> |
| </div> |
| <div class="paragraph"> |
| <p>As a <code>checkpoint</code> can require a significant amount of CPU time and |
| disk IO (to compute the overall pack SHA-1 checksum, generate the |
| corresponding index file, and update the refs) it can easily take |
| several minutes for a single <code>checkpoint</code> command to complete.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Frontends may choose to issue checkpoints during extremely large |
| and long running imports, or when they need to allow another Git |
| process access to a branch. However given that a 30 GiB Subversion |
| repository can be loaded into Git through fast-import in about 3 hours, |
| explicit checkpointing may not be necessary.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>LF</code> after the command is optional (it used to be required).</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_progress"><code>progress</code></h3> |
| <div class="paragraph"> |
| <p>Causes fast-import to print the entire <code>progress</code> line unmodified to |
| its standard output channel (file descriptor 1) when the command is |
| processed from the input stream. The command otherwise has no impact |
| on the current import, or on any of fast-import’s internal state.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> 'progress' SP <any> LF |
| LF?</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <em><any></em> part of the command may contain any sequence of bytes |
| that does not contain <code>LF</code>. The <code>LF</code> after the command is optional. |
| Callers may wish to process the output through a tool such as sed to |
| remove the leading part of the line, for example:</p> |
| </div> |
| <div class="exampleblock"> |
| <div class="content"> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>frontend | git fast-import | sed 's/^progress //'</pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Placing a <code>progress</code> command immediately after a <code>checkpoint</code> will |
| inform the reader when the <code>checkpoint</code> has been completed and it |
| can safely access the refs that fast-import updated.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_get_mark"><code>get-mark</code></h3> |
| <div class="paragraph"> |
| <p>Causes fast-import to print the SHA-1 corresponding to a mark to |
| stdout or to the file descriptor previously arranged with the |
| <code>--cat-blob-fd</code> argument. The command otherwise has no impact on the |
| current import; its purpose is to retrieve SHA-1s that later commits |
| might want to refer to in their commit messages.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> 'get-mark' SP ':' <idnum> LF</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>See “Responses To Commands” below for details about how to read |
| this output safely.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_cat_blob"><code>cat-blob</code></h3> |
| <div class="paragraph"> |
| <p>Causes fast-import to print a blob to a file descriptor previously |
| arranged with the <code>--cat-blob-fd</code> argument. The command otherwise |
| has no impact on the current import; its main purpose is to |
| retrieve blobs that may be in fast-import’s memory but not |
| accessible from the target repository.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> 'cat-blob' SP <dataref> LF</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <em><dataref></em> can be either a mark reference (<code>:</code><em><idnum></em>) |
| set previously or a full 40-byte SHA-1 of a Git blob, preexisting or |
| ready to be written.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Output uses the same format as <code>git</code> <code>cat-file</code> <code>--batch</code>:</p> |
| </div> |
| <div class="exampleblock"> |
| <div class="content"> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre><sha1> SP 'blob' SP <size> LF |
| <contents> LF</pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This command can be used where a <code>filemodify</code> directive can appear, |
| allowing it to be used in the middle of a commit. For a <code>filemodify</code> |
| using an inline directive, it can also appear right before the <code>data</code> |
| directive.</p> |
| </div> |
| <div class="paragraph"> |
| <p>See “Responses To Commands” below for details about how to read |
| this output safely.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_ls"><code>ls</code></h3> |
| <div class="paragraph"> |
| <p>Prints information about the object at a path to a file descriptor |
| previously arranged with the <code>--cat-blob-fd</code> argument. This allows |
| printing a blob from the active commit (with <code>cat-blob</code>) or copying a |
| blob or tree from a previous commit for use in the current one (with |
| <code>filemodify</code>).</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>ls</code> command can also be used where a <code>filemodify</code> directive can |
| appear, allowing it to be used in the middle of a commit.</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Reading from the active commit</dt> |
| <dd> |
| <p>This form can only be used in the middle of a <code>commit</code>. |
| The path names a directory entry within fast-import’s |
| active commit. The path must be quoted in this case.</p> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> 'ls' SP <path> LF</pre> |
| </div> |
| </div> |
| </dd> |
| <dt class="hdlist1">Reading from a named tree</dt> |
| <dd> |
| <p>The <em><dataref></em> can be a mark reference (<code>:</code><em><idnum></em>) or the |
| full 40-byte SHA-1 of a Git tag, commit, or tree object, |
| preexisting or waiting to be written. |
| The path is relative to the top level of the tree |
| named by <em><dataref></em>.</p> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> 'ls' SP <dataref> SP <path> LF</pre> |
| </div> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p>See <code>filemodify</code> above for a detailed description of <em><path></em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Output uses the same format as <code>git</code> <code>ls-tree</code> <em><tree></em> <code>--</code> <em><path></em>:</p> |
| </div> |
| <div class="exampleblock"> |
| <div class="content"> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre><mode> SP ('blob' | 'tree' | 'commit') SP <dataref> HT <path> LF</pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <dataref> represents the blob, tree, or commit object at <path> |
| and can be used in later <em>get-mark</em>, <em>cat-blob</em>, <em>filemodify</em>, or |
| <em>ls</em> commands.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If there is no file or subtree at that path, <em>git fast-import</em> will |
| instead report</p> |
| </div> |
| <div class="exampleblock"> |
| <div class="content"> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>missing SP <path> LF</pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>See “Responses To Commands” below for details about how to read |
| this output safely.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_feature"><code>feature</code></h3> |
| <div class="paragraph"> |
| <p>Require that fast-import supports the specified feature, or abort if |
| it does not.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> 'feature' SP <feature> ('=' <argument>)? LF</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <feature> part of the command may be any one of the following:</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">date-format</dt> |
| <dt class="hdlist1">export-marks</dt> |
| <dt class="hdlist1">relative-marks</dt> |
| <dt class="hdlist1">no-relative-marks</dt> |
| <dt class="hdlist1">force</dt> |
| <dd> |
| <p>Act as though the corresponding command-line option with |
| a leading <code>--</code> was passed on the command line |
| (see OPTIONS, above).</p> |
| </dd> |
| <dt class="hdlist1">import-marks</dt> |
| <dt class="hdlist1">import-marks-if-exists</dt> |
| <dd> |
| <p>Like --import-marks except in two respects: first, only one |
| "feature import-marks" or "feature import-marks-if-exists" |
| command is allowed per stream; second, an --import-marks= |
| or --import-marks-if-exists command-line option overrides |
| any of these "feature" commands in the stream; third, |
| "feature import-marks-if-exists" like a corresponding |
| command-line option silently skips a nonexistent file.</p> |
| </dd> |
| <dt class="hdlist1">get-mark</dt> |
| <dt class="hdlist1">cat-blob</dt> |
| <dt class="hdlist1">ls</dt> |
| <dd> |
| <p>Require that the backend support the <em>get-mark</em>, <em>cat-blob</em>, |
| or <em>ls</em> command respectively. |
| Versions of fast-import not supporting the specified command |
| will exit with a message indicating so. |
| This lets the import error out early with a clear message, |
| rather than wasting time on the early part of an import |
| before the unsupported command is detected.</p> |
| </dd> |
| <dt class="hdlist1">notes</dt> |
| <dd> |
| <p>Require that the backend support the <em>notemodify</em> (N) |
| subcommand to the <em>commit</em> command. |
| Versions of fast-import not supporting notes will exit |
| with a message indicating so.</p> |
| </dd> |
| <dt class="hdlist1">done</dt> |
| <dd> |
| <p>Error out if the stream ends without a <em>done</em> command. |
| Without this feature, errors causing the frontend to end |
| abruptly at a convenient point in the stream can go |
| undetected. This may occur, for example, if an import |
| front end dies in mid-operation without emitting SIGTERM |
| or SIGKILL at its subordinate git fast-import instance.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_option"><code>option</code></h3> |
| <div class="paragraph"> |
| <p>Processes the specified option so that git fast-import behaves in a |
| way that suits the frontend’s needs. |
| Note that options specified by the frontend are overridden by any |
| options the user may specify to git fast-import itself.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre> 'option' SP <option> LF</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <em><option></em> part of the command may contain any of the options |
| listed in the OPTIONS section that do not change import semantics, |
| without the leading <code>--</code> and is treated in the same way.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Option commands must be the first commands on the input (not counting |
| feature commands), to give an option command after any non-option |
| command is an error.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following command-line options change import semantics and may therefore |
| not be passed as option:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>date-format</p> |
| </li> |
| <li> |
| <p>import-marks</p> |
| </li> |
| <li> |
| <p>export-marks</p> |
| </li> |
| <li> |
| <p>cat-blob-fd</p> |
| </li> |
| <li> |
| <p>force</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_done"><code>done</code></h3> |
| <div class="paragraph"> |
| <p>If the <code>done</code> feature is not in use, treated as if EOF was read. |
| This can be used to tell fast-import to finish early.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If the <code>--done</code> command-line option or <code>feature</code> <code>done</code> command is |
| in use, the <code>done</code> command is mandatory and marks the end of the |
| stream.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_responses_to_commands">RESPONSES TO COMMANDS</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>New objects written by fast-import are not available immediately. |
| Most fast-import commands have no visible effect until the next |
| checkpoint (or completion). The frontend can send commands to |
| fill fast-import’s input pipe without worrying about how quickly |
| they will take effect, which improves performance by simplifying |
| scheduling.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For some frontends, though, it is useful to be able to read back |
| data from the current repository as it is being updated (for |
| example when the source material describes objects in terms of |
| patches to be applied to previously imported objects). This can |
| be accomplished by connecting the frontend and fast-import via |
| bidirectional pipes:</p> |
| </div> |
| <div class="exampleblock"> |
| <div class="content"> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>mkfifo fast-import-output |
| frontend <fast-import-output | |
| git fast-import >fast-import-output</pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>A frontend set up this way can use <code>progress</code>, <code>get-mark</code>, <code>ls</code>, and |
| <code>cat-blob</code> commands to read information from the import in progress.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To avoid deadlock, such frontends must completely consume any |
| pending output from <code>progress</code>, <code>ls</code>, <code>get-mark</code>, and <code>cat-blob</code> before |
| performing writes to fast-import that might block.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_crash_reports">CRASH REPORTS</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>If fast-import is supplied invalid input it will terminate with a |
| non-zero exit status and create a crash report in the top level of |
| the Git repository it was importing into. Crash reports contain |
| a snapshot of the internal fast-import state as well as the most |
| recent commands that lead up to the crash.</p> |
| </div> |
| <div class="paragraph"> |
| <p>All recent commands (including stream comments, file changes and |
| progress commands) are shown in the command history within the crash |
| report, but raw file data and commit messages are excluded from the |
| crash report. This exclusion saves space within the report file |
| and reduces the amount of buffering that fast-import must perform |
| during execution.</p> |
| </div> |
| <div class="paragraph"> |
| <p>After writing a crash report fast-import will close the current |
| packfile and export the marks table. This allows the frontend |
| developer to inspect the repository state and resume the import from |
| the point where it crashed. The modified branches and tags are not |
| updated during a crash, as the import did not complete successfully. |
| Branch and tag information can be found in the crash report and |
| must be applied manually if the update is needed.</p> |
| </div> |
| <div class="paragraph"> |
| <p>An example crash:</p> |
| </div> |
| <div class="exampleblock"> |
| <div class="content"> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>$ cat >in <<END_OF_INPUT |
| # my very first test commit |
| commit refs/heads/master |
| committer Shawn O. Pearce <spearce> 19283 -0400 |
| # who is that guy anyway? |
| data <<EOF |
| this is my commit |
| EOF |
| M 644 inline .gitignore |
| data <<EOF |
| .gitignore |
| EOF |
| M 777 inline bob |
| END_OF_INPUT</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>$ git fast-import <in |
| fatal: Corrupt mode: M 777 inline bob |
| fast-import: dumping crash report to .git/fast_import_crash_8434</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>$ cat .git/fast_import_crash_8434 |
| fast-import crash report: |
| fast-import process: 8434 |
| parent process : 1391 |
| at Sat Sep 1 00:58:12 2007</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>fatal: Corrupt mode: M 777 inline bob</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>Most Recent Commands Before Crash |
| --------------------------------- |
| # my very first test commit |
| commit refs/heads/master |
| committer Shawn O. Pearce <spearce> 19283 -0400 |
| # who is that guy anyway? |
| data <<EOF |
| M 644 inline .gitignore |
| data <<EOF |
| * M 777 inline bob</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>Active Branch LRU |
| ----------------- |
| active_branches = 1 cur, 5 max</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>pos clock name |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1) 0 refs/heads/master</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>Inactive Branches |
| ----------------- |
| refs/heads/master: |
| status : active loaded dirty |
| tip commit : 0000000000000000000000000000000000000000 |
| old tree : 0000000000000000000000000000000000000000 |
| cur tree : 0000000000000000000000000000000000000000 |
| commit clock: 0 |
| last pack :</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>------------------- |
| END OF CRASH REPORT</pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_tips_and_tricks">TIPS AND TRICKS</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The following tips and tricks have been collected from various |
| users of fast-import, and are offered here as suggestions.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_use_one_mark_per_commit">Use One Mark Per Commit</h3> |
| <div class="paragraph"> |
| <p>When doing a repository conversion, use a unique mark per commit |
| (<code>mark</code> <code>:</code><em><n></em>) and supply the --export-marks option on the command |
| line. fast-import will dump a file which lists every mark and the Git |
| object SHA-1 that corresponds to it. If the frontend can tie |
| the marks back to the source repository, it is easy to verify the |
| accuracy and completeness of the import by comparing each Git |
| commit to the corresponding source revision.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Coming from a system such as Perforce or Subversion, this should be |
| quite simple, as the fast-import mark can also be the Perforce changeset |
| number or the Subversion revision number.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_freely_skip_around_branches">Freely Skip Around Branches</h3> |
| <div class="paragraph"> |
| <p>Don’t bother trying to optimize the frontend to stick to one branch |
| at a time during an import. Although doing so might be slightly |
| faster for fast-import, it tends to increase the complexity of the frontend |
| code considerably.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The branch LRU builtin to fast-import tends to behave very well, and the |
| cost of activating an inactive branch is so low that bouncing around |
| between branches has virtually no impact on import performance.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_handling_renames">Handling Renames</h3> |
| <div class="paragraph"> |
| <p>When importing a renamed file or directory, simply delete the old |
| name(s) and modify the new name(s) during the corresponding commit. |
| Git performs rename detection after-the-fact, rather than explicitly |
| during a commit.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_use_tag_fixup_branches">Use Tag Fixup Branches</h3> |
| <div class="paragraph"> |
| <p>Some other SCM systems let the user create a tag from multiple |
| files which are not from the same commit/changeset. Or to create |
| tags which are a subset of the files available in the repository.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Importing these tags as-is in Git is impossible without making at |
| least one commit which “fixes up” the files to match the content |
| of the tag. Use fast-import’s <code>reset</code> command to reset a dummy branch |
| outside of your normal branch space to the base commit for the tag, |
| then commit one or more file fixup commits, and finally tag the |
| dummy branch.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For example since all normal branches are stored under <code>refs/heads/</code> |
| name the tag fixup branch <code>TAG_FIXUP</code>. This way it is impossible for |
| the fixup branch used by the importer to have namespace conflicts |
| with real branches imported from the source (the name <code>TAG_FIXUP</code> |
| is not <code>refs/heads/TAG_FIXUP</code>).</p> |
| </div> |
| <div class="paragraph"> |
| <p>When committing fixups, consider using <code>merge</code> to connect the |
| commit(s) which are supplying file revisions to the fixup branch. |
| Doing so will allow tools such as <em>git blame</em> to track |
| through the real commit history and properly annotate the source |
| files.</p> |
| </div> |
| <div class="paragraph"> |
| <p>After fast-import terminates the frontend will need to do <code>rm</code> <code>.git/TAG_FIXUP</code> |
| to remove the dummy branch.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_import_now_repack_later">Import Now, Repack Later</h3> |
| <div class="paragraph"> |
| <p>As soon as fast-import completes the Git repository is completely valid |
| and ready for use. Typically this takes only a very short time, |
| even for considerably large projects (100,000+ commits).</p> |
| </div> |
| <div class="paragraph"> |
| <p>However repacking the repository is necessary to improve data |
| locality and access performance. It can also take hours on extremely |
| large projects (especially if -f and a large --window parameter is |
| used). Since repacking is safe to run alongside readers and writers, |
| run the repack in the background and let it finish when it finishes. |
| There is no reason to wait to explore your new Git project!</p> |
| </div> |
| <div class="paragraph"> |
| <p>If you choose to wait for the repack, don’t try to run benchmarks |
| or performance tests until repacking is completed. fast-import outputs |
| suboptimal packfiles that are simply never seen in real use |
| situations.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_repacking_historical_data">Repacking Historical Data</h3> |
| <div class="paragraph"> |
| <p>If you are repacking very old imported data (e.g. older than the |
| last year), consider expending some extra CPU time and supplying |
| --window=50 (or higher) when you run <em>git repack</em>. |
| This will take longer, but will also produce a smaller packfile. |
| You only need to expend the effort once, and everyone using your |
| project will benefit from the smaller repository.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_include_some_progress_messages">Include Some Progress Messages</h3> |
| <div class="paragraph"> |
| <p>Every once in a while have your frontend emit a <code>progress</code> message |
| to fast-import. The contents of the messages are entirely free-form, |
| so one suggestion would be to output the current month and year |
| each time the current commit date moves into the next month. |
| Your users will feel better knowing how much of the data stream |
| has been processed.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_packfile_optimization">PACKFILE OPTIMIZATION</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>When packing a blob fast-import always attempts to deltify against the last |
| blob written. Unless specifically arranged for by the frontend, |
| this will probably not be a prior version of the same file, so the |
| generated delta will not be the smallest possible. The resulting |
| packfile will be compressed, but will not be optimal.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Frontends which have efficient access to all revisions of a |
| single file (for example reading an RCS/CVS ,v file) can choose |
| to supply all revisions of that file as a sequence of consecutive |
| <code>blob</code> commands. This allows fast-import to deltify the different file |
| revisions against each other, saving space in the final packfile. |
| Marks can be used to later identify individual file revisions during |
| a sequence of <code>commit</code> commands.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The packfile(s) created by fast-import do not encourage good disk access |
| patterns. This is caused by fast-import writing the data in the order |
| it is received on standard input, while Git typically organizes |
| data within packfiles to make the most recent (current tip) data |
| appear before historical data. Git also clusters commits together, |
| speeding up revision traversal through better cache locality.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For this reason it is strongly recommended that users repack the |
| repository with <code>git</code> <code>repack</code> <code>-a</code> <code>-d</code> after fast-import completes, allowing |
| Git to reorganize the packfiles for faster data access. If blob |
| deltas are suboptimal (see above) then also adding the <code>-f</code> option |
| to force recomputation of all deltas can significantly reduce the |
| final packfile size (30-50% smaller can be quite typical).</p> |
| </div> |
| <div class="paragraph"> |
| <p>Instead of running <code>git</code> <code>repack</code> you can also run <code>git</code> <code>gc</code> |
| <code>--aggressive</code>, which will also optimize other things after an import |
| (e.g. pack loose refs). As noted in the "AGGRESSIVE" section in |
| <a href="git-gc.html">git-gc(1)</a> the <code>--aggressive</code> option will find new deltas with |
| the <code>-f</code> option to <a href="git-repack.html">git-repack(1)</a>. For the reasons elaborated |
| on above using <code>--aggressive</code> after a fast-import is one of the few |
| cases where it’s known to be worthwhile.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_memory_utilization">MEMORY UTILIZATION</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>There are a number of factors which affect how much memory fast-import |
| requires to perform an import. Like critical sections of core |
| Git, fast-import uses its own memory allocators to amortize any overheads |
| associated with malloc. In practice fast-import tends to amortize any |
| malloc overheads to 0, due to its use of large block allocations.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_per_object">per object</h3> |
| <div class="paragraph"> |
| <p>fast-import maintains an in-memory structure for every object written in |
| this execution. On a 32 bit system the structure is 32 bytes, |
| on a 64 bit system the structure is 40 bytes (due to the larger |
| pointer sizes). Objects in the table are not deallocated until |
| fast-import terminates. Importing 2 million objects on a 32 bit system |
| will require approximately 64 MiB of memory.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The object table is actually a hashtable keyed on the object name |
| (the unique SHA-1). This storage configuration allows fast-import to reuse |
| an existing or already written object and avoid writing duplicates |
| to the output packfile. Duplicate blobs are surprisingly common |
| in an import, typically due to branch merges in the source.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_per_mark">per mark</h3> |
| <div class="paragraph"> |
| <p>Marks are stored in a sparse array, using 1 pointer (4 bytes or 8 |
| bytes, depending on pointer size) per mark. Although the array |
| is sparse, frontends are still strongly encouraged to use marks |
| between 1 and n, where n is the total number of marks required for |
| this import.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_per_branch">per branch</h3> |
| <div class="paragraph"> |
| <p>Branches are classified as active and inactive. The memory usage |
| of the two classes is significantly different.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Inactive branches are stored in a structure which uses 96 or 120 |
| bytes (32 bit or 64 bit systems, respectively), plus the length of |
| the branch name (typically under 200 bytes), per branch. fast-import will |
| easily handle as many as 10,000 inactive branches in under 2 MiB |
| of memory.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Active branches have the same overhead as inactive branches, but |
| also contain copies of every tree that has been recently modified on |
| that branch. If subtree <code>include</code> has not been modified since the |
| branch became active, its contents will not be loaded into memory, |
| but if subtree <code>src</code> has been modified by a commit since the branch |
| became active, then its contents will be loaded in memory.</p> |
| </div> |
| <div class="paragraph"> |
| <p>As active branches store metadata about the files contained on that |
| branch, their in-memory storage size can grow to a considerable size |
| (see below).</p> |
| </div> |
| <div class="paragraph"> |
| <p>fast-import automatically moves active branches to inactive status based on |
| a simple least-recently-used algorithm. The LRU chain is updated on |
| each <code>commit</code> command. The maximum number of active branches can be |
| increased or decreased on the command line with --active-branches=.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_per_active_tree">per active tree</h3> |
| <div class="paragraph"> |
| <p>Trees (aka directories) use just 12 bytes of memory on top of the |
| memory required for their entries (see “per active file” below). |
| The cost of a tree is virtually 0, as its overhead amortizes out |
| over the individual file entries.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_per_active_file_entry">per active file entry</h3> |
| <div class="paragraph"> |
| <p>Files (and pointers to subtrees) within active trees require 52 or 64 |
| bytes (32/64 bit platforms) per entry. To conserve space, file and |
| tree names are pooled in a common string table, allowing the filename |
| “Makefile” to use just 16 bytes (after including the string header |
| overhead) no matter how many times it occurs within the project.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The active branch LRU, when coupled with the filename string pool |
| and lazy loading of subtrees, allows fast-import to efficiently import |
| projects with 2,000+ branches and 45,114+ files in a very limited |
| memory footprint (less than 2.7 MiB per active branch).</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_signals">SIGNALS</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Sending <strong>SIGUSR1</strong> to the <em>git fast-import</em> process ends the current |
| packfile early, simulating a <code>checkpoint</code> command. The impatient |
| operator can use this facility to peek at the objects and refs from an |
| import in progress, at the cost of some added running time and worse |
| compression.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_configuration">CONFIGURATION</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Everything below this line in this section is selectively included |
| from the <a href="git-config.html">git-config(1)</a> documentation. The content is the same |
| as what’s found there:</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">fastimport.unpackLimit</dt> |
| <dd> |
| <p>If the number of objects imported by <a href="git-fast-import.html">git-fast-import(1)</a> |
| is below this limit, then the objects will be unpacked into |
| loose object files. However, if the number of imported objects |
| equals or exceeds this limit, then the pack will be stored as a |
| pack. Storing the pack from a fast-import can make the import |
| operation complete faster, especially on slow filesystems. If |
| not set, the value of <code>transfer.unpackLimit</code> is used instead.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_see_also">SEE ALSO</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p><a href="git-fast-export.html">git-fast-export(1)</a></p> |
| </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-07-24 21:55:32 -0700 |
| </div> |
| </div> |
| </body> |
| </html> |
