MinGW: 64-bit file offsets
[git/platforms.git] / Documentation / git-filter-branch.txt
blob451950bab67702a236c55e77d6f3a0723a812488
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.  (See the "RECOVERING FROM UPSTREAM
40 REBASE" section in linkgit:git-rebase[1] for further information about
41 rewriting published history.)
43 Always verify that the rewritten version is correct: The original refs,
44 if different from the rewritten ones, will be stored in the namespace
45 'refs/original/'.
47 Note that since this operation is very I/O expensive, it might
48 be a good idea to redirect the temporary directory off-disk with the
49 '-d' option, e.g. on tmpfs.  Reportedly the speedup is very noticeable.
52 Filters
53 ~~~~~~~
55 The filters are applied in the order as listed below.  The <command>
56 argument is always evaluated in the shell context using the 'eval' command
57 (with the notable exception of the commit filter, for technical reasons).
58 Prior to that, the $GIT_COMMIT environment variable will be set to contain
59 the id of the commit being rewritten.  Also, GIT_AUTHOR_NAME,
60 GIT_AUTHOR_EMAIL, GIT_AUTHOR_DATE, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL,
61 and GIT_COMMITTER_DATE are set according to the current commit.  The values
62 of these variables after the filters have run, are used for the new commit.
63 If any evaluation of <command> returns a non-zero exit status, the whole
64 operation will be aborted.
66 A 'map' function is available that takes an "original sha1 id" argument
67 and outputs a "rewritten sha1 id" if the commit has been already
68 rewritten, and "original sha1 id" otherwise; the 'map' function can
69 return several ids on separate lines if your commit filter emitted
70 multiple commits.
73 OPTIONS
74 -------
76 --env-filter <command>::
77         This filter may be used if you only need to modify the environment
78         in which the commit will be performed.  Specifically, you might
79         want to rewrite the author/committer name/email/time environment
80         variables (see linkgit:git-commit[1] for details).  Do not forget
81         to re-export the variables.
83 --tree-filter <command>::
84         This is the filter for rewriting the tree and its contents.
85         The argument is evaluated in shell with the working
86         directory set to the root of the checked out tree.  The new tree
87         is then used as-is (new files are auto-added, disappeared files
88         are auto-removed - neither .gitignore files nor any other ignore
89         rules *HAVE ANY EFFECT*!).
91 --index-filter <command>::
92         This is the filter for rewriting the index.  It is similar to the
93         tree filter but does not check out the tree, which makes it much
94         faster.  For hairy cases, see linkgit:git-update-index[1].
96 --parent-filter <command>::
97         This is the filter for rewriting the commit's parent list.
98         It will receive the parent string on stdin and shall output
99         the new parent string on stdout.  The parent string is in
100         the format described in linkgit:git-commit-tree[1]: empty for
101         the initial commit, "-p parent" for a normal commit and
102         "-p parent1 -p parent2 -p parent3 ..." for a merge commit.
104 --msg-filter <command>::
105         This is the filter for rewriting the commit messages.
106         The argument is evaluated in the shell with the original
107         commit message on standard input; its standard output is
108         used as the new commit message.
110 --commit-filter <command>::
111         This is the filter for performing the commit.
112         If this filter is specified, it will be called instead of the
113         'git-commit-tree' command, with arguments of the form
114         "<TREE_ID> [-p <PARENT_COMMIT_ID>]..." and the log message on
115         stdin.  The commit id is expected on stdout.
117 As a special extension, the commit filter may emit multiple
118 commit ids; in that case, the rewritten children of the original commit will
119 have all of them as parents.
121 You can use the 'map' convenience function in this filter, and other
122 convenience functions, too.  For example, calling 'skip_commit "$@"'
123 will leave out the current commit (but not its changes! If you want
124 that, use 'git-rebase' instead).
126 You can also use the 'git_commit_non_empty_tree "$@"' instead of
127 'git commit-tree "$@"' if you don't wish to keep commits with a single parent
128 and that makes no change to the tree.
130 --tag-name-filter <command>::
131         This is the filter for rewriting tag names. When passed,
132         it will be called for every tag ref that points to a rewritten
133         object (or to a tag object which points to a rewritten object).
134         The original tag name is passed via standard input, and the new
135         tag name is expected on standard output.
137 The original tags are not deleted, but can be overwritten;
138 use "--tag-name-filter cat" to simply update the tags.  In this
139 case, be very careful and make sure you have the old tags
140 backed up in case the conversion has run afoul.
142 Nearly proper rewriting of tag objects is supported. If the tag has
143 a message attached, a new tag object will be created with the same message,
144 author, and timestamp. If the tag has a signature attached, the
145 signature will be stripped. It is by definition impossible to preserve
146 signatures. The reason this is "nearly" proper, is because ideally if
147 the tag did not change (points to the same object, has the same name, etc.)
148 it should retain any signature. That is not the case, signatures will always
149 be removed, buyer beware. There is also no support for changing the
150 author or timestamp (or the tag message for that matter). Tags which point
151 to other tags will be rewritten to point to the underlying commit.
153 --subdirectory-filter <directory>::
154         Only look at the history which touches the given subdirectory.
155         The result will contain that directory (and only that) as its
156         project root.
158 --prune-empty::
159         Some kind of filters will generate empty commits, that left the tree
160         untouched.  This switch allow git-filter-branch to ignore such
161         commits.  Though, this switch only applies for commits that have one
162         and only one parent, it will hence keep merges points. Also, this
163         option is not compatible with the use of '--commit-filter'. Though you
164         just need to use the function 'git_commit_non_empty_tree "$@"' instead
165         of the 'git commit-tree "$@"' idiom in your commit filter to make that
166         happen.
168 --original <namespace>::
169         Use this option to set the namespace where the original commits
170         will be stored. The default value is 'refs/original'.
172 -d <directory>::
173         Use this option to set the path to the temporary directory used for
174         rewriting.  When applying a tree filter, the command needs to
175         temporarily check out the tree to some directory, which may consume
176         considerable space in case of large projects.  By default it
177         does this in the '.git-rewrite/' directory but you can override
178         that choice by this parameter.
180 -f::
181 --force::
182         'git-filter-branch' refuses to start with an existing temporary
183         directory or when there are already refs starting with
184         'refs/original/', unless forced.
186 <rev-list options>...::
187         Arguments for 'git-rev-list'.  All positive refs included by
188         these options are rewritten.  You may also specify options
189         such as '--all', but you must use '--' to separate them from
190         the 'git-filter-branch' options.
193 Examples
194 --------
196 Suppose you want to remove a file (containing confidential information
197 or copyright violation) from all commits:
199 -------------------------------------------------------
200 git filter-branch --tree-filter 'rm filename' HEAD
201 -------------------------------------------------------
203 However, if the file is absent from the tree of some commit,
204 a simple `rm filename` will fail for that tree and commit.
205 Thus you may instead want to use `rm -f filename` as the script.
207 A significantly faster version:
209 --------------------------------------------------------------------------
210 git filter-branch --index-filter 'git rm --cached filename' HEAD
211 --------------------------------------------------------------------------
213 Now, you will get the rewritten history saved in HEAD.
215 To rewrite the repository to look as if `foodir/` had been its project
216 root, and discard all other history:
218 -------------------------------------------------------
219 git filter-branch --subdirectory-filter foodir -- --all
220 -------------------------------------------------------
222 Thus you can, e.g., turn a library subdirectory into a repository of
223 its own.  Note the `\--` that separates 'filter-branch' options from
224 revision options, and the `\--all` to rewrite all branches and tags.
226 To set a commit (which typically is at the tip of another
227 history) to be the parent of the current initial commit, in
228 order to paste the other history behind the current history:
230 -------------------------------------------------------------------
231 git filter-branch --parent-filter 'sed "s/^\$/-p <graft-id>/"' HEAD
232 -------------------------------------------------------------------
234 (if the parent string is empty - which happens when we are dealing with
235 the initial commit - add graftcommit as a parent).  Note that this assumes
236 history with a single root (that is, no merge without common ancestors
237 happened).  If this is not the case, use:
239 --------------------------------------------------------------------------
240 git filter-branch --parent-filter \
241         'test $GIT_COMMIT = <commit-id> && echo "-p <graft-id>" || cat' HEAD
242 --------------------------------------------------------------------------
244 or even simpler:
246 -----------------------------------------------
247 echo "$commit-id $graft-id" >> .git/info/grafts
248 git filter-branch $graft-id..HEAD
249 -----------------------------------------------
251 To remove commits authored by "Darl McBribe" from the history:
253 ------------------------------------------------------------------------------
254 git filter-branch --commit-filter '
255         if [ "$GIT_AUTHOR_NAME" = "Darl McBribe" ];
256         then
257                 skip_commit "$@";
258         else
259                 git commit-tree "$@";
260         fi' HEAD
261 ------------------------------------------------------------------------------
263 The function 'skip_commit' is defined as follows:
265 --------------------------
266 skip_commit()
268         shift;
269         while [ -n "$1" ];
270         do
271                 shift;
272                 map "$1";
273                 shift;
274         done;
276 --------------------------
278 The shift magic first throws away the tree id and then the -p
279 parameters.  Note that this handles merges properly! In case Darl
280 committed a merge between P1 and P2, it will be propagated properly
281 and all children of the merge will become merge commits with P1,P2
282 as their parents instead of the merge commit.
284 You can rewrite the commit log messages using `--msg-filter`.  For
285 example, 'git-svn-id' strings in a repository created by 'git-svn' can
286 be removed this way:
288 -------------------------------------------------------
289 git filter-branch --msg-filter '
290         sed -e "/^git-svn-id:/d"
292 -------------------------------------------------------
294 To restrict rewriting to only part of the history, specify a revision
295 range in addition to the new branch name.  The new branch name will
296 point to the top-most revision that a 'git-rev-list' of this range
297 will print.
299 *NOTE* the changes introduced by the commits, and which are not reverted
300 by subsequent commits, will still be in the rewritten branch. If you want
301 to throw out _changes_ together with the commits, you should use the
302 interactive mode of 'git-rebase'.
305 Consider this history:
307 ------------------
308      D--E--F--G--H
309     /     /
310 A--B-----C
311 ------------------
313 To rewrite only commits D,E,F,G,H, but leave A, B and C alone, use:
315 --------------------------------
316 git filter-branch ... C..H
317 --------------------------------
319 To rewrite commits E,F,G,H, use one of these:
321 ----------------------------------------
322 git filter-branch ... C..H --not D
323 git filter-branch ... D..H --not C
324 ----------------------------------------
326 To move the whole tree into a subdirectory, or remove it from there:
328 ---------------------------------------------------------------
329 git filter-branch --index-filter \
330         'git ls-files -s | sed "s-\t-&newsubdir/-" |
331                 GIT_INDEX_FILE=$GIT_INDEX_FILE.new \
332                         git update-index --index-info &&
333          mv $GIT_INDEX_FILE.new $GIT_INDEX_FILE' HEAD
334 ---------------------------------------------------------------
337 Author
338 ------
339 Written by Petr "Pasky" Baudis <pasky@suse.cz>,
340 and the git list <git@vger.kernel.org>
342 Documentation
343 --------------
344 Documentation by Petr Baudis and the git list.
348 Part of the linkgit:git[1] suite