363287d0ab39e1189cec4090f767cfe0ce1511fe
1 git-filter-branch(1)
2 ====================
4 NAME
5 ----
6 git-filter-branch - Rewrite branches
8 SYNOPSIS
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 [-d <directory>] <new-branch-name> [<rev-list options>...]
17 DESCRIPTION
18 -----------
19 Lets you rewrite git revision history by creating a new branch from
20 your current branch, applying custom filters on each revision.
21 Those filters can modify each tree (e.g. removing a file or running
22 a perl rewrite on all files) or information about each commit.
23 Otherwise, all information (including original commit times or merge
24 information) will be preserved.
26 The command takes the new branch name as a mandatory argument and
27 the filters as optional arguments. If you specify no filters, the
28 commits will be recommitted without any changes, which would normally
29 have no effect and result in the new branch pointing to the same
30 branch as your current branch. Nevertheless, this may be useful in
31 the future for compensating for some git bugs or such, therefore
32 such a usage is permitted.
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 before disposing
42 the original branch.
44 Note that since this operation is extensively I/O expensive, it might
45 be a good idea to redirect the temporary directory off-disk, e.g. on
46 tmpfs. Reportedly the speedup is very noticeable.
49 Filters
50 ~~~~~~~
52 The filters are applied in the order as listed below. The <command>
53 argument is always evaluated in shell using the 'eval' command.
54 Prior to that, the $GIT_COMMIT environment variable will be set to contain
55 the id of the commit being rewritten. Also, GIT_AUTHOR_NAME,
56 GIT_AUTHOR_EMAIL, GIT_AUTHOR_DATE, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL,
57 and GIT_COMMITTER_DATE are set according to the current commit.
59 A 'map' function is available that takes an "original sha1 id" argument
60 and outputs a "rewritten sha1 id" if the commit has been already
61 rewritten, fails otherwise; the 'map' function can return several
62 ids on separate lines if your commit filter emitted multiple commits.
65 OPTIONS
66 -------
68 --env-filter <command>::
69 This is the filter for modifying the environment in which
70 the commit will be performed. Specifically, you might want
71 to rewrite the author/committer name/email/time environment
72 variables (see gitlink:git-commit[1] for details). Do not forget
73 to re-export the variables.
75 --tree-filter <command>::
76 This is the filter for rewriting the tree and its contents.
77 The argument is evaluated in shell with the working
78 directory set to the root of the checked out tree. The new tree
79 is then used as-is (new files are auto-added, disappeared files
80 are auto-removed - neither .gitignore files nor any other ignore
81 rules *HAVE ANY EFFECT*!).
83 --index-filter <command>::
84 This is the filter for rewriting the index. It is similar to the
85 tree filter but does not check out the tree, which makes it much
86 faster. For hairy cases, see gitlink:git-update-index[1].
88 --parent-filter <command>::
89 This is the filter for rewriting the commit's parent list.
90 It will receive the parent string on stdin and shall output
91 the new parent string on stdout. The parent string is in
92 a format accepted by gitlink:git-commit-tree[1]: empty for
93 the initial commit, "-p parent" for a normal commit and
94 "-p parent1 -p parent2 -p parent3 ..." for a merge commit.
96 --msg-filter <command>::
97 This is the filter for rewriting the commit messages.
98 The argument is evaluated in the shell with the original
99 commit message on standard input; its standard output is
100 used as the new commit message.
102 --commit-filter <command>::
103 This is the filter for performing the commit.
104 If this filter is specified, it will be called instead of the
105 gitlink:git-commit-tree[1] command, with arguments of the form
106 "<TREE_ID> [-p <PARENT_COMMIT_ID>]..." and the log message on
107 stdin. The commit id is expected on stdout.
108 +
109 As a special extension, the commit filter may emit multiple
110 commit ids; in that case, ancestors of the original commit will
111 have all of them as parents.
113 --tag-name-filter <command>::
114 This is the filter for rewriting tag names. When passed,
115 it will be called for every tag ref that points to a rewritten
116 object (or to a tag object which points to a rewritten object).
117 The original tag name is passed via standard input, and the new
118 tag name is expected on standard output.
119 +
120 The original tags are not deleted, but can be overwritten;
121 use "--tag-name-filter=cat" to simply update the tags. In this
122 case, be very careful and make sure you have the old tags
123 backed up in case the conversion has run afoul.
124 +
125 Note that there is currently no support for proper rewriting of
126 tag objects; in layman terms, if the tag has a message or signature
127 attached, the rewritten tag won't have it. Sorry. (It is by
128 definition impossible to preserve signatures at any rate.)
130 --subdirectory-filter <directory>::
131 Only look at the history which touches the given subdirectory.
132 The result will contain that directory (and only that) as its
133 project root.
135 -d <directory>::
136 Use this option to set the path to the temporary directory used for
137 rewriting. When applying a tree filter, the command needs to
138 temporary checkout the tree to some directory, which may consume
139 considerable space in case of large projects. By default it
140 does this in the '.git-rewrite/' directory but you can override
141 that choice by this parameter.
143 <rev-list-options>::
144 When options are given after the new branch name, they will
145 be passed to gitlink:git-rev-list[1]. Only commits in the resulting
146 output will be filtered, although the filtered commits can still
147 reference parents which are outside of that set.
150 Examples
151 --------
153 Suppose you want to remove a file (containing confidential information
154 or copyright violation) from all commits:
156 -------------------------------------------------------
157 git filter-branch --tree-filter 'rm filename' newbranch
158 -------------------------------------------------------
160 A significantly faster version:
162 -------------------------------------------------------------------------------
163 git filter-branch --index-filter 'git update-index --remove filename' newbranch
164 -------------------------------------------------------------------------------
166 Now, you will get the rewritten history saved in the branch 'newbranch'
167 (your current branch is left untouched).
169 To "etch-graft" a commit to the revision history (set a commit to be
170 the parent of the current initial commit and propagate that):
172 ----------------------------------------------------------------------
173 git filter-branch --parent-filter sed\ 's/^$/-p <graft-id>/' newbranch
174 ----------------------------------------------------------------------
176 (if the parent string is empty - therefore we are dealing with the
177 initial commit - add graftcommit as a parent). Note that this assumes
178 history with a single root (that is, no merge without common ancestors
179 happened). If this is not the case, use:
181 -------------------------------------------------------------------------------
182 git filter-branch --parent-filter \
183 'cat; test $GIT_COMMIT = <commit-id> && echo "-p <graft-id>"' newbranch
184 -------------------------------------------------------------------------------
186 To remove commits authored by "Darl McBribe" from the history:
188 ------------------------------------------------------------------------------
189 git filter-branch --commit-filter '
190 if [ "$GIT_AUTHOR_NAME" = "Darl McBribe" ];
191 then
192 shift;
193 while [ -n "$1" ];
194 do
195 shift;
196 echo "$1";
197 shift;
198 done;
199 else
200 git commit-tree "$@";
201 fi' newbranch
202 ------------------------------------------------------------------------------
204 The shift magic first throws away the tree id and then the -p
205 parameters. Note that this handles merges properly! In case Darl
206 committed a merge between P1 and P2, it will be propagated properly
207 and all children of the merge will become merge commits with P1,P2
208 as their parents instead of the merge commit.
210 To restrict rewriting to only part of the history, specify a revision
211 range in addition to the new branch name. The new branch name will
212 point to the top-most revision that a 'git rev-list' of this range
213 will print.
215 Note that the changes introduced by the commits, and not reverted by
216 subsequent commits, will still be in the rewritten branch. If you want
217 to throw out _changes_ together with the commits, you should use the
218 interactive mode of gitlink:git-rebase[1].
220 Consider this history:
222 ------------------
223 D--E--F--G--H
224 / /
225 A--B-----C
226 ------------------
228 To rewrite only commits D,E,F,G,H, but leave A, B and C alone, use:
230 --------------------------------
231 git filter-branch ... new-H C..H
232 --------------------------------
234 To rewrite commits E,F,G,H, use one of these:
236 ----------------------------------------
237 git filter-branch ... new-H C..H --not D
238 git filter-branch ... new-H D..H --not C
239 ----------------------------------------
241 To move the whole tree into a subdirectory, or remove it from there:
243 ---------------------------------------------------------------
244 git filter-branch --index-filter \
245 'git ls-files -s | sed "s-\t-&newsubdir/-" |
246 GIT_INDEX_FILE=$GIT_INDEX_FILE.new \
247 git update-index --index-info &&
248 mv $GIT_INDEX_FILE.new $GIT_INDEX_FILE' directorymoved
249 ---------------------------------------------------------------
252 Author
253 ------
254 Written by Petr "Pasky" Baudis <pasky@suse.cz>,
255 and the git list <git@vger.kernel.org>
257 Documentation
258 --------------
259 Documentation by Petr Baudis and the git list.
261 GIT
262 ---
263 Part of the gitlink:git[7] suite