git-filter-branch.html

   1 <!DOCTYPE html>
   2 <html xmlns="http://www.w3.org/1999/xhtml" lang="en">
   3 <head>
   4 <meta charset="UTF-8"/>
   5 <meta http-equiv="X-UA-Compatible" content="IE=edge"/>
   6 <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
   7 <meta name="generator" content="Asciidoctor 2.0.20"/>
   8 <title>git-filter-branch(1)</title>
   9 <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"/>
  10 <style>
  11 /*! Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */
  12 /* Uncomment the following line when using as a custom stylesheet */
  13 /* @import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"; */
  14 html{font-family:sans-serif;-webkit-text-size-adjust:100%}
  15 a{background:none}
  16 a:focus{outline:thin dotted}
  17 a:active,a:hover{outline:0}
  18 h1{font-size:2em;margin:.67em 0}
  19 b,strong{font-weight:bold}
  20 abbr{font-size:.9em}
  21 abbr[title]{cursor:help;border-bottom:1px dotted #dddddf;text-decoration:none}
  22 dfn{font-style:italic}
  23 hr{height:0}
  24 mark{background:#ff0;color:#000}
  25 code,kbd,pre,samp{font-family:monospace;font-size:1em}
  26 pre{white-space:pre-wrap}
  27 q{quotes:"\201C" "\201D" "\2018" "\2019"}
  28 small{font-size:80%}
  29 sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
  30 sup{top:-.5em}
  31 sub{bottom:-.25em}
  32 img{border:0}
  33 svg:not(:root){overflow:hidden}
  34 figure{margin:0}
  35 audio,video{display:inline-block}
  36 audio:not([controls]){display:none;height:0}
  37 fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
  38 legend{border:0;padding:0}
  39 button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
  40 button,input{line-height:normal}
  41 button,select{text-transform:none}
  42 button,html input[type=button],input[type=reset],input[type=submit]{-webkit-appearance:button;cursor:pointer}
  43 button[disabled],html input[disabled]{cursor:default}
  44 input[type=checkbox],input[type=radio]{padding:0}
  45 button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
  46 textarea{overflow:auto;vertical-align:top}
  47 table{border-collapse:collapse;border-spacing:0}
  48 *,::before,::after{box-sizing:border-box}
  49 html,body{font-size:100%}
  50 body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;line-height:1;position:relative;cursor:auto;-moz-tab-size:4;-o-tab-size:4;tab-size:4;word-wrap:anywhere;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}
  51 a:hover{cursor:pointer}
  52 img,object,embed{max-width:100%;height:auto}
  53 object,embed{height:100%}
  54 img{-ms-interpolation-mode:bicubic}
  55 .left{float:left!important}
  56 .right{float:right!important}
  57 .text-left{text-align:left!important}
  58 .text-right{text-align:right!important}
  59 .text-center{text-align:center!important}
  60 .text-justify{text-align:justify!important}
  61 .hide{display:none}
  62 img,object,svg{display:inline-block;vertical-align:middle}
  63 textarea{height:auto;min-height:50px}
  64 select{width:100%}
  65 .subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}
  66 div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0}
  67 a{color:#2156a5;text-decoration:underline;line-height:inherit}
  68 a:hover,a:focus{color:#1d4b8f}
  69 a img{border:0}
  70 p{line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
  71 p aside{font-size:.875em;line-height:1.35;font-style:italic}
  72 h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}
  73 h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}
  74 h1{font-size:2.125em}
  75 h2{font-size:1.6875em}
  76 h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
  77 h4,h5{font-size:1.125em}
  78 h6{font-size:1em}
  79 hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em}
  80 em,i{font-style:italic;line-height:inherit}
  81 strong,b{font-weight:bold;line-height:inherit}
  82 small{font-size:60%;line-height:inherit}
  83 code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
  84 ul,ol,dl{line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
  85 ul,ol{margin-left:1.5em}
  86 ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0}
  87 ul.circle{list-style-type:circle}
  88 ul.disc{list-style-type:disc}
  89 ul.square{list-style-type:square}
  90 ul.circle ul:not([class]),ul.disc ul:not([class]),ul.square ul:not([class]){list-style:inherit}
  91 ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
  92 dl dt{margin-bottom:.3125em;font-weight:bold}
  93 dl dd{margin-bottom:1.25em}
  94 blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
  95 blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
  96 @media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
  97 h1{font-size:2.75em}
  98 h2{font-size:2.3125em}
  99 h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
 100 h4{font-size:1.4375em}}
 101 table{background:#fff;margin-bottom:1.25em;border:1px solid #dedede;word-wrap:normal}
 102 table thead,table tfoot{background:#f7f8f7}
 103 table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}
 104 table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
 105 table tr.even,table tr.alt{background:#f8f8f7}
 106 table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{line-height:1.6}
 107 h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
 108 h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
 109 .center{margin-left:auto;margin-right:auto}
 110 .stretch{width:100%}
 111 .clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table}
 112 .clearfix::after,.float-group::after{clear:both}
 113 :not(pre).nobreak{word-wrap:normal}
 114 :not(pre).nowrap{white-space:nowrap}
 115 :not(pre).pre-wrap{white-space:pre-wrap}
 116 :not(pre):not([class^=L])>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background:#f7f7f8;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed}
 117 pre{color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;line-height:1.45;text-rendering:optimizeSpeed}
 118 pre code,pre pre{color:inherit;font-size:inherit;line-height:inherit}
 119 pre>code{display:block}
 120 pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal}
 121 em em{font-style:normal}
 122 strong strong{font-weight:400}
 123 .keyseq{color:rgba(51,51,51,.8)}
 124 kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background:#f7f7f7;border:1px solid #ccc;border-radius:3px;box-shadow:0 1px 0 rgba(0,0,0,.2),inset 0 0 0 .1em #fff;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}
 125 .keyseq kbd:first-child{margin-left:0}
 126 .keyseq kbd:last-child{margin-right:0}
 127 .menuseq,.menuref{color:#000}
 128 .menuseq b:not(.caret),.menuref{font-weight:inherit}
 129 .menuseq{word-spacing:-.02em}
 130 .menuseq b.caret{font-size:1.25em;line-height:.8}
 131 .menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
 132 b.button::before,b.button::after{position:relative;top:-1px;font-weight:400}
 133 b.button::before{content:"[";padding:0 3px 0 2px}
 134 b.button::after{content:"]";padding:0 2px 0 3px}
 135 p a>code:hover{color:rgba(0,0,0,.9)}
 136 #header,#content,#footnotes,#footer{width:100%;margin:0 auto;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
 137 #header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table}
 138 #header::after,#content::after,#footnotes::after,#footer::after{clear:both}
 139 #content{margin-top:1.25em}
 140 #content::before{content:none}
 141 #header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
 142 #header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}
 143 #header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
 144 #header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:flex;flex-flow:row wrap}
 145 #header .details span:first-child{margin-left:-.125em}
 146 #header .details span.email a{color:rgba(0,0,0,.85)}
 147 #header .details br{display:none}
 148 #header .details br+span::before{content:"\00a0\2013\00a0"}
 149 #header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
 150 #header .details br+span#revremark::before{content:"\00a0|\00a0"}
 151 #header #revnumber{text-transform:capitalize}
 152 #header #revnumber::after{content:"\00a0"}
 153 #content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}
 154 #toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em}
 155 #toc>ul{margin-left:.125em}
 156 #toc ul.sectlevel0>li>a{font-style:italic}
 157 #toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
 158 #toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
 159 #toc li{line-height:1.3334;margin-top:.3334em}
 160 #toc a{text-decoration:none}
 161 #toc a:active{text-decoration:underline}
 162 #toctitle{color:#7a2518;font-size:1.2em}
 163 @media screen and (min-width:768px){#toctitle{font-size:1.375em}
 164 body.toc2{padding-left:15em;padding-right:0}
 165 #toc.toc2{margin-top:0!important;background:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
 166 #toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
 167 #toc.toc2>ul{font-size:.9em;margin-bottom:0}
 168 #toc.toc2 ul ul{margin-left:0;padding-left:1em}
 169 #toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
 170 body.toc2.toc-right{padding-left:0;padding-right:15em}
 171 body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}
 172 @media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
 173 #toc.toc2{width:20em}
 174 #toc.toc2 #toctitle{font-size:1.375em}
 175 #toc.toc2>ul{font-size:.95em}
 176 #toc.toc2 ul ul{padding-left:1.25em}
 177 body.toc2.toc-right{padding-left:0;padding-right:20em}}
 178 #content #toc{border:1px solid #e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;border-radius:4px}
 179 #content #toc>:first-child{margin-top:0}
 180 #content #toc>:last-child{margin-bottom:0}
 181 #footer{max-width:none;background:rgba(0,0,0,.8);padding:1.25em}
 182 #footer-text{color:hsla(0,0%,100%,.8);line-height:1.44}
 183 #content{margin-bottom:.625em}
 184 .sect1{padding-bottom:.625em}
 185 @media screen and (min-width:768px){#content{margin-bottom:1.25em}
 186 .sect1{padding-bottom:1.25em}}
 187 .sect1:last-child{padding-bottom:0}
 188 .sect1+.sect1{border-top:1px solid #e7e7e9}
 189 #content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}
 190 #content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}
 191 #content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}
 192 #content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}
 193 #content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}
 194 details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
 195 details{margin-left:1.25rem}
 196 details>summary{cursor:pointer;display:block;position:relative;line-height:1.6;margin-bottom:.625rem;outline:none;-webkit-tap-highlight-color:transparent}
 197 details>summary::-webkit-details-marker{display:none}
 198 details>summary::before{content:"";border:solid transparent;border-left:solid;border-width:.3em 0 .3em .5em;position:absolute;top:.5em;left:-1.25rem;transform:translateX(15%)}
 199 details[open]>summary::before{border:solid transparent;border-top:solid;border-width:.5em .3em 0;transform:translateY(15%)}
 200 details>summary::after{content:"";width:1.25rem;height:1em;position:absolute;top:.3em;left:-1.25rem}
 201 .admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}
 202 table.tableblock.fit-content>caption.title{white-space:nowrap;width:0}
 203 .paragraph.lead>p,#preamble>.sectionbody>[class=paragraph]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)}
 204 .admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
 205 .admonitionblock>table td.icon{text-align:center;width:80px}
 206 .admonitionblock>table td.icon img{max-width:none}
 207 .admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
 208 .admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6);word-wrap:anywhere}
 209 .admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
 210 .exampleblock>.content{border:1px solid #e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;border-radius:4px}
 211 .sidebarblock{border:1px solid #dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;border-radius:4px}
 212 .sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
 213 .exampleblock>.content>:first-child,.sidebarblock>.content>:first-child{margin-top:0}
 214 .exampleblock>.content>:last-child,.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
 215 .literalblock pre,.listingblock>.content>pre{border-radius:4px;overflow-x:auto;padding:1em;font-size:.8125em}
 216 @media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}}
 217 @media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}}
 218 .literalblock pre,.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class=highlight],.listingblock>.content>pre[class^="highlight "]{background:#f7f7f8}
 219 .literalblock.output pre{color:#f7f7f8;background:rgba(0,0,0,.9)}
 220 .listingblock>.content{position:relative}
 221 .listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:inherit;opacity:.5}
 222 .listingblock:hover code[data-lang]::before{display:block}
 223 .listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:inherit;opacity:.5}
 224 .listingblock.terminal pre .command:not([data-prompt])::before{content:"$"}
 225 .listingblock pre.highlightjs{padding:0}
 226 .listingblock pre.highlightjs>code{padding:1em;border-radius:4px}
 227 .listingblock pre.prettyprint{border-width:0}
 228 .prettyprint{background:#f7f7f8}
 229 pre.prettyprint .linenums{line-height:1.45;margin-left:2em}
 230 pre.prettyprint li{background:none;list-style-type:inherit;padding-left:0}
 231 pre.prettyprint li code[data-lang]::before{opacity:1}
 232 pre.prettyprint li:not(:first-child) code[data-lang]::before{display:none}
 233 table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none}
 234 table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal}
 235 table.linenotable td.code{padding-left:.75em}
 236 table.linenotable td.linenos,pre.pygments .linenos{border-right:1px solid;opacity:.35;padding-right:.5em;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}
 237 pre.pygments span.linenos{display:inline-block;margin-right:.75em}
 238 .quoteblock{margin:0 1em 1.25em 1.5em;display:table}
 239 .quoteblock:not(.excerpt)>.title{margin-left:-1.5em;margin-bottom:.75em}
 240 .quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}
 241 .quoteblock blockquote{margin:0;padding:0;border:0}
 242 .quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}
 243 .quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
 244 .quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right}
 245 .verseblock{margin:0 1em 1.25em}
 246 .verseblock pre{font-family:"Open Sans","DejaVu Sans",sans-serif;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}
 247 .verseblock pre strong{font-weight:400}
 248 .verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
 249 .quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
 250 .quoteblock .attribution br,.verseblock .attribution br{display:none}
 251 .quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}
 252 .quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none}
 253 .quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0}
 254 .quoteblock.abstract{margin:0 1em 1.25em;display:block}
 255 .quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center}
 256 .quoteblock.excerpt>blockquote,.quoteblock .quoteblock{padding:0 0 .25em 1em;border-left:.25em solid #dddddf}
 257 .quoteblock.excerpt,.quoteblock .quoteblock{margin-left:0}
 258 .quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem}
 259 .quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;font-size:.85rem;text-align:left;margin-right:0}
 260 p.tableblock:last-child{margin-bottom:0}
 261 td.tableblock>.content{margin-bottom:1.25em;word-wrap:anywhere}
 262 td.tableblock>.content>:last-child{margin-bottom:-1.25em}
 263 table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
 264 table.grid-all>*>tr>*{border-width:1px}
 265 table.grid-cols>*>tr>*{border-width:0 1px}
 266 table.grid-rows>*>tr>*{border-width:1px 0}
 267 table.frame-all{border-width:1px}
 268 table.frame-ends{border-width:1px 0}
 269 table.frame-sides{border-width:0 1px}
 270 table.frame-none>colgroup+*>:first-child>*,table.frame-sides>colgroup+*>:first-child>*{border-top-width:0}
 271 table.frame-none>:last-child>:last-child>*,table.frame-sides>:last-child>:last-child>*{border-bottom-width:0}
 272 table.frame-none>*>tr>:first-child,table.frame-ends>*>tr>:first-child{border-left-width:0}
 273 table.frame-none>*>tr>:last-child,table.frame-ends>*>tr>:last-child{border-right-width:0}
 274 table.stripes-all>*>tr,table.stripes-odd>*>tr:nth-of-type(odd),table.stripes-even>*>tr:nth-of-type(even),table.stripes-hover>*>tr:hover{background:#f8f8f7}
 275 th.halign-left,td.halign-left{text-align:left}
 276 th.halign-right,td.halign-right{text-align:right}
 277 th.halign-center,td.halign-center{text-align:center}
 278 th.valign-top,td.valign-top{vertical-align:top}
 279 th.valign-bottom,td.valign-bottom{vertical-align:bottom}
 280 th.valign-middle,td.valign-middle{vertical-align:middle}
 281 table thead th,table tfoot th{font-weight:bold}
 282 tbody tr th{background:#f7f8f7}
 283 tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
 284 p.tableblock>code:only-child{background:none;padding:0}
 285 p.tableblock{font-size:1em}
 286 ol{margin-left:1.75em}
 287 ul li ol{margin-left:1.5em}
 288 dl dd{margin-left:1.125em}
 289 dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
 290 li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
 291 ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}
 292 ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}
 293 ul.unstyled,ol.unstyled{margin-left:0}
 294 li>p:empty:only-child::before{content:"";display:inline-block}
 295 ul.checklist>li>p:first-child{margin-left:-1em}
 296 ul.checklist>li>p:first-child>.fa-square-o:first-child,ul.checklist>li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em}
 297 ul.checklist>li>p:first-child>input[type=checkbox]:first-child{margin-right:.25em}
 298 ul.inline{display:flex;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em}
 299 ul.inline>li{margin-left:1.25em}
 300 .unstyled dl dt{font-weight:400;font-style:normal}
 301 ol.arabic{list-style-type:decimal}
 302 ol.decimal{list-style-type:decimal-leading-zero}
 303 ol.loweralpha{list-style-type:lower-alpha}
 304 ol.upperalpha{list-style-type:upper-alpha}
 305 ol.lowerroman{list-style-type:lower-roman}
 306 ol.upperroman{list-style-type:upper-roman}
 307 ol.lowergreek{list-style-type:lower-greek}
 308 .hdlist>table,.colist>table{border:0;background:none}
 309 .hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
 310 td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
 311 td.hdlist1{font-weight:bold;padding-bottom:1.25em}
 312 td.hdlist2{word-wrap:anywhere}
 313 .literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
 314 .colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top}
 315 .colist td:not([class]):first-child img{max-width:none}
 316 .colist td:not([class]):last-child{padding:.25em 0}
 317 .thumb,.th{line-height:0;display:inline-block;border:4px solid #fff;box-shadow:0 0 0 1px #ddd}
 318 .imageblock.left{margin:.25em .625em 1.25em 0}
 319 .imageblock.right{margin:.25em 0 1.25em .625em}
 320 .imageblock>.title{margin-bottom:0}
 321 .imageblock.thumb,.imageblock.th{border-width:6px}
 322 .imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
 323 .image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
 324 .image.left{margin-right:.625em}
 325 .image.right{margin-left:.625em}
 326 a.image{text-decoration:none;display:inline-block}
 327 a.image object{pointer-events:none}
 328 sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
 329 sup.footnote a,sup.footnoteref a{text-decoration:none}
 330 sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline}
 331 #footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
 332 #footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}
 333 #footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}
 334 #footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em}
 335 #footnotes .footnote:last-of-type{margin-bottom:0}
 336 #content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
 337 div.unbreakable{page-break-inside:avoid}
 338 .big{font-size:larger}
 339 .small{font-size:smaller}
 340 .underline{text-decoration:underline}
 341 .overline{text-decoration:overline}
 342 .line-through{text-decoration:line-through}
 343 .aqua{color:#00bfbf}
 344 .aqua-background{background:#00fafa}
 345 .black{color:#000}
 346 .black-background{background:#000}
 347 .blue{color:#0000bf}
 348 .blue-background{background:#0000fa}
 349 .fuchsia{color:#bf00bf}
 350 .fuchsia-background{background:#fa00fa}
 351 .gray{color:#606060}
 352 .gray-background{background:#7d7d7d}
 353 .green{color:#006000}
 354 .green-background{background:#007d00}
 355 .lime{color:#00bf00}
 356 .lime-background{background:#00fa00}
 357 .maroon{color:#600000}
 358 .maroon-background{background:#7d0000}
 359 .navy{color:#000060}
 360 .navy-background{background:#00007d}
 361 .olive{color:#606000}
 362 .olive-background{background:#7d7d00}
 363 .purple{color:#600060}
 364 .purple-background{background:#7d007d}
 365 .red{color:#bf0000}
 366 .red-background{background:#fa0000}
 367 .silver{color:#909090}
 368 .silver-background{background:#bcbcbc}
 369 .teal{color:#006060}
 370 .teal-background{background:#007d7d}
 371 .white{color:#bfbfbf}
 372 .white-background{background:#fafafa}
 373 .yellow{color:#bfbf00}
 374 .yellow-background{background:#fafa00}
 375 span.icon>.fa{cursor:default}
 376 a span.icon>.fa{cursor:inherit}
 377 .admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
 378 .admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c}
 379 .admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
 380 .admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900}
 381 .admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400}
 382 .admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000}
 383 .conum[data-value]{display:inline-block;color:#fff!important;background:rgba(0,0,0,.8);border-radius:50%;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
 384 .conum[data-value] *{color:#fff!important}
 385 .conum[data-value]+b{display:none}
 386 .conum[data-value]::after{content:attr(data-value)}
 387 pre .conum[data-value]{position:relative;top:-.125em}
 388 b.conum *{color:inherit!important}
 389 .conum:not([data-value]):empty{display:none}
 390 dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}
 391 h1,h2,p,td.content,span.alt,summary{letter-spacing:-.01em}
 392 p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}
 393 p,blockquote,dt,td.content,td.hdlist1,span.alt,summary{font-size:1.0625rem}
 394 p{margin-bottom:1.25rem}
 395 .sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
 396 .exampleblock>.content{background:#fffef7;border-color:#e0e0dc;box-shadow:0 1px 4px #e0e0dc}
 397 .print-only{display:none!important}
 398 @page{margin:1.25cm .75cm}
 399 @media print{*{box-shadow:none!important;text-shadow:none!important}
 400 html{font-size:80%}
 401 a{color:inherit!important;text-decoration:underline!important}
 402 a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
 403 a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
 404 abbr[title]{border-bottom:1px dotted}
 405 abbr[title]::after{content:" (" attr(title) ")"}
 406 pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
 407 thead{display:table-header-group}
 408 svg{max-width:100%}
 409 p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
 410 h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
 411 #header,#content,#footnotes,#footer{max-width:none}
 412 #toc,.sidebarblock,.exampleblock>.content{background:none!important}
 413 #toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important}
 414 body.book #header{text-align:center}
 415 body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em}
 416 body.book #header .details{border:0!important;display:block;padding:0!important}
 417 body.book #header .details span:first-child{margin-left:0!important}
 418 body.book #header .details br{display:block}
 419 body.book #header .details br+span::before{content:none!important}
 420 body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
 421 body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
 422 .listingblock code[data-lang]::before{display:block}
 423 #footer{padding:0 .9375em}
 424 .hide-on-print{display:none!important}
 425 .print-only{display:block!important}
 426 .hide-for-print{display:none!important}
 427 .show-for-print{display:inherit!important}}
 428 @media amzn-kf8,print{#header>h1:first-child{margin-top:1.25rem}
 429 .sect1{padding:0!important}
 430 .sect1+.sect1{border:0}
 431 #footer{background:none}
 432 #footer-text{color:rgba(0,0,0,.6);font-size:.9em}}
 433 @media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}}
 434 </style>
 435 <style>
 436 pre>code {
 437    display: inline;
 438 }
 439 </style>
 440 </head>
 441 <body class="manpage">
 442 <div id="header">
 443 <h1>git-filter-branch(1) Manual Page</h1>
 444 <h2 id="_name">NAME</h2>
 445 <div class="sectionbody">
 446 <p>git-filter-branch - Rewrite branches</p>
 447 </div>
 448 </div>
 449 <div id="content">
 450 <div class="sect1">
 451 <h2 id="_synopsis">SYNOPSIS</h2>
 452 <div class="sectionbody">
 453 <div class="verseblock">
 454 <pre class="content"><em>git filter-branch</em> [--setup &lt;command&gt;] [--subdirectory-filter &lt;directory&gt;]
 455         [--env-filter &lt;command&gt;] [--tree-filter &lt;command&gt;]
 456         [--index-filter &lt;command&gt;] [--parent-filter &lt;command&gt;]
 457         [--msg-filter &lt;command&gt;] [--commit-filter &lt;command&gt;]
 458         [--tag-name-filter &lt;command&gt;] [--prune-empty]
 459         [--original &lt;namespace&gt;] [-d &lt;directory&gt;] [-f | --force]
 460         [--state-branch &lt;branch&gt;] [--] [&lt;rev-list-options&gt;&#8230;&#8203;]</pre>
 461 </div>
 462 </div>
 463 </div>
 464 <div class="sect1">
 465 <h2 id="_warning">WARNING</h2>
 466 <div class="sectionbody">
 467 <div class="paragraph">
 468 <p><em>git filter-branch</em> has a plethora of pitfalls that can produce non-obvious
 469 manglings of the intended history rewrite (and can leave you with little
 470 time to investigate such problems since it has such abysmal performance).
 471 These safety and performance issues cannot be backward compatibly fixed and
 472 as such, its use is not recommended.  Please use an alternative history
 473 filtering tool such as <a href="https://github.com/newren/git-filter-repo/">git
 474 filter-repo</a>.  If you still need to use <em>git filter-branch</em>, please
 475 carefully read <a href="#SAFETY">SAFETY</a> (and <a href="#PERFORMANCE">PERFORMANCE</a>) to learn about the land
 476 mines of filter-branch, and then vigilantly avoid as many of the hazards
 477 listed there as reasonably possible.</p>
 478 </div>
 479 </div>
 480 </div>
 481 <div class="sect1">
 482 <h2 id="_description">DESCRIPTION</h2>
 483 <div class="sectionbody">
 484 <div class="paragraph">
 485 <p>Lets you rewrite Git revision history by rewriting the branches mentioned
 486 in the &lt;rev-list-options&gt;, applying custom filters on each revision.
 487 Those filters can modify each tree (e.g. removing a file or running
 488 a perl rewrite on all files) or information about each commit.
 489 Otherwise, all information (including original commit times or merge
 490 information) will be preserved.</p>
 491 </div>
 492 <div class="paragraph">
 493 <p>The command will only rewrite the <em>positive</em> refs mentioned in the
 494 command line (e.g. if you pass <em>a..b</em>, only <em>b</em> will be rewritten).
 495 If you specify no filters, the commits will be recommitted without any
 496 changes, which would normally have no effect.  Nevertheless, this may be
 497 useful in the future for compensating for some Git bugs or such,
 498 therefore such a usage is permitted.</p>
 499 </div>
 500 <div class="paragraph">
 501 <p><strong>NOTE</strong>: This command honors .<code>git/info/grafts</code> file and refs in
 502 the <code>refs/replace/</code> namespace.
 503 If you have any grafts or replacement refs defined, running this command
 504 will make them permanent.</p>
 505 </div>
 506 <div class="paragraph">
 507 <p><strong>WARNING</strong>! The rewritten history will have different object names for all
 508 the objects and will not converge with the original branch.  You will not
 509 be able to easily push and distribute the rewritten branch on top of the
 510 original branch.  Please do not use this command if you do not know the
 511 full implications, and avoid using it anyway, if a simple single commit
 512 would suffice to fix your problem.  (See the "RECOVERING FROM UPSTREAM
 513 REBASE" section in <a href="git-rebase.html">git-rebase(1)</a> for further information about
 514 rewriting published history.)</p>
 515 </div>
 516 <div class="paragraph">
 517 <p>Always verify that the rewritten version is correct: The original refs,
 518 if different from the rewritten ones, will be stored in the namespace
 519 <em>refs/original/</em>.</p>
 520 </div>
 521 <div class="paragraph">
 522 <p>Note that since this operation is very I/O expensive, it might
 523 be a good idea to redirect the temporary directory off-disk with the
 524 <code>-d</code> option, e.g. on tmpfs.  Reportedly the speedup is very noticeable.</p>
 525 </div>
 526 <div class="sect2">
 527 <h3 id="_filters">Filters</h3>
 528 <div class="paragraph">
 529 <p>The filters are applied in the order as listed below.  The &lt;command&gt;
 530 argument is always evaluated in the shell context using the <em>eval</em> command
 531 (with the notable exception of the commit filter, for technical reasons).
 532 Prior to that, the <code>$GIT_COMMIT</code> environment variable will be set to contain
 533 the id of the commit being rewritten.  Also, GIT_AUTHOR_NAME,
 534 GIT_AUTHOR_EMAIL, GIT_AUTHOR_DATE, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL,
 535 and GIT_COMMITTER_DATE are taken from the current commit and exported to
 536 the environment, in order to affect the author and committer identities of
 537 the replacement commit created by <a href="git-commit-tree.html">git-commit-tree(1)</a> after the
 538 filters have run.</p>
 539 </div>
 540 <div class="paragraph">
 541 <p>If any evaluation of &lt;command&gt; returns a non-zero exit status, the whole
 542 operation will be aborted.</p>
 543 </div>
 544 <div class="paragraph">
 545 <p>A <em>map</em> function is available that takes an "original sha1 id" argument
 546 and outputs a "rewritten sha1 id" if the commit has been already
 547 rewritten, and "original sha1 id" otherwise; the <em>map</em> function can
 548 return several ids on separate lines if your commit filter emitted
 549 multiple commits.</p>
 550 </div>
 551 </div>
 552 </div>
 553 </div>
 554 <div class="sect1">
 555 <h2 id="_options">OPTIONS</h2>
 556 <div class="sectionbody">
 557 <div class="dlist">
 558 <dl>
 559 <dt class="hdlist1">--setup &lt;command&gt;</dt>
 560 <dd>
 561 <p>This is not a real filter executed for each commit but a one
 562 time setup just before the loop. Therefore no commit-specific
 563 variables are defined yet.  Functions or variables defined here
 564 can be used or modified in the following filter steps except
 565 the commit filter, for technical reasons.</p>
 566 </dd>
 567 <dt class="hdlist1">--subdirectory-filter &lt;directory&gt;</dt>
 568 <dd>
 569 <p>Only look at the history which touches the given subdirectory.
 570 The result will contain that directory (and only that) as its
 571 project root. Implies <a href="#Remap_to_ancestor">Remap to ancestor</a>.</p>
 572 </dd>
 573 <dt class="hdlist1">--env-filter &lt;command&gt;</dt>
 574 <dd>
 575 <p>This filter may be used if you only need to modify the environment
 576 in which the commit will be performed.  Specifically, you might
 577 want to rewrite the author/committer name/email/time environment
 578 variables (see <a href="git-commit-tree.html">git-commit-tree(1)</a> for details).</p>
 579 </dd>
 580 <dt class="hdlist1">--tree-filter &lt;command&gt;</dt>
 581 <dd>
 582 <p>This is the filter for rewriting the tree and its contents.
 583 The argument is evaluated in shell with the working
 584 directory set to the root of the checked out tree.  The new tree
 585 is then used as-is (new files are auto-added, disappeared files
 586 are auto-removed - neither .gitignore files nor any other ignore
 587 rules <strong>HAVE ANY EFFECT</strong>!).</p>
 588 </dd>
 589 <dt class="hdlist1">--index-filter &lt;command&gt;</dt>
 590 <dd>
 591 <p>This is the filter for rewriting the index.  It is similar to the
 592 tree filter but does not check out the tree, which makes it much
 593 faster.  Frequently used with <code>git</code> <code>rm</code> <code>--cached</code>
 594 <code>--ignore-unmatch</code> ..., see EXAMPLES below.  For hairy
 595 cases, see <a href="git-update-index.html">git-update-index(1)</a>.</p>
 596 </dd>
 597 <dt class="hdlist1">--parent-filter &lt;command&gt;</dt>
 598 <dd>
 599 <p>This is the filter for rewriting the commit&#8217;s parent list.
 600 It will receive the parent string on stdin and shall output
 601 the new parent string on stdout.  The parent string is in
 602 the format described in <a href="git-commit-tree.html">git-commit-tree(1)</a>: empty for
 603 the initial commit, "-p parent" for a normal commit and
 604 "-p parent1 -p parent2 -p parent3 &#8230;&#8203;" for a merge commit.</p>
 605 </dd>
 606 <dt class="hdlist1">--msg-filter &lt;command&gt;</dt>
 607 <dd>
 608 <p>This is the filter for rewriting the commit messages.
 609 The argument is evaluated in the shell with the original
 610 commit message on standard input; its standard output is
 611 used as the new commit message.</p>
 612 </dd>
 613 <dt class="hdlist1">--commit-filter &lt;command&gt;</dt>
 614 <dd>
 615 <p>This is the filter for performing the commit.
 616 If this filter is specified, it will be called instead of the
 617 <em>git commit-tree</em> command, with arguments of the form
 618 "&lt;TREE_ID&gt; [(-p &lt;PARENT_COMMIT_ID&gt;)&#8230;&#8203;]" and the log message on
 619 stdin.  The commit id is expected on stdout.</p>
 620 <div class="paragraph">
 621 <p>As a special extension, the commit filter may emit multiple
 622 commit ids; in that case, the rewritten children of the original commit will
 623 have all of them as parents.</p>
 624 </div>
 625 <div class="paragraph">
 626 <p>You can use the <em>map</em> convenience function in this filter, and other
 627 convenience functions, too.  For example, calling <em>skip_commit "$@"</em>
 628 will leave out the current commit (but not its changes! If you want
 629 that, use <em>git rebase</em> instead).</p>
 630 </div>
 631 <div class="paragraph">
 632 <p>You can also use the <code>git_commit_non_empty_tree</code> "$@" instead of
 633 <code>git</code> <code>commit-tree</code> "$@" if you don&#8217;t wish to keep commits with a single parent
 634 and that makes no change to the tree.</p>
 635 </div>
 636 </dd>
 637 <dt class="hdlist1">--tag-name-filter &lt;command&gt;</dt>
 638 <dd>
 639 <p>This is the filter for rewriting tag names. When passed,
 640 it will be called for every tag ref that points to a rewritten
 641 object (or to a tag object which points to a rewritten object).
 642 The original tag name is passed via standard input, and the new
 643 tag name is expected on standard output.</p>
 644 <div class="paragraph">
 645 <p>The original tags are not deleted, but can be overwritten;
 646 use "--tag-name-filter cat" to simply update the tags.  In this
 647 case, be very careful and make sure you have the old tags
 648 backed up in case the conversion has run afoul.</p>
 649 </div>
 650 <div class="paragraph">
 651 <p>Nearly proper rewriting of tag objects is supported. If the tag has
 652 a message attached, a new tag object will be created with the same message,
 653 author, and timestamp. If the tag has a signature attached, the
 654 signature will be stripped. It is by definition impossible to preserve
 655 signatures. The reason this is "nearly" proper, is because ideally if
 656 the tag did not change (points to the same object, has the same name, etc.)
 657 it should retain any signature. That is not the case, signatures will always
 658 be removed, buyer beware. There is also no support for changing the
 659 author or timestamp (or the tag message for that matter). Tags which point
 660 to other tags will be rewritten to point to the underlying commit.</p>
 661 </div>
 662 </dd>
 663 <dt class="hdlist1">--prune-empty</dt>
 664 <dd>
 665 <p>Some filters will generate empty commits that leave the tree untouched.
 666 This option instructs git-filter-branch to remove such commits if they
 667 have exactly one or zero non-pruned parents; merge commits will
 668 therefore remain intact.  This option cannot be used together with
 669 <code>--commit-filter</code>, though the same effect can be achieved by using the
 670 provided <code>git_commit_non_empty_tree</code> function in a commit filter.</p>
 671 </dd>
 672 <dt class="hdlist1">--original &lt;namespace&gt;</dt>
 673 <dd>
 674 <p>Use this option to set the namespace where the original commits
 675 will be stored. The default value is <em>refs/original</em>.</p>
 676 </dd>
 677 <dt class="hdlist1">-d &lt;directory&gt;</dt>
 678 <dd>
 679 <p>Use this option to set the path to the temporary directory used for
 680 rewriting.  When applying a tree filter, the command needs to
 681 temporarily check out the tree to some directory, which may consume
 682 considerable space in case of large projects.  By default it
 683 does this in the .<code>git-rewrite/</code> directory but you can override
 684 that choice by this parameter.</p>
 685 </dd>
 686 <dt class="hdlist1">-f</dt>
 687 <dt class="hdlist1">--force</dt>
 688 <dd>
 689 <p><em>git filter-branch</em> refuses to start with an existing temporary
 690 directory or when there are already refs starting with
 691 <em>refs/original/</em>, unless forced.</p>
 692 </dd>
 693 <dt class="hdlist1">--state-branch &lt;branch&gt;</dt>
 694 <dd>
 695 <p>This option will cause the mapping from old to new objects to
 696 be loaded from named branch upon startup and saved as a new
 697 commit to that branch upon exit, enabling incremental of large
 698 trees. If <em>&lt;branch&gt;</em> does not exist it will be created.</p>
 699 </dd>
 700 <dt class="hdlist1">&lt;rev-list options&gt;&#8230;&#8203;</dt>
 701 <dd>
 702 <p>Arguments for <em>git rev-list</em>.  All positive refs included by
 703 these options are rewritten.  You may also specify options
 704 such as <code>--all</code>, but you must use <code>--</code> to separate them from
 705 the <em>git filter-branch</em> options. Implies <a href="#Remap_to_ancestor">Remap to ancestor</a>.</p>
 706 </dd>
 707 </dl>
 708 </div>
 709 <div class="sect2">
 710 <h3 id="Remap_to_ancestor">Remap to ancestor</h3>
 711 <div class="paragraph">
 712 <p>By using <a href="git-rev-list.html">git-rev-list(1)</a> arguments, e.g., path limiters, you can limit the
 713 set of revisions which get rewritten. However, positive refs on the command
 714 line are distinguished: we don&#8217;t let them be excluded by such limiters. For
 715 this purpose, they are instead rewritten to point at the nearest ancestor that
 716 was not excluded.</p>
 717 </div>
 718 </div>
 719 </div>
 720 </div>
 721 <div class="sect1">
 722 <h2 id="_exit_status">EXIT STATUS</h2>
 723 <div class="sectionbody">
 724 <div class="paragraph">
 725 <p>On success, the exit status is <code>0</code>.  If the filter can&#8217;t find any commits to
 726 rewrite, the exit status is <code>2</code>.  On any other error, the exit status may be
 727 any other non-zero value.</p>
 728 </div>
 729 </div>
 730 </div>
 731 <div class="sect1">
 732 <h2 id="_examples">EXAMPLES</h2>
 733 <div class="sectionbody">
 734 <div class="paragraph">
 735 <p>Suppose you want to remove a file (containing confidential information
 736 or copyright violation) from all commits:</p>
 737 </div>
 738 <div class="listingblock">
 739 <div class="content">
 740 <pre>git filter-branch --tree-filter 'rm filename' HEAD</pre>
 741 </div>
 742 </div>
 743 <div class="paragraph">
 744 <p>However, if the file is absent from the tree of some commit,
 745 a simple <code>rm</code> <code>filename</code> will fail for that tree and commit.
 746 Thus you may instead want to use <code>rm</code> <code>-f</code> <code>filename</code> as the script.</p>
 747 </div>
 748 <div class="paragraph">
 749 <p>Using <code>--index-filter</code> with <em>git rm</em> yields a significantly faster
 750 version.  Like with using <code>rm</code> <code>filename</code>, <code>git</code> <code>rm</code> <code>--cached</code> <code>filename</code>
 751 will fail if the file is absent from the tree of a commit.  If you
 752 want to "completely forget" a file, it does not matter when it entered
 753 history, so we also add <code>--ignore-unmatch</code>:</p>
 754 </div>
 755 <div class="listingblock">
 756 <div class="content">
 757 <pre>git filter-branch --index-filter 'git rm --cached --ignore-unmatch filename' HEAD</pre>
 758 </div>
 759 </div>
 760 <div class="paragraph">
 761 <p>Now, you will get the rewritten history saved in HEAD.</p>
 762 </div>
 763 <div class="paragraph">
 764 <p>To rewrite the repository to look as if <code>foodir/</code> had been its project
 765 root, and discard all other history:</p>
 766 </div>
 767 <div class="listingblock">
 768 <div class="content">
 769 <pre>git filter-branch --subdirectory-filter foodir -- --all</pre>
 770 </div>
 771 </div>
 772 <div class="paragraph">
 773 <p>Thus you can, e.g., turn a library subdirectory into a repository of
 774 its own.  Note the <code>--</code> that separates <em>filter-branch</em> options from
 775 revision options, and the <code>--all</code> to rewrite all branches and tags.</p>
 776 </div>
 777 <div class="paragraph">
 778 <p>To set a commit (which typically is at the tip of another
 779 history) to be the parent of the current initial commit, in
 780 order to paste the other history behind the current history:</p>
 781 </div>
 782 <div class="listingblock">
 783 <div class="content">
 784 <pre>git filter-branch --parent-filter 'sed "s/^\$/-p &lt;graft-id&gt;/"' HEAD</pre>
 785 </div>
 786 </div>
 787 <div class="paragraph">
 788 <p>(if the parent string is empty - which happens when we are dealing with
 789 the initial commit - add graftcommit as a parent).  Note that this assumes
 790 history with a single root (that is, no merge without common ancestors
 791 happened).  If this is not the case, use:</p>
 792 </div>
 793 <div class="listingblock">
 794 <div class="content">
 795 <pre>git filter-branch --parent-filter \
 796         'test $GIT_COMMIT = &lt;commit-id&gt; &amp;&amp; echo "-p &lt;graft-id&gt;" || cat' HEAD</pre>
 797 </div>
 798 </div>
 799 <div class="paragraph">
 800 <p>or even simpler:</p>
 801 </div>
 802 <div class="listingblock">
 803 <div class="content">
 804 <pre>git replace --graft $commit-id $graft-id
 805 git filter-branch $graft-id..HEAD</pre>
 806 </div>
 807 </div>
 808 <div class="paragraph">
 809 <p>To remove commits authored by "Darl McBribe" from the history:</p>
 810 </div>
 811 <div class="listingblock">
 812 <div class="content">
 813 <pre>git filter-branch --commit-filter '
 814         if [ "$GIT_AUTHOR_NAME" = "Darl McBribe" ];
 815         then
 816                 skip_commit "$@";
 817         else
 818                 git commit-tree "$@";
 819         fi' HEAD</pre>
 820 </div>
 821 </div>
 822 <div class="paragraph">
 823 <p>The function <em>skip_commit</em> is defined as follows:</p>
 824 </div>
 825 <div class="listingblock">
 826 <div class="content">
 827 <pre>skip_commit()
 828 {
 829         shift;
 830         while [ -n "$1" ];
 831         do
 832                 shift;
 833                 map "$1";
 834                 shift;
 835         done;
 836 }</pre>
 837 </div>
 838 </div>
 839 <div class="paragraph">
 840 <p>The shift magic first throws away the tree id and then the -p
 841 parameters.  Note that this handles merges properly! In case Darl
 842 committed a merge between P1 and P2, it will be propagated properly
 843 and all children of the merge will become merge commits with P1,P2
 844 as their parents instead of the merge commit.</p>
 845 </div>
 846 <div class="paragraph">
 847 <p><strong>NOTE</strong> the changes introduced by the commits, and which are not reverted
 848 by subsequent commits, will still be in the rewritten branch. If you want
 849 to throw out <em>changes</em> together with the commits, you should use the
 850 interactive mode of <em>git rebase</em>.</p>
 851 </div>
 852 <div class="paragraph">
 853 <p>You can rewrite the commit log messages using <code>--msg-filter</code>.  For
 854 example, <em>git svn-id</em> strings in a repository created by <em>git svn</em> can
 855 be removed this way:</p>
 856 </div>
 857 <div class="listingblock">
 858 <div class="content">
 859 <pre>git filter-branch --msg-filter '
 860         sed -e "/^git-svn-id:/d"
 861 '</pre>
 862 </div>
 863 </div>
 864 <div class="paragraph">
 865 <p>If you need to add <em>Acked-by</em> lines to, say, the last 10 commits (none
 866 of which is a merge), use this command:</p>
 867 </div>
 868 <div class="listingblock">
 869 <div class="content">
 870 <pre>git filter-branch --msg-filter '
 871         cat &amp;&amp;
 872         echo "Acked-by: Bugs Bunny &lt;bunny@bugzilla.org&gt;"
 873 ' HEAD~10..HEAD</pre>
 874 </div>
 875 </div>
 876 <div class="paragraph">
 877 <p>The <code>--env-filter</code> option can be used to modify committer and/or author
 878 identity.  For example, if you found out that your commits have the wrong
 879 identity due to a misconfigured user.email, you can make a correction,
 880 before publishing the project, like this:</p>
 881 </div>
 882 <div class="listingblock">
 883 <div class="content">
 884 <pre>git filter-branch --env-filter '
 885         if test "$GIT_AUTHOR_EMAIL" = "root@localhost"
 886         then
 887                 GIT_AUTHOR_EMAIL=john@example.com
 888         fi
 889         if test "$GIT_COMMITTER_EMAIL" = "root@localhost"
 890         then
 891                 GIT_COMMITTER_EMAIL=john@example.com
 892         fi
 893 ' -- --all</pre>
 894 </div>
 895 </div>
 896 <div class="paragraph">
 897 <p>To restrict rewriting to only part of the history, specify a revision
 898 range in addition to the new branch name.  The new branch name will
 899 point to the top-most revision that a <em>git rev-list</em> of this range
 900 will print.</p>
 901 </div>
 902 <div class="paragraph">
 903 <p>Consider this history:</p>
 904 </div>
 905 <div class="listingblock">
 906 <div class="content">
 907 <pre>     D--E--F--G--H
 908     /     /
 909 A--B-----C</pre>
 910 </div>
 911 </div>
 912 <div class="paragraph">
 913 <p>To rewrite only commits D,E,F,G,H, but leave A, B and C alone, use:</p>
 914 </div>
 915 <div class="listingblock">
 916 <div class="content">
 917 <pre>git filter-branch ... C..H</pre>
 918 </div>
 919 </div>
 920 <div class="paragraph">
 921 <p>To rewrite commits E,F,G,H, use one of these:</p>
 922 </div>
 923 <div class="listingblock">
 924 <div class="content">
 925 <pre>git filter-branch ... C..H --not D
 926 git filter-branch ... D..H --not C</pre>
 927 </div>
 928 </div>
 929 <div class="paragraph">
 930 <p>To move the whole tree into a subdirectory, or remove it from there:</p>
 931 </div>
 932 <div class="listingblock">
 933 <div class="content">
 934 <pre>git filter-branch --index-filter \
 935         'git ls-files -s | sed "s-\t\"*-&amp;newsubdir/-" |
 936                 GIT_INDEX_FILE=$GIT_INDEX_FILE.new \
 937                         git update-index --index-info &amp;&amp;
 938          mv "$GIT_INDEX_FILE.new" "$GIT_INDEX_FILE"' HEAD</pre>
 939 </div>
 940 </div>
 941 </div>
 942 </div>
 943 <div class="sect1">
 944 <h2 id="_checklist_for_shrinking_a_repository">CHECKLIST FOR SHRINKING A REPOSITORY</h2>
 945 <div class="sectionbody">
 946 <div class="paragraph">
 947 <p>git-filter-branch can be used to get rid of a subset of files,
 948 usually with some combination of <code>--index-filter</code> and
 949 <code>--subdirectory-filter</code>.  People expect the resulting repository to
 950 be smaller than the original, but you need a few more steps to
 951 actually make it smaller, because Git tries hard not to lose your
 952 objects until you tell it to.  First make sure that:</p>
 953 </div>
 954 <div class="ulist">
 955 <ul>
 956 <li>
 957 <p>You really removed all variants of a filename, if a blob was moved
 958 over its lifetime.  <code>git</code> <code>log</code> <code>--name-only</code> <code>--follow</code> <code>--all</code> <code>--</code> <code>filename</code>
 959 can help you find renames.</p>
 960 </li>
 961 <li>
 962 <p>You really filtered all refs: use <code>--tag-name-filter</code> <code>cat</code> <code>--</code> <code>--all</code>
 963 when calling git-filter-branch.</p>
 964 </li>
 965 </ul>
 966 </div>
 967 <div class="paragraph">
 968 <p>Then there are two ways to get a smaller repository.  A safer way is
 969 to clone, that keeps your original intact.</p>
 970 </div>
 971 <div class="ulist">
 972 <ul>
 973 <li>
 974 <p>Clone it with <code>git</code> <code>clone</code> <code>file:///path/to/repo</code>.  The clone
 975 will not have the removed objects.  See <a href="git-clone.html">git-clone(1)</a>.  (Note
 976 that cloning with a plain path just hardlinks everything!)</p>
 977 </li>
 978 </ul>
 979 </div>
 980 <div class="paragraph">
 981 <p>If you really don&#8217;t want to clone it, for whatever reasons, check the
 982 following points instead (in this order).  This is a very destructive
 983 approach, so <strong>make a backup</strong> or go back to cloning it.  You have been
 984 warned.</p>
 985 </div>
 986 <div class="ulist">
 987 <ul>
 988 <li>
 989 <p>Remove the original refs backed up by git-filter-branch: say <code>git</code>
 990 <code>for-each-ref</code> <code>--format=</code>"%(<code>refname</code>)" <code>refs/original/</code> | <code>xargs</code> <code>-n</code> <code>1</code> <code>git</code>
 991 <code>update-ref</code> <code>-d</code>.</p>
 992 </li>
 993 <li>
 994 <p>Expire all reflogs with <code>git</code> <code>reflog</code> <code>expire</code> <code>--expire=now</code> <code>--all</code>.</p>
 995 </li>
 996 <li>
 997 <p>Garbage collect all unreferenced objects with <code>git</code> <code>gc</code> <code>--prune=now</code>
 998 (or if your git-gc is not new enough to support arguments to
 999 <code>--prune</code>, use <code>git</code> <code>repack</code> <code>-ad</code>; <code>git</code> <code>prune</code> instead).</p>
1000 </li>
1001 </ul>
1002 </div>
1003 </div>
1004 </div>
1005 <div class="sect1">
1006 <h2 id="PERFORMANCE">PERFORMANCE</h2>
1007 <div class="sectionbody">
1008 <div class="paragraph">
1009 <p>The performance of git-filter-branch is glacially slow; its design makes it
1010 impossible for a backward-compatible implementation to ever be fast:</p>
1011 </div>
1012 <div class="ulist">
1013 <ul>
1014 <li>
1015 <p>In editing files, git-filter-branch by design checks out each and
1016 every commit as it existed in the original repo.  If your repo has
1017 <code>10^5</code> files and <code>10^5</code> commits, but each commit only modifies five
1018 files, then git-filter-branch will make you do <code>10^10</code> modifications,
1019 despite only having (at most) <code>5</code>*10^5 unique blobs.</p>
1020 </li>
1021 <li>
1022 <p>If you try and cheat and try to make git-filter-branch only work on
1023 files modified in a commit, then two things happen</p>
1024 <div class="ulist">
1025 <ul>
1026 <li>
1027 <p>you run into problems with deletions whenever the user is simply
1028 trying to rename files (because attempting to delete files that
1029 don&#8217;t exist looks like a no-op; it takes some chicanery to remap
1030 deletes across file renames when the renames happen via arbitrary
1031 user-provided shell)</p>
1032 </li>
1033 <li>
1034 <p>even if you succeed at the map-deletes-for-renames chicanery, you
1035 still technically violate backward compatibility because users
1036 are allowed to filter files in ways that depend upon topology of
1037 commits instead of filtering solely based on file contents or
1038 names (though this has not been observed in the wild).</p>
1039 </li>
1040 </ul>
1041 </div>
1042 </li>
1043 <li>
1044 <p>Even if you don&#8217;t need to edit files but only want to e.g. rename or
1045 remove some and thus can avoid checking out each file (i.e. you can
1046 use --index-filter), you still are passing shell snippets for your
1047 filters.  This means that for every commit, you have to have a
1048 prepared git repo where those filters can be run.  That&#8217;s a
1049 significant setup.</p>
1050 </li>
1051 <li>
1052 <p>Further, several additional files are created or updated per commit
1053 by git-filter-branch.  Some of these are for supporting the
1054 convenience functions provided by git-filter-branch (such as map()),
1055 while others are for keeping track of internal state (but could have
1056 also been accessed by user filters; one of git-filter-branch&#8217;s
1057 regression tests does so).  This essentially amounts to using the
1058 filesystem as an IPC mechanism between git-filter-branch and the
1059 user-provided filters.  Disks tend to be a slow IPC mechanism, and
1060 writing these files also effectively represents a forced
1061 synchronization point between separate processes that we hit with
1062 every commit.</p>
1063 </li>
1064 <li>
1065 <p>The user-provided shell commands will likely involve a pipeline of
1066 commands, resulting in the creation of many processes per commit.
1067 Creating and running another process takes a widely varying amount
1068 of time between operating systems, but on any platform it is very
1069 slow relative to invoking a function.</p>
1070 </li>
1071 <li>
1072 <p>git-filter-branch itself is written in shell, which is kind of slow.
1073 This is the one performance issue that could be backward-compatibly
1074 fixed, but compared to the above problems that are intrinsic to the
1075 design of git-filter-branch, the language of the tool itself is a
1076 relatively minor issue.</p>
1077 <div class="ulist">
1078 <ul>
1079 <li>
1080 <p>Side note: Unfortunately, people tend to fixate on the
1081 written-in-shell aspect and periodically ask if git-filter-branch
1082 could be rewritten in another language to fix the performance
1083 issues.  Not only does that ignore the bigger intrinsic problems
1084 with the design, it&#8217;d help less than you&#8217;d expect: if
1085 git-filter-branch itself were not shell, then the convenience
1086 functions (map(), skip_commit(), etc) and the <code>--setup</code> argument
1087 could no longer be executed once at the beginning of the program
1088 but would instead need to be prepended to every user filter (and
1089 thus re-executed with every commit).</p>
1090 </li>
1091 </ul>
1092 </div>
1093 </li>
1094 </ul>
1095 </div>
1096 <div class="paragraph">
1097 <p>The <a href="https://github.com/newren/git-filter-repo/">git filter-repo</a> tool is
1098 an alternative to git-filter-branch which does not suffer from these
1099 performance problems or the safety problems (mentioned below). For those
1100 with existing tooling which relies upon git-filter-branch, <em>git
1101 filter-repo</em> also provides
1102 <a href="https://github.com/newren/git-filter-repo/blob/master/contrib/filter-repo-demos/filter-lamely">filter-lamely</a>,
1103 a drop-in git-filter-branch replacement (with a few caveats).  While
1104 filter-lamely suffers from all the same safety issues as
1105 git-filter-branch, it at least ameliorates the performance issues a
1106 little.</p>
1107 </div>
1108 </div>
1109 </div>
1110 <div class="sect1">
1111 <h2 id="SAFETY">SAFETY</h2>
1112 <div class="sectionbody">
1113 <div class="paragraph">
1114 <p>git-filter-branch is riddled with gotchas resulting in various ways to
1115 easily corrupt repos or end up with a mess worse than what you started
1116 with:</p>
1117 </div>
1118 <div class="ulist">
1119 <ul>
1120 <li>
1121 <p>Someone can have a set of "working and tested filters" which they
1122 document or provide to a coworker, who then runs them on a different
1123 OS where the same commands are not working/tested (some examples in
1124 the git-filter-branch manpage are also affected by this).
1125 BSD vs. GNU userland differences can really bite.  If lucky, error
1126 messages are spewed.  But just as likely, the commands either don&#8217;t
1127 do the filtering requested, or silently corrupt by making some
1128 unwanted change.  The unwanted change may only affect a few commits,
1129 so it&#8217;s not necessarily obvious either.  (The fact that problems
1130 won&#8217;t necessarily be obvious means they are likely to go unnoticed
1131 until the rewritten history is in use for quite a while, at which
1132 point it&#8217;s really hard to justify another flag-day for another
1133 rewrite.)</p>
1134 </li>
1135 <li>
1136 <p>Filenames with spaces are often mishandled by shell snippets since
1137 they cause problems for shell pipelines.  Not everyone is familiar
1138 with find -print0, xargs -0, git-ls-files -z, etc.  Even people who
1139 are familiar with these may assume such flags are not relevant
1140 because someone else renamed any such files in their repo back
1141 before the person doing the filtering joined the project.  And
1142 often, even those familiar with handling arguments with spaces may
1143 not do so just because they aren&#8217;t in the mindset of thinking about
1144 everything that could possibly go wrong.</p>
1145 </li>
1146 <li>
1147 <p>Non-ascii filenames can be silently removed despite being in a
1148 desired directory.  Keeping only wanted paths is often done using
1149 pipelines like <code>git</code> <code>ls-files</code> | <code>grep</code> <code>-v</code> <code>^WANTED_DIR/</code> | <code>xargs</code> <code>git</code> <code>rm</code>.
1150 ls-files will only quote filenames if needed, so folks may not
1151 notice that one of the files didn&#8217;t match the regex (at least not
1152 until it&#8217;s much too late).  Yes, someone who knows about
1153 core.quotePath can avoid this (unless they have other special
1154 characters like \t, \n, or "), and people who use ls-files -z with
1155 something other than grep can avoid this, but that doesn&#8217;t mean they
1156 will.</p>
1157 </li>
1158 <li>
1159 <p>Similarly, when moving files around, one can find that filenames
1160 with non-ascii or special characters end up in a different
1161 directory, one that includes a double quote character.  (This is
1162 technically the same issue as above with quoting, but perhaps an
1163 interesting different way that it can and has manifested as a
1164 problem.)</p>
1165 </li>
1166 <li>
1167 <p>It&#8217;s far too easy to accidentally mix up old and new history.  It&#8217;s
1168 still possible with any tool, but git-filter-branch almost
1169 invites it.  If lucky, the only downside is users getting frustrated
1170 that they don&#8217;t know how to shrink their repo and remove the old
1171 stuff.  If unlucky, they merge old and new history and end up with
1172 multiple "copies" of each commit, some of which have unwanted or
1173 sensitive files and others which don&#8217;t.  This comes about in
1174 multiple different ways:</p>
1175 <div class="ulist">
1176 <ul>
1177 <li>
1178 <p>the default to only doing a partial history rewrite (<em>--all</em> is not
1179 the default and few examples show it)</p>
1180 </li>
1181 <li>
1182 <p>the fact that there&#8217;s no automatic post-run cleanup</p>
1183 </li>
1184 <li>
1185 <p>the fact that --tag-name-filter (when used to rename tags) doesn&#8217;t
1186 remove the old tags but just adds new ones with the new name</p>
1187 </li>
1188 <li>
1189 <p>the fact that little educational information is provided to inform
1190 users of the ramifications of a rewrite and how to avoid mixing old
1191 and new history.  For example, this man page discusses how users
1192 need to understand that they need to rebase their changes for all
1193 their branches on top of new history (or delete and reclone), but
1194 that&#8217;s only one of multiple concerns to consider.  See the
1195 "DISCUSSION" section of the git filter-repo manual page for more
1196 details.</p>
1197 </li>
1198 </ul>
1199 </div>
1200 </li>
1201 <li>
1202 <p>Annotated tags can be accidentally converted to lightweight tags,
1203 due to either of two issues:</p>
1204 <div class="ulist">
1205 <ul>
1206 <li>
1207 <p>Someone can do a history rewrite, realize they messed up, restore
1208 from the backups in refs/original/, and then redo their
1209 git-filter-branch command.  (The backup in refs/original/ is not a
1210 real backup; it dereferences tags first.)</p>
1211 </li>
1212 <li>
1213 <p>Running git-filter-branch with either --tags or --all in your
1214 &lt;rev-list-options&gt;.  In order to retain annotated tags as
1215 annotated, you must use --tag-name-filter (and must not have
1216 restored from refs/original/ in a previously botched rewrite).</p>
1217 </li>
1218 </ul>
1219 </div>
1220 </li>
1221 <li>
1222 <p>Any commit messages that specify an encoding will become corrupted
1223 by the rewrite; git-filter-branch ignores the encoding, takes the
1224 original bytes, and feeds it to commit-tree without telling it the
1225 proper encoding.  (This happens whether or not --msg-filter is
1226 used.)</p>
1227 </li>
1228 <li>
1229 <p>Commit messages (even if they are all UTF-8) by default become
1230 corrupted due to not being updated&#8201;&#8212;&#8201;any references to other commit
1231 hashes in commit messages will now refer to no-longer-extant
1232 commits.</p>
1233 </li>
1234 <li>
1235 <p>There are no facilities for helping users find what unwanted crud
1236 they should delete, which means they are much more likely to have
1237 incomplete or partial cleanups that sometimes result in confusion
1238 and people wasting time trying to understand.  (For example, folks
1239 tend to just look for big files to delete instead of big directories
1240 or extensions, and once they do so, then sometime later folks using
1241 the new repository who are going through history will notice a build
1242 artifact directory that has some files but not others, or a cache of
1243 dependencies (node_modules or similar) which couldn&#8217;t have ever been
1244 functional since it&#8217;s missing some files.)</p>
1245 </li>
1246 <li>
1247 <p>If --prune-empty isn&#8217;t specified, then the filtering process can
1248 create hoards of confusing empty commits</p>
1249 </li>
1250 <li>
1251 <p>If --prune-empty is specified, then intentionally placed empty
1252 commits from before the filtering operation are also pruned instead
1253 of just pruning commits that became empty due to filtering rules.</p>
1254 </li>
1255 <li>
1256 <p>If --prune-empty is specified, sometimes empty commits are missed
1257 and left around anyway (a somewhat rare bug, but it happens&#8230;&#8203;)</p>
1258 </li>
1259 <li>
1260 <p>A minor issue, but users who have a goal to update all names and
1261 emails in a repository may be led to --env-filter which will only
1262 update authors and committers, missing taggers.</p>
1263 </li>
1264 <li>
1265 <p>If the user provides a --tag-name-filter that maps multiple tags to
1266 the same name, no warning or error is provided; git-filter-branch
1267 simply overwrites each tag in some undocumented pre-defined order
1268 resulting in only one tag at the end.  (A git-filter-branch
1269 regression test requires this surprising behavior.)</p>
1270 </li>
1271 </ul>
1272 </div>
1273 <div class="paragraph">
1274 <p>Also, the poor performance of git-filter-branch often leads to safety
1275 issues:</p>
1276 </div>
1277 <div class="ulist">
1278 <ul>
1279 <li>
1280 <p>Coming up with the correct shell snippet to do the filtering you
1281 want is sometimes difficult unless you&#8217;re just doing a trivial
1282 modification such as deleting a couple files.  Unfortunately, people
1283 often learn if the snippet is right or wrong by trying it out, but
1284 the rightness or wrongness can vary depending on special
1285 circumstances (spaces in filenames, non-ascii filenames, funny
1286 author names or emails, invalid timezones, presence of grafts or
1287 replace objects, etc.), meaning they may have to wait a long time,
1288 hit an error, then restart.  The performance of git-filter-branch is
1289 so bad that this cycle is painful, reducing the time available to
1290 carefully re-check (to say nothing about what it does to the
1291 patience of the person doing the rewrite even if they do technically
1292 have more time available).  This problem is extra compounded because
1293 errors from broken filters may not be shown for a long time and/or
1294 get lost in a sea of output.  Even worse, broken filters often just
1295 result in silent incorrect rewrites.</p>
1296 </li>
1297 <li>
1298 <p>To top it all off, even when users finally find working commands,
1299 they naturally want to share them.  But they may be unaware that
1300 their repo didn&#8217;t have some special cases that someone else&#8217;s does.
1301 So, when someone else with a different repository runs the same
1302 commands, they get hit by the problems above.  Or, the user just
1303 runs commands that really were vetted for special cases, but they
1304 run it on a different OS where it doesn&#8217;t work, as noted above.</p>
1305 </li>
1306 </ul>
1307 </div>
1308 </div>
1309 </div>
1310 <div class="sect1">
1311 <h2 id="_git">GIT</h2>
1312 <div class="sectionbody">
1313 <div class="paragraph">
1314 <p>Part of the <a href="git.html">git(1)</a> suite</p>
1315 </div>
1316 </div>
1317 </div>
1318 </div>
1319 <div id="footer">
1320 <div id="footer-text">
1321 Last updated 2024-02-08 15:45:59 -0800
1322 </div>
1323 </div>
1324 </body>
1325 </html>