Merge commit 'git/master'
[git/git-bigfiles.git] / Documentation / git-filter-branch.txt
blob237f85e7673e90b214550e051d92c4cb0865413a
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.  Frequently used with `git rm \--cached
95         \--ignore-unmatch ...`, see EXAMPLES below.  For hairy
96         cases, see linkgit:git-update-index[1].
98 --parent-filter <command>::
99         This is the filter for rewriting the commit's parent list.
100         It will receive the parent string on stdin and shall output
101         the new parent string on stdout.  The parent string is in
102         the format described in linkgit:git-commit-tree[1]: empty for
103         the initial commit, "-p parent" for a normal commit and
104         "-p parent1 -p parent2 -p parent3 ..." for a merge commit.
106 --msg-filter <command>::
107         This is the filter for rewriting the commit messages.
108         The argument is evaluated in the shell with the original
109         commit message on standard input; its standard output is
110         used as the new commit message.
112 --commit-filter <command>::
113         This is the filter for performing the commit.
114         If this filter is specified, it will be called instead of the
115         'git-commit-tree' command, with arguments of the form
116         "<TREE_ID> [-p <PARENT_COMMIT_ID>]..." and the log message on
117         stdin.  The commit id is expected on stdout.
119 As a special extension, the commit filter may emit multiple
120 commit ids; in that case, the rewritten children of the original commit will
121 have all of them as parents.
123 You can use the 'map' convenience function in this filter, and other
124 convenience functions, too.  For example, calling 'skip_commit "$@"'
125 will leave out the current commit (but not its changes! If you want
126 that, use 'git-rebase' instead).
128 You can also use the 'git_commit_non_empty_tree "$@"' instead of
129 'git commit-tree "$@"' if you don't wish to keep commits with a single parent
130 and that makes no change to the tree.
132 --tag-name-filter <command>::
133         This is the filter for rewriting tag names. When passed,
134         it will be called for every tag ref that points to a rewritten
135         object (or to a tag object which points to a rewritten object).
136         The original tag name is passed via standard input, and the new
137         tag name is expected on standard output.
139 The original tags are not deleted, but can be overwritten;
140 use "--tag-name-filter cat" to simply update the tags.  In this
141 case, be very careful and make sure you have the old tags
142 backed up in case the conversion has run afoul.
144 Nearly proper rewriting of tag objects is supported. If the tag has
145 a message attached, a new tag object will be created with the same message,
146 author, and timestamp. If the tag has a signature attached, the
147 signature will be stripped. It is by definition impossible to preserve
148 signatures. The reason this is "nearly" proper, is because ideally if
149 the tag did not change (points to the same object, has the same name, etc.)
150 it should retain any signature. That is not the case, signatures will always
151 be removed, buyer beware. There is also no support for changing the
152 author or timestamp (or the tag message for that matter). Tags which point
153 to other tags will be rewritten to point to the underlying commit.
155 --subdirectory-filter <directory>::
156         Only look at the history which touches the given subdirectory.
157         The result will contain that directory (and only that) as its
158         project root.
160 --prune-empty::
161         Some kind of filters will generate empty commits, that left the tree
162         untouched.  This switch allow git-filter-branch to ignore such
163         commits.  Though, this switch only applies for commits that have one
164         and only one parent, it will hence keep merges points. Also, this
165         option is not compatible with the use of '--commit-filter'. Though you
166         just need to use the function 'git_commit_non_empty_tree "$@"' instead
167         of the 'git commit-tree "$@"' idiom in your commit filter to make that
168         happen.
170 --original <namespace>::
171         Use this option to set the namespace where the original commits
172         will be stored. The default value is 'refs/original'.
174 -d <directory>::
175         Use this option to set the path to the temporary directory used for
176         rewriting.  When applying a tree filter, the command needs to
177         temporarily check out the tree to some directory, which may consume
178         considerable space in case of large projects.  By default it
179         does this in the '.git-rewrite/' directory but you can override
180         that choice by this parameter.
182 -f::
183 --force::
184         'git-filter-branch' refuses to start with an existing temporary
185         directory or when there are already refs starting with
186         'refs/original/', unless forced.
188 <rev-list options>...::
189         Arguments for 'git-rev-list'.  All positive refs included by
190         these options are rewritten.  You may also specify options
191         such as '--all', but you must use '--' to separate them from
192         the 'git-filter-branch' options.
195 Examples
196 --------
198 Suppose you want to remove a file (containing confidential information
199 or copyright violation) from all commits:
201 -------------------------------------------------------
202 git filter-branch --tree-filter 'rm filename' HEAD
203 -------------------------------------------------------
205 However, if the file is absent from the tree of some commit,
206 a simple `rm filename` will fail for that tree and commit.
207 Thus you may instead want to use `rm -f filename` as the script.
209 Using `\--index-filter` with 'git-rm' yields a significantly faster
210 version.  Like with using `rm filename`, `git rm --cached filename`
211 will fail if the file is absent from the tree of a commit.  If you
212 want to "completely forget" a file, it does not matter when it entered
213 history, so we also add `\--ignore-unmatch`:
215 --------------------------------------------------------------------------
216 git filter-branch --index-filter 'git rm --cached --ignore-unmatch filename' HEAD
217 --------------------------------------------------------------------------
219 Now, you will get the rewritten history saved in HEAD.
221 To rewrite the repository to look as if `foodir/` had been its project
222 root, and discard all other history:
224 -------------------------------------------------------
225 git filter-branch --subdirectory-filter foodir -- --all
226 -------------------------------------------------------
228 Thus you can, e.g., turn a library subdirectory into a repository of
229 its own.  Note the `\--` that separates 'filter-branch' options from
230 revision options, and the `\--all` to rewrite all branches and tags.
232 To set a commit (which typically is at the tip of another
233 history) to be the parent of the current initial commit, in
234 order to paste the other history behind the current history:
236 -------------------------------------------------------------------
237 git filter-branch --parent-filter 'sed "s/^\$/-p <graft-id>/"' HEAD
238 -------------------------------------------------------------------
240 (if the parent string is empty - which happens when we are dealing with
241 the initial commit - add graftcommit as a parent).  Note that this assumes
242 history with a single root (that is, no merge without common ancestors
243 happened).  If this is not the case, use:
245 --------------------------------------------------------------------------
246 git filter-branch --parent-filter \
247         'test $GIT_COMMIT = <commit-id> && echo "-p <graft-id>" || cat' HEAD
248 --------------------------------------------------------------------------
250 or even simpler:
252 -----------------------------------------------
253 echo "$commit-id $graft-id" >> .git/info/grafts
254 git filter-branch $graft-id..HEAD
255 -----------------------------------------------
257 To remove commits authored by "Darl McBribe" from the history:
259 ------------------------------------------------------------------------------
260 git filter-branch --commit-filter '
261         if [ "$GIT_AUTHOR_NAME" = "Darl McBribe" ];
262         then
263                 skip_commit "$@";
264         else
265                 git commit-tree "$@";
266         fi' HEAD
267 ------------------------------------------------------------------------------
269 The function 'skip_commit' is defined as follows:
271 --------------------------
272 skip_commit()
274         shift;
275         while [ -n "$1" ];
276         do
277                 shift;
278                 map "$1";
279                 shift;
280         done;
282 --------------------------
284 The shift magic first throws away the tree id and then the -p
285 parameters.  Note that this handles merges properly! In case Darl
286 committed a merge between P1 and P2, it will be propagated properly
287 and all children of the merge will become merge commits with P1,P2
288 as their parents instead of the merge commit.
290 You can rewrite the commit log messages using `--msg-filter`.  For
291 example, 'git-svn-id' strings in a repository created by 'git-svn' can
292 be removed this way:
294 -------------------------------------------------------
295 git filter-branch --msg-filter '
296         sed -e "/^git-svn-id:/d"
298 -------------------------------------------------------
300 To restrict rewriting to only part of the history, specify a revision
301 range in addition to the new branch name.  The new branch name will
302 point to the top-most revision that a 'git-rev-list' of this range
303 will print.
305 *NOTE* the changes introduced by the commits, and which are not reverted
306 by subsequent commits, will still be in the rewritten branch. If you want
307 to throw out _changes_ together with the commits, you should use the
308 interactive mode of 'git-rebase'.
311 Consider this history:
313 ------------------
314      D--E--F--G--H
315     /     /
316 A--B-----C
317 ------------------
319 To rewrite only commits D,E,F,G,H, but leave A, B and C alone, use:
321 --------------------------------
322 git filter-branch ... C..H
323 --------------------------------
325 To rewrite commits E,F,G,H, use one of these:
327 ----------------------------------------
328 git filter-branch ... C..H --not D
329 git filter-branch ... D..H --not C
330 ----------------------------------------
332 To move the whole tree into a subdirectory, or remove it from there:
334 ---------------------------------------------------------------
335 git filter-branch --index-filter \
336         'git ls-files -s | sed "s-\t-&newsubdir/-" |
337                 GIT_INDEX_FILE=$GIT_INDEX_FILE.new \
338                         git update-index --index-info &&
339          mv $GIT_INDEX_FILE.new $GIT_INDEX_FILE' HEAD
340 ---------------------------------------------------------------
344 Checklist for Shrinking a Repository
345 ------------------------------------
347 git-filter-branch is often used to get rid of a subset of files,
348 usually with some combination of `\--index-filter` and
349 `\--subdirectory-filter`.  People expect the resulting repository to
350 be smaller than the original, but you need a few more steps to
351 actually make it smaller, because git tries hard not to lose your
352 objects until you tell it to.  First make sure that:
354 * You really removed all variants of a filename, if a blob was moved
355   over its lifetime.  `git log \--name-only \--follow \--all \--
356   filename` can help you find renames.
358 * You really filtered all refs: use `\--tag-name-filter cat \--
359   \--all` when calling git-filter-branch.
361 Then there are two ways to get a smaller repository.  A safer way is
362 to clone, that keeps your original intact.
364 * Clone it with `git clone +++file:///path/to/repo+++`.  The clone
365   will not have the removed objects.  See linkgit:git-clone[1].  (Note
366   that cloning with a plain path just hardlinks everything!)
368 If you really don't want to clone it, for whatever reasons, check the
369 following points instead (in this order).  This is a very destructive
370 approach, so *make a backup* or go back to cloning it.  You have been
371 warned.
373 * Remove the original refs backed up by git-filter-branch: say `git
374   for-each-ref \--format="%(refname)" refs/original/ | xargs -n 1 git
375   update-ref -d`.
377 * Expire all reflogs with `git reflog expire \--expire=now \--all`.
379 * Garbage collect all unreferenced objects with `git gc \--prune=now`
380   (or if your git-gc is not new enough to support arguments to
381   `\--prune`, use `git repack -ad; git prune` instead).
384 Author
385 ------
386 Written by Petr "Pasky" Baudis <pasky@suse.cz>,
387 and the git list <git@vger.kernel.org>
389 Documentation
390 --------------
391 Documentation by Petr Baudis and the git list.
395 Part of the linkgit:git[1] suite