6 git-filter-branch - Rewrite branches
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>...]
20 Lets you rewrite git revision history by creating a new branch from
21 your current branch, applying custom filters on each revision.
22 Those filters can modify each tree (e.g. removing a file or running
23 a perl rewrite on all files) or information about each commit.
24 Otherwise, all information (including original commit times or merge
25 information) will be preserved.
27 The command takes the new branch name as a mandatory argument and
28 the filters as optional arguments. If you specify no filters, the
29 commits will be recommitted without any changes, which would normally
30 have no effect. Nevertheless, this may be useful in the future for
31 compensating for some git bugs or such, therefore such a usage is
34 *WARNING*! The rewritten history will have different object names for all
35 the objects and will not converge with the original branch. You will not
36 be able to easily push and distribute the rewritten branch on top of the
37 original branch. Please do not use this command if you do not know the
38 full implications, and avoid using it anyway, if a simple single commit
39 would suffice to fix your problem.
41 Always verify that the rewritten version is correct: The original refs,
42 if different from the rewritten ones, will be stored in the namespace
45 Note that since this operation is extensively I/O expensive, it might
46 be a good idea to redirect the temporary directory off-disk, e.g. on
47 tmpfs. Reportedly the speedup is very noticeable.
53 The filters are applied in the order as listed below. The <command>
54 argument is always evaluated in shell using the 'eval' command (with the
55 notable exception of the commit filter, for technical reasons).
56 Prior to that, the $GIT_COMMIT environment variable will be set to contain
57 the id of the commit being rewritten. Also, GIT_AUTHOR_NAME,
58 GIT_AUTHOR_EMAIL, GIT_AUTHOR_DATE, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL,
59 and GIT_COMMITTER_DATE are set according to the current commit.
61 A 'map' function is available that takes an "original sha1 id" argument
62 and outputs a "rewritten sha1 id" if the commit has been already
63 rewritten, and "original sha1 id" otherwise; the 'map' function can
64 return several ids on separate lines if your commit filter emitted
71 --env-filter <command>::
72 This is the filter for modifying the environment in which
73 the commit will be performed. Specifically, you might want
74 to rewrite the author/committer name/email/time environment
75 variables (see gitlink:git-commit[1] for details). Do not forget
76 to re-export the variables.
78 --tree-filter <command>::
79 This is the filter for rewriting the tree and its contents.
80 The argument is evaluated in shell with the working
81 directory set to the root of the checked out tree. The new tree
82 is then used as-is (new files are auto-added, disappeared files
83 are auto-removed - neither .gitignore files nor any other ignore
84 rules *HAVE ANY EFFECT*!).
86 --index-filter <command>::
87 This is the filter for rewriting the index. It is similar to the
88 tree filter but does not check out the tree, which makes it much
89 faster. For hairy cases, see gitlink:git-update-index[1].
91 --parent-filter <command>::
92 This is the filter for rewriting the commit's parent list.
93 It will receive the parent string on stdin and shall output
94 the new parent string on stdout. The parent string is in
95 a format accepted by gitlink:git-commit-tree[1]: empty for
96 the initial commit, "-p parent" for a normal commit and
97 "-p parent1 -p parent2 -p parent3 ..." for a merge commit.
99 --msg-filter <command>::
100 This is the filter for rewriting the commit messages.
101 The argument is evaluated in the shell with the original
102 commit message on standard input; its standard output is
103 used as the new commit message.
105 --commit-filter <command>::
106 This is the filter for performing the commit.
107 If this filter is specified, it will be called instead of the
108 gitlink:git-commit-tree[1] command, with arguments of the form
109 "<TREE_ID> [-p <PARENT_COMMIT_ID>]..." and the log message on
110 stdin. The commit id is expected on stdout.
112 As a special extension, the commit filter may emit multiple
113 commit ids; in that case, ancestors of the original commit will
114 have all of them as parents.
116 --tag-name-filter <command>::
117 This is the filter for rewriting tag names. When passed,
118 it will be called for every tag ref that points to a rewritten
119 object (or to a tag object which points to a rewritten object).
120 The original tag name is passed via standard input, and the new
121 tag name is expected on standard output.
123 The original tags are not deleted, but can be overwritten;
124 use "--tag-name-filter cat" to simply update the tags. In this
125 case, be very careful and make sure you have the old tags
126 backed up in case the conversion has run afoul.
128 Note that there is currently no support for proper rewriting of
129 tag objects; in layman terms, if the tag has a message or signature
130 attached, the rewritten tag won't have it. Sorry. (It is by
131 definition impossible to preserve signatures at any rate.)
133 --subdirectory-filter <directory>::
134 Only look at the history which touches the given subdirectory.
135 The result will contain that directory (and only that) as its
138 --original <namespace>::
139 Use this option to set the namespace where the original commits
140 will be stored. The default value is 'refs/original'.
143 Use this option to set the path to the temporary directory used for
144 rewriting. When applying a tree filter, the command needs to
145 temporary checkout the tree to some directory, which may consume
146 considerable space in case of large projects. By default it
147 does this in the '.git-rewrite/' directory but you can override
148 that choice by this parameter.
151 `git filter-branch` refuses to start with an existing temporary
152 directory or when there are already refs starting with
153 'refs/original/', unless forced.
156 When options are given after the new branch name, they will
157 be passed to gitlink:git-rev-list[1]. Only commits in the resulting
158 output will be filtered, although the filtered commits can still
159 reference parents which are outside of that set.
165 Suppose you want to remove a file (containing confidential information
166 or copyright violation) from all commits:
168 -------------------------------------------------------
169 git filter-branch --tree-filter 'rm filename' HEAD
170 -------------------------------------------------------
172 A significantly faster version:
174 --------------------------------------------------------------------------
175 git filter-branch --index-filter 'git update-index --remove filename' HEAD
176 --------------------------------------------------------------------------
178 Now, you will get the rewritten history saved in the branch 'newbranch'
179 (your current branch is left untouched).
181 To set a commit (which typically is at the tip of another
182 history) to be the parent of the current initial commit, in
183 order to paste the other history behind the current history:
185 -------------------------------------------------------------------
186 git filter-branch --parent-filter 'sed "s/^\$/-p <graft-id>/"' HEAD
187 -------------------------------------------------------------------
189 (if the parent string is empty - therefore we are dealing with the
190 initial commit - add graftcommit as a parent). Note that this assumes
191 history with a single root (that is, no merge without common ancestors
192 happened). If this is not the case, use:
194 --------------------------------------------------------------------------
195 git filter-branch --parent-filter \
196 'cat; test $GIT_COMMIT = <commit-id> && echo "-p <graft-id>"' HEAD
197 --------------------------------------------------------------------------
201 -----------------------------------------------
202 echo "$commit-id $graft-id" >> .git/info/grafts
203 git filter-branch $graft-id..HEAD
204 -----------------------------------------------
206 To remove commits authored by "Darl McBribe" from the history:
208 ------------------------------------------------------------------------------
209 git filter-branch --commit-filter '
210 if [ "$GIT_AUTHOR_NAME" = "Darl McBribe" ];
220 git commit-tree "$@";
222 ------------------------------------------------------------------------------
224 The shift magic first throws away the tree id and then the -p
225 parameters. Note that this handles merges properly! In case Darl
226 committed a merge between P1 and P2, it will be propagated properly
227 and all children of the merge will become merge commits with P1,P2
228 as their parents instead of the merge commit.
230 To restrict rewriting to only part of the history, specify a revision
231 range in addition to the new branch name. The new branch name will
232 point to the top-most revision that a 'git rev-list' of this range
235 Note that the changes introduced by the commits, and not reverted by
236 subsequent commits, will still be in the rewritten branch. If you want
237 to throw out _changes_ together with the commits, you should use the
238 interactive mode of gitlink:git-rebase[1].
240 Consider this history:
248 To rewrite only commits D,E,F,G,H, but leave A, B and C alone, use:
250 --------------------------------
251 git filter-branch ... C..H
252 --------------------------------
254 To rewrite commits E,F,G,H, use one of these:
256 ----------------------------------------
257 git filter-branch ... C..H --not D
258 git filter-branch ... D..H --not C
259 ----------------------------------------
261 To move the whole tree into a subdirectory, or remove it from there:
263 ---------------------------------------------------------------
264 git filter-branch --index-filter \
265 'git ls-files -s | sed "s-\t-&newsubdir/-" |
266 GIT_INDEX_FILE=$GIT_INDEX_FILE.new \
267 git update-index --index-info &&
268 mv $GIT_INDEX_FILE.new $GIT_INDEX_FILE' HEAD
269 ---------------------------------------------------------------
274 Written by Petr "Pasky" Baudis <pasky@suse.cz>,
275 and the git list <git@vger.kernel.org>
279 Documentation by Petr Baudis and the git list.
283 Part of the gitlink:git[7] suite