git-am: Do not exit silently if committer is unset
[git/jnareb-git.git] / Documentation / git-filter-branch.txt
blobea77f1fce505fbb9c1691f7e75aa014e7a1d5be5
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         [--original <namespace>] [-d <directory>] [-f | --force]
16         [<rev-list options>...]
18 DESCRIPTION
19 -----------
20 Lets you rewrite git revision history by rewriting the branches mentioned
21 in the <rev-list options>, 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 will only rewrite the _positive_ refs mentioned in the
28 command line (e.g. if you pass 'a..b', only 'b' will be rewritten).
29 If you specify no filters, the commits will be recommitted without any
30 changes, which would normally have no effect.  Nevertheless, this may be
31 useful in the future for compensating for some git bugs or such,
32 therefore 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: The original refs,
42 if different from the rewritten ones, will be stored in the namespace
43 'refs/original/'.
45 Note that since this operation is very I/O expensive, it might
46 be a good idea to redirect the temporary directory off-disk with the
47 '-d' option, e.g. on tmpfs.  Reportedly the speedup is very noticeable.
50 Filters
51 ~~~~~~~
53 The filters are applied in the order as listed below.  The <command>
54 argument is always evaluated in the shell context using the 'eval' command
55 (with the 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.  The values
60 of these variables after the filters have run, are used for the new commit.
61 If any evaluation of <command> returns a non-zero exit status, the whole
62 operation will be aborted.
64 A 'map' function is available that takes an "original sha1 id" argument
65 and outputs a "rewritten sha1 id" if the commit has been already
66 rewritten, and "original sha1 id" otherwise; the 'map' function can
67 return several ids on separate lines if your commit filter emitted
68 multiple commits.
71 OPTIONS
72 -------
74 --env-filter <command>::
75         This filter may be used if you only need to modify the environment
76         in which the commit will be performed.  Specifically, you might
77         want to rewrite the author/committer name/email/time environment
78         variables (see linkgit:git-commit[1] for details).  Do not forget
79         to re-export the variables.
81 --tree-filter <command>::
82         This is the filter for rewriting the tree and its contents.
83         The argument is evaluated in shell with the working
84         directory set to the root of the checked out tree.  The new tree
85         is then used as-is (new files are auto-added, disappeared files
86         are auto-removed - neither .gitignore files nor any other ignore
87         rules *HAVE ANY EFFECT*!).
89 --index-filter <command>::
90         This is the filter for rewriting the index.  It is similar to the
91         tree filter but does not check out the tree, which makes it much
92         faster.  For hairy cases, see linkgit:git-update-index[1].
94 --parent-filter <command>::
95         This is the filter for rewriting the commit's parent list.
96         It will receive the parent string on stdin and shall output
97         the new parent string on stdout.  The parent string is in
98         a format accepted by linkgit:git-commit-tree[1]: empty for
99         the initial commit, "-p parent" for a normal commit and
100         "-p parent1 -p parent2 -p parent3 ..." for a merge commit.
102 --msg-filter <command>::
103         This is the filter for rewriting the commit messages.
104         The argument is evaluated in the shell with the original
105         commit message on standard input; its standard output is
106         used as the new commit message.
108 --commit-filter <command>::
109         This is the filter for performing the commit.
110         If this filter is specified, it will be called instead of the
111         linkgit:git-commit-tree[1] command, with arguments of the form
112         "<TREE_ID> [-p <PARENT_COMMIT_ID>]..." and the log message on
113         stdin.  The commit id is expected on stdout.
115 As a special extension, the commit filter may emit multiple
116 commit ids; in that case, the rewritten children of the original commit will
117 have all of them as parents.
119 You can use the 'map' convenience function in this filter, and other
120 convenience functions, too.  For example, calling 'skip_commit "$@"'
121 will leave out the current commit (but not its changes! If you want
122 that, use linkgit:git-rebase[1] instead).
124 --tag-name-filter <command>::
125         This is the filter for rewriting tag names. When passed,
126         it will be called for every tag ref that points to a rewritten
127         object (or to a tag object which points to a rewritten object).
128         The original tag name is passed via standard input, and the new
129         tag name is expected on standard output.
131 The original tags are not deleted, but can be overwritten;
132 use "--tag-name-filter cat" to simply update the tags.  In this
133 case, be very careful and make sure you have the old tags
134 backed up in case the conversion has run afoul.
136 Nearly proper rewriting of tag objects is supported. If the tag has
137 a message attached, a new tag object will be created with the same message,
138 author, and timestamp. If the tag has a signature attached, the
139 signature will be stripped. It is by definition impossible to preserve
140 signatures. The reason this is "nearly" proper, is because ideally if
141 the tag did not change (points to the same object, has the same name, etc.)
142 it should retain any signature. That is not the case, signatures will always
143 be removed, buyer beware. There is also no support for changing the
144 author or timestamp (or the tag message for that matter). Tags which point
145 to other tags will be rewritten to point to the underlying commit.
147 --subdirectory-filter <directory>::
148         Only look at the history which touches the given subdirectory.
149         The result will contain that directory (and only that) as its
150         project root.
152 --original <namespace>::
153         Use this option to set the namespace where the original commits
154         will be stored. The default value is 'refs/original'.
156 -d <directory>::
157         Use this option to set the path to the temporary directory used for
158         rewriting.  When applying a tree filter, the command needs to
159         temporarily check out the tree to some directory, which may consume
160         considerable space in case of large projects.  By default it
161         does this in the '.git-rewrite/' directory but you can override
162         that choice by this parameter.
164 -f::
165 --force::
166         `git filter-branch` refuses to start with an existing temporary
167         directory or when there are already refs starting with
168         'refs/original/', unless forced.
170 <rev-list-options>::
171         When options are given after the new branch name, they will
172         be passed to linkgit:git-rev-list[1].  Only commits in the resulting
173         output will be filtered, although the filtered commits can still
174         reference parents which are outside of that set.
177 Examples
178 --------
180 Suppose you want to remove a file (containing confidential information
181 or copyright violation) from all commits:
183 -------------------------------------------------------
184 git filter-branch --tree-filter 'rm filename' HEAD
185 -------------------------------------------------------
187 However, if the file is absent from the tree of some commit,
188 a simple `rm filename` will fail for that tree and commit.
189 Thus you may instead want to use `rm -f filename` as the script.
191 A significantly faster version:
193 --------------------------------------------------------------------------
194 git filter-branch --index-filter 'git update-index --remove filename' HEAD
195 --------------------------------------------------------------------------
197 Now, you will get the rewritten history saved in HEAD.
199 To set a commit (which typically is at the tip of another
200 history) to be the parent of the current initial commit, in
201 order to paste the other history behind the current history:
203 -------------------------------------------------------------------
204 git filter-branch --parent-filter 'sed "s/^\$/-p <graft-id>/"' HEAD
205 -------------------------------------------------------------------
207 (if the parent string is empty - which happens when we are dealing with
208 the initial commit - add graftcommit as a parent).  Note that this assumes
209 history with a single root (that is, no merge without common ancestors
210 happened).  If this is not the case, use:
212 --------------------------------------------------------------------------
213 git filter-branch --parent-filter \
214         'test $GIT_COMMIT = <commit-id> && echo "-p <graft-id>" || cat' HEAD
215 --------------------------------------------------------------------------
217 or even simpler:
219 -----------------------------------------------
220 echo "$commit-id $graft-id" >> .git/info/grafts
221 git filter-branch $graft-id..HEAD
222 -----------------------------------------------
224 To remove commits authored by "Darl McBribe" from the history:
226 ------------------------------------------------------------------------------
227 git filter-branch --commit-filter '
228         if [ "$GIT_AUTHOR_NAME" = "Darl McBribe" ];
229         then
230                 skip_commit "$@";
231         else
232                 git commit-tree "$@";
233         fi' HEAD
234 ------------------------------------------------------------------------------
236 The function 'skip_commit' is defined as follows:
238 --------------------------
239 skip_commit()
241         shift;
242         while [ -n "$1" ];
243         do
244                 shift;
245                 map "$1";
246                 shift;
247         done;
249 --------------------------
251 The shift magic first throws away the tree id and then the -p
252 parameters.  Note that this handles merges properly! In case Darl
253 committed a merge between P1 and P2, it will be propagated properly
254 and all children of the merge will become merge commits with P1,P2
255 as their parents instead of the merge commit.
257 You can rewrite the commit log messages using `--msg-filter`.  For
258 example, `git-svn-id` strings in a repository created by `git-svn` can
259 be removed this way:
261 -------------------------------------------------------
262 git filter-branch --msg-filter '
263         sed -e "/^git-svn-id:/d"
265 -------------------------------------------------------
267 To restrict rewriting to only part of the history, specify a revision
268 range in addition to the new branch name.  The new branch name will
269 point to the top-most revision that a 'git rev-list' of this range
270 will print.
272 *NOTE* the changes introduced by the commits, and which are not reverted
273 by subsequent commits, will still be in the rewritten branch. If you want
274 to throw out _changes_ together with the commits, you should use the
275 interactive mode of linkgit:git-rebase[1].
278 Consider this history:
280 ------------------
281      D--E--F--G--H
282     /     /
283 A--B-----C
284 ------------------
286 To rewrite only commits D,E,F,G,H, but leave A, B and C alone, use:
288 --------------------------------
289 git filter-branch ... C..H
290 --------------------------------
292 To rewrite commits E,F,G,H, use one of these:
294 ----------------------------------------
295 git filter-branch ... C..H --not D
296 git filter-branch ... D..H --not C
297 ----------------------------------------
299 To move the whole tree into a subdirectory, or remove it from there:
301 ---------------------------------------------------------------
302 git filter-branch --index-filter \
303         'git ls-files -s | sed "s-\t-&newsubdir/-" |
304                 GIT_INDEX_FILE=$GIT_INDEX_FILE.new \
305                         git update-index --index-info &&
306          mv $GIT_INDEX_FILE.new $GIT_INDEX_FILE' HEAD
307 ---------------------------------------------------------------
310 Author
311 ------
312 Written by Petr "Pasky" Baudis <pasky@suse.cz>,
313 and the git list <git@vger.kernel.org>
315 Documentation
316 --------------
317 Documentation by Petr Baudis and the git list.
321 Part of the linkgit:git[1] suite