1git-filter-branch(1) 2==================== 3 4NAME 5---- 6git-filter-branch - Rewrite branches 7 8SYNOPSIS 9-------- 10[verse] 11'git filter-branch' [--env-filter <command>] [--tree-filter <command>] 12 [--index-filter <command>] [--parent-filter <command>] 13 [--msg-filter <command>] [--commit-filter <command>] 14 [--tag-name-filter <command>] [--subdirectory-filter <directory>] 15 [--original <namespace>] [-d <directory>] [-f | --force] 16 [--] [<rev-list options>...] 17 18DESCRIPTION 19----------- 20Lets you rewrite git revision history by rewriting the branches mentioned 21in the <rev-list options>, applying custom filters on each revision. 22Those filters can modify each tree (e.g. removing a file or running 23a perl rewrite on all files) or information about each commit. 24Otherwise, all information (including original commit times or merge 25information) will be preserved. 26 27The command will only rewrite the _positive_ refs mentioned in the 28command line (e.g. if you pass 'a..b', only 'b' will be rewritten). 29If you specify no filters, the commits will be recommitted without any 30changes, which would normally have no effect. Nevertheless, this may be 31useful in the future for compensating for some git bugs or such, 32therefore such a usage is permitted. 33 34*NOTE*: This command honors `.git/info/grafts`. If you have any grafts 35defined, running this command will make them permanent. 36 37*WARNING*! The rewritten history will have different object names for all 38the objects and will not converge with the original branch. You will not 39be able to easily push and distribute the rewritten branch on top of the 40original branch. Please do not use this command if you do not know the 41full implications, and avoid using it anyway, if a simple single commit 42would suffice to fix your problem. (See the "RECOVERING FROM UPSTREAM 43REBASE" section in linkgit:git-rebase[1] for further information about 44rewriting published history.) 45 46Always verify that the rewritten version is correct: The original refs, 47if different from the rewritten ones, will be stored in the namespace 48'refs/original/'. 49 50Note that since this operation is very I/O expensive, it might 51be a good idea to redirect the temporary directory off-disk with the 52'-d' option, e.g. on tmpfs. Reportedly the speedup is very noticeable. 53 54 55Filters 56~~~~~~~ 57 58The filters are applied in the order as listed below. The <command> 59argument is always evaluated in the shell context using the 'eval' command 60(with the notable exception of the commit filter, for technical reasons). 61Prior to that, the $GIT_COMMIT environment variable will be set to contain 62the id of the commit being rewritten. Also, GIT_AUTHOR_NAME, 63GIT_AUTHOR_EMAIL, GIT_AUTHOR_DATE, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL, 64and GIT_COMMITTER_DATE are set according to the current commit. The values 65of these variables after the filters have run, are used for the new commit. 66If any evaluation of <command> returns a non-zero exit status, the whole 67operation will be aborted. 68 69A 'map' function is available that takes an "original sha1 id" argument 70and outputs a "rewritten sha1 id" if the commit has been already 71rewritten, and "original sha1 id" otherwise; the 'map' function can 72return several ids on separate lines if your commit filter emitted 73multiple commits. 74 75 76OPTIONS 77------- 78 79--env-filter <command>:: 80 This filter may be used if you only need to modify the environment 81 in which the commit will be performed. Specifically, you might 82 want to rewrite the author/committer name/email/time environment 83 variables (see linkgit:git-commit[1] for details). Do not forget 84 to re-export the variables. 85 86--tree-filter <command>:: 87 This is the filter for rewriting the tree and its contents. 88 The argument is evaluated in shell with the working 89 directory set to the root of the checked out tree. The new tree 90 is then used as-is (new files are auto-added, disappeared files 91 are auto-removed - neither .gitignore files nor any other ignore 92 rules *HAVE ANY EFFECT*!). 93 94--index-filter <command>:: 95 This is the filter for rewriting the index. It is similar to the 96 tree filter but does not check out the tree, which makes it much 97 faster. For hairy cases, see linkgit:git-update-index[1]. 98 99--parent-filter <command>:: 100 This is the filter for rewriting the commit's parent list. 101 It will receive the parent string on stdin and shall output 102 the new parent string on stdout. The parent string is in 103 the format described in linkgit:git-commit-tree[1]: empty for 104 the initial commit, "-p parent" for a normal commit and 105 "-p parent1 -p parent2 -p parent3 ..." for a merge commit. 106 107--msg-filter <command>:: 108 This is the filter for rewriting the commit messages. 109 The argument is evaluated in the shell with the original 110 commit message on standard input; its standard output is 111 used as the new commit message. 112 113--commit-filter <command>:: 114 This is the filter for performing the commit. 115 If this filter is specified, it will be called instead of the 116 'git-commit-tree' command, with arguments of the form 117 "<TREE_ID> [-p <PARENT_COMMIT_ID>]..." and the log message on 118 stdin. The commit id is expected on stdout. 119+ 120As a special extension, the commit filter may emit multiple 121commit ids; in that case, the rewritten children of the original commit will 122have all of them as parents. 123+ 124You can use the 'map' convenience function in this filter, and other 125convenience functions, too. For example, calling 'skip_commit "$@"' 126will leave out the current commit (but not its changes! If you want 127that, use 'git-rebase' instead). 128 129--tag-name-filter <command>:: 130 This is the filter for rewriting tag names. When passed, 131 it will be called for every tag ref that points to a rewritten 132 object (or to a tag object which points to a rewritten object). 133 The original tag name is passed via standard input, and the new 134 tag name is expected on standard output. 135+ 136The original tags are not deleted, but can be overwritten; 137use "--tag-name-filter cat" to simply update the tags. In this 138case, be very careful and make sure you have the old tags 139backed up in case the conversion has run afoul. 140+ 141Nearly proper rewriting of tag objects is supported. If the tag has 142a message attached, a new tag object will be created with the same message, 143author, and timestamp. If the tag has a signature attached, the 144signature will be stripped. It is by definition impossible to preserve 145signatures. The reason this is "nearly" proper, is because ideally if 146the tag did not change (points to the same object, has the same name, etc.) 147it should retain any signature. That is not the case, signatures will always 148be removed, buyer beware. There is also no support for changing the 149author or timestamp (or the tag message for that matter). Tags which point 150to other tags will be rewritten to point to the underlying commit. 151 152--subdirectory-filter <directory>:: 153 Only look at the history which touches the given subdirectory. 154 The result will contain that directory (and only that) as its 155 project root. 156 157--original <namespace>:: 158 Use this option to set the namespace where the original commits 159 will be stored. The default value is 'refs/original'. 160 161-d <directory>:: 162 Use this option to set the path to the temporary directory used for 163 rewriting. When applying a tree filter, the command needs to 164 temporarily check out the tree to some directory, which may consume 165 considerable space in case of large projects. By default it 166 does this in the '.git-rewrite/' directory but you can override 167 that choice by this parameter. 168 169-f:: 170--force:: 171 'git-filter-branch' refuses to start with an existing temporary 172 directory or when there are already refs starting with 173 'refs/original/', unless forced. 174 175<rev-list options>...:: 176 Arguments for 'git-rev-list'. All positive refs included by 177 these options are rewritten. You may also specify options 178 such as '--all', but you must use '--' to separate them from 179 the 'git-filter-branch' options. 180 181 182Examples 183-------- 184 185Suppose you want to remove a file (containing confidential information 186or copyright violation) from all commits: 187 188------------------------------------------------------- 189git filter-branch --tree-filter 'rm filename' HEAD 190------------------------------------------------------- 191 192However, if the file is absent from the tree of some commit, 193a simple `rm filename` will fail for that tree and commit. 194Thus you may instead want to use `rm -f filename` as the script. 195 196A significantly faster version: 197 198-------------------------------------------------------------------------- 199git filter-branch --index-filter 'git rm --cached filename' HEAD 200-------------------------------------------------------------------------- 201 202Now, you will get the rewritten history saved in HEAD. 203 204To rewrite the repository to look as if `foodir/` had been its project 205root, and discard all other history: 206 207------------------------------------------------------- 208git filter-branch --subdirectory-filter foodir -- --all 209------------------------------------------------------- 210 211Thus you can, e.g., turn a library subdirectory into a repository of 212its own. Note the `\--` that separates 'filter-branch' options from 213revision options, and the `\--all` to rewrite all branches and tags. 214 215To set a commit (which typically is at the tip of another 216history) to be the parent of the current initial commit, in 217order to paste the other history behind the current history: 218 219------------------------------------------------------------------- 220git filter-branch --parent-filter 'sed "s/^\$/-p <graft-id>/"' HEAD 221------------------------------------------------------------------- 222 223(if the parent string is empty - which happens when we are dealing with 224the initial commit - add graftcommit as a parent). Note that this assumes 225history with a single root (that is, no merge without common ancestors 226happened). If this is not the case, use: 227 228-------------------------------------------------------------------------- 229git filter-branch --parent-filter \ 230 'test $GIT_COMMIT = <commit-id> && echo "-p <graft-id>" || cat' HEAD 231-------------------------------------------------------------------------- 232 233or even simpler: 234 235----------------------------------------------- 236echo "$commit-id $graft-id" >> .git/info/grafts 237git filter-branch $graft-id..HEAD 238----------------------------------------------- 239 240To remove commits authored by "Darl McBribe" from the history: 241 242------------------------------------------------------------------------------ 243git filter-branch --commit-filter ' 244 if [ "$GIT_AUTHOR_NAME" = "Darl McBribe" ]; 245 then 246 skip_commit "$@"; 247 else 248 git commit-tree "$@"; 249 fi' HEAD 250------------------------------------------------------------------------------ 251 252The function 'skip_commit' is defined as follows: 253 254-------------------------- 255skip_commit() 256{ 257 shift; 258 while [ -n "$1" ]; 259 do 260 shift; 261 map "$1"; 262 shift; 263 done; 264} 265-------------------------- 266 267The shift magic first throws away the tree id and then the -p 268parameters. Note that this handles merges properly! In case Darl 269committed a merge between P1 and P2, it will be propagated properly 270and all children of the merge will become merge commits with P1,P2 271as their parents instead of the merge commit. 272 273You can rewrite the commit log messages using `--msg-filter`. For 274example, 'git-svn-id' strings in a repository created by 'git-svn' can 275be removed this way: 276 277------------------------------------------------------- 278git filter-branch --msg-filter ' 279 sed -e "/^git-svn-id:/d" 280' 281------------------------------------------------------- 282 283To restrict rewriting to only part of the history, specify a revision 284range in addition to the new branch name. The new branch name will 285point to the top-most revision that a 'git-rev-list' of this range 286will print. 287 288*NOTE* the changes introduced by the commits, and which are not reverted 289by subsequent commits, will still be in the rewritten branch. If you want 290to throw out _changes_ together with the commits, you should use the 291interactive mode of 'git-rebase'. 292 293 294Consider this history: 295 296------------------ 297 D--E--F--G--H 298 / / 299A--B-----C 300------------------ 301 302To rewrite only commits D,E,F,G,H, but leave A, B and C alone, use: 303 304-------------------------------- 305git filter-branch ... C..H 306-------------------------------- 307 308To rewrite commits E,F,G,H, use one of these: 309 310---------------------------------------- 311git filter-branch ... C..H --not D 312git filter-branch ... D..H --not C 313---------------------------------------- 314 315To move the whole tree into a subdirectory, or remove it from there: 316 317--------------------------------------------------------------- 318git filter-branch --index-filter \ 319 'git ls-files -s | sed "s-\t-&newsubdir/-" | 320 GIT_INDEX_FILE=$GIT_INDEX_FILE.new \ 321 git update-index --index-info && 322 mv $GIT_INDEX_FILE.new $GIT_INDEX_FILE' HEAD 323--------------------------------------------------------------- 324 325 326Author 327------ 328Written by Petr "Pasky" Baudis <pasky@suse.cz>, 329and the git list <git@vger.kernel.org> 330 331Documentation 332-------------- 333Documentation by Petr Baudis and the git list. 334 335GIT 336--- 337Part of the linkgit:git[1] suite