Move setup_diff_pager to libgit.a
[git/jnareb-git.git] / Documentation / git-filter-branch.txt
1 git-filter-branch(1)
2 ====================
5 ----
6 git-filter-branch - Rewrite branches
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         [--prune-empty]
16         [--original <namespace>] [-d <directory>] [-f | --force]
17         [--] [<rev-list options>...]
20 -----------
21 Lets you rewrite git revision history by rewriting the branches mentioned
22 in the <rev-list options>, applying custom filters on each revision.
23 Those filters can modify each tree (e.g. removing a file or running
24 a perl rewrite on all files) or information about each commit.
25 Otherwise, all information (including original commit times or merge
26 information) will be preserved.
28 The command will only rewrite the _positive_ refs mentioned in the
29 command line (e.g. if you pass 'a..b', only 'b' will be rewritten).
30 If you specify no filters, the commits will be recommitted without any
31 changes, which would normally have no effect.  Nevertheless, this may be
32 useful in the future for compensating for some git bugs or such,
33 therefore such a usage is permitted.
35 *NOTE*: This command honors `.git/info/grafts` file and refs in
36 the `refs/replace/` namespace.
37 If you have any grafts or replacement refs defined, running this command
38 will make them permanent.
40 *WARNING*! The rewritten history will have different object names for all
41 the objects and will not converge with the original branch.  You will not
42 be able to easily push and distribute the rewritten branch on top of the
43 original branch.  Please do not use this command if you do not know the
44 full implications, and avoid using it anyway, if a simple single commit
45 would suffice to fix your problem.  (See the "RECOVERING FROM UPSTREAM
46 REBASE" section in linkgit:git-rebase[1] for further information about
47 rewriting published history.)
49 Always verify that the rewritten version is correct: The original refs,
50 if different from the rewritten ones, will be stored in the namespace
51 'refs/original/'.
53 Note that since this operation is very I/O expensive, it might
54 be a good idea to redirect the temporary directory off-disk with the
55 '-d' option, e.g. on tmpfs.  Reportedly the speedup is very noticeable.
58 Filters
59 ~~~~~~~
61 The filters are applied in the order as listed below.  The <command>
62 argument is always evaluated in the shell context using the 'eval' command
63 (with the notable exception of the commit filter, for technical reasons).
64 Prior to that, the $GIT_COMMIT environment variable will be set to contain
65 the id of the commit being rewritten.  Also, GIT_AUTHOR_NAME,
67 and GIT_COMMITTER_DATE are set according to the current commit.  The values
68 of these variables after the filters have run, are used for the new commit.
69 If any evaluation of <command> returns a non-zero exit status, the whole
70 operation will be aborted.
72 A 'map' function is available that takes an "original sha1 id" argument
73 and outputs a "rewritten sha1 id" if the commit has been already
74 rewritten, and "original sha1 id" otherwise; the 'map' function can
75 return several ids on separate lines if your commit filter emitted
76 multiple commits.
80 -------
82 --env-filter <command>::
83         This filter may be used if you only need to modify the environment
84         in which the commit will be performed.  Specifically, you might
85         want to rewrite the author/committer name/email/time environment
86         variables (see linkgit:git-commit-tree[1] for details).  Do not forget
87         to re-export the variables.
89 --tree-filter <command>::
90         This is the filter for rewriting the tree and its contents.
91         The argument is evaluated in shell with the working
92         directory set to the root of the checked out tree.  The new tree
93         is then used as-is (new files are auto-added, disappeared files
94         are auto-removed - neither .gitignore files nor any other ignore
95         rules *HAVE ANY EFFECT*!).
97 --index-filter <command>::
98         This is the filter for rewriting the index.  It is similar to the
99         tree filter but does not check out the tree, which makes it much
100         faster.  Frequently used with `git rm --cached
101         --ignore-unmatch ...`, see EXAMPLES below.  For hairy
102         cases, see linkgit:git-update-index[1].
104 --parent-filter <command>::
105         This is the filter for rewriting the commit's parent list.
106         It will receive the parent string on stdin and shall output
107         the new parent string on stdout.  The parent string is in
108         the format described in linkgit:git-commit-tree[1]: empty for
109         the initial commit, "-p parent" for a normal commit and
110         "-p parent1 -p parent2 -p parent3 ..." for a merge commit.
112 --msg-filter <command>::
113         This is the filter for rewriting the commit messages.
114         The argument is evaluated in the shell with the original
115         commit message on standard input; its standard output is
116         used as the new commit message.
118 --commit-filter <command>::
119         This is the filter for performing the commit.
120         If this filter is specified, it will be called instead of the
121         'git commit-tree' command, with arguments of the form
122         "<TREE_ID> [(-p <PARENT_COMMIT_ID>)...]" and the log message on
123         stdin.  The commit id is expected on stdout.
125 As a special extension, the commit filter may emit multiple
126 commit ids; in that case, the rewritten children of the original commit will
127 have all of them as parents.
129 You can use the 'map' convenience function in this filter, and other
130 convenience functions, too.  For example, calling 'skip_commit "$@"'
131 will leave out the current commit (but not its changes! If you want
132 that, use 'git rebase' instead).
134 You can also use the `git_commit_non_empty_tree "$@"` instead of
135 `git commit-tree "$@"` if you don't wish to keep commits with a single parent
136 and that makes no change to the tree.
138 --tag-name-filter <command>::
139         This is the filter for rewriting tag names. When passed,
140         it will be called for every tag ref that points to a rewritten
141         object (or to a tag object which points to a rewritten object).
142         The original tag name is passed via standard input, and the new
143         tag name is expected on standard output.
145 The original tags are not deleted, but can be overwritten;
146 use "--tag-name-filter cat" to simply update the tags.  In this
147 case, be very careful and make sure you have the old tags
148 backed up in case the conversion has run afoul.
150 Nearly proper rewriting of tag objects is supported. If the tag has
151 a message attached, a new tag object will be created with the same message,
152 author, and timestamp. If the tag has a signature attached, the
153 signature will be stripped. It is by definition impossible to preserve
154 signatures. The reason this is "nearly" proper, is because ideally if
155 the tag did not change (points to the same object, has the same name, etc.)
156 it should retain any signature. That is not the case, signatures will always
157 be removed, buyer beware. There is also no support for changing the
158 author or timestamp (or the tag message for that matter). Tags which point
159 to other tags will be rewritten to point to the underlying commit.
161 --subdirectory-filter <directory>::
162         Only look at the history which touches the given subdirectory.
163         The result will contain that directory (and only that) as its
164         project root. Implies <<Remap_to_ancestor>>.
166 --prune-empty::
167         Some kind of filters will generate empty commits, that left the tree
168         untouched.  This switch allow git-filter-branch to ignore such
169         commits.  Though, this switch only applies for commits that have one
170         and only one parent, it will hence keep merges points. Also, this
171         option is not compatible with the use of '--commit-filter'. Though you
172         just need to use the function 'git_commit_non_empty_tree "$@"' instead
173         of the `git commit-tree "$@"` idiom in your commit filter to make that
174         happen.
176 --original <namespace>::
177         Use this option to set the namespace where the original commits
178         will be stored. The default value is 'refs/original'.
180 -d <directory>::
181         Use this option to set the path to the temporary directory used for
182         rewriting.  When applying a tree filter, the command needs to
183         temporarily check out the tree to some directory, which may consume
184         considerable space in case of large projects.  By default it
185         does this in the '.git-rewrite/' directory but you can override
186         that choice by this parameter.
188 -f::
189 --force::
190         'git filter-branch' refuses to start with an existing temporary
191         directory or when there are already refs starting with
192         'refs/original/', unless forced.
194 <rev-list options>...::
195         Arguments for 'git rev-list'.  All positive refs included by
196         these options are rewritten.  You may also specify options
197         such as '--all', but you must use '--' to separate them from
198         the 'git filter-branch' options. Implies <<Remap_to_ancestor>>.
201 [[Remap_to_ancestor]]
202 Remap to ancestor
203 ~~~~~~~~~~~~~~~~~
205 By using linkgit:rev-list[1] arguments, e.g., path limiters, you can limit the
206 set of revisions which get rewritten. However, positive refs on the command
207 line are distinguished: we don't let them be excluded by such limiters. For
208 this purpose, they are instead rewritten to point at the nearest ancestor that
209 was not excluded.
212 Examples
213 --------
215 Suppose you want to remove a file (containing confidential information
216 or copyright violation) from all commits:
218 -------------------------------------------------------
219 git filter-branch --tree-filter 'rm filename' HEAD
220 -------------------------------------------------------
222 However, if the file is absent from the tree of some commit,
223 a simple `rm filename` will fail for that tree and commit.
224 Thus you may instead want to use `rm -f filename` as the script.
226 Using `--index-filter` with 'git rm' yields a significantly faster
227 version.  Like with using `rm filename`, `git rm --cached filename`
228 will fail if the file is absent from the tree of a commit.  If you
229 want to "completely forget" a file, it does not matter when it entered
230 history, so we also add `--ignore-unmatch`:
232 --------------------------------------------------------------------------
233 git filter-branch --index-filter 'git rm --cached --ignore-unmatch filename' HEAD
234 --------------------------------------------------------------------------
236 Now, you will get the rewritten history saved in HEAD.
238 To rewrite the repository to look as if `foodir/` had been its project
239 root, and discard all other history:
241 -------------------------------------------------------
242 git filter-branch --subdirectory-filter foodir -- --all
243 -------------------------------------------------------
245 Thus you can, e.g., turn a library subdirectory into a repository of
246 its own.  Note the `--` that separates 'filter-branch' options from
247 revision options, and the `--all` to rewrite all branches and tags.
249 To set a commit (which typically is at the tip of another
250 history) to be the parent of the current initial commit, in
251 order to paste the other history behind the current history:
253 -------------------------------------------------------------------
254 git filter-branch --parent-filter 'sed "s/^\$/-p <graft-id>/"' HEAD
255 -------------------------------------------------------------------
257 (if the parent string is empty - which happens when we are dealing with
258 the initial commit - add graftcommit as a parent).  Note that this assumes
259 history with a single root (that is, no merge without common ancestors
260 happened).  If this is not the case, use:
262 --------------------------------------------------------------------------
263 git filter-branch --parent-filter \
264         'test $GIT_COMMIT = <commit-id> && echo "-p <graft-id>" || cat' HEAD
265 --------------------------------------------------------------------------
267 or even simpler:
269 -----------------------------------------------
270 echo "$commit-id $graft-id" >> .git/info/grafts
271 git filter-branch $graft-id..HEAD
272 -----------------------------------------------
274 To remove commits authored by "Darl McBribe" from the history:
276 ------------------------------------------------------------------------------
277 git filter-branch --commit-filter '
278         if [ "$GIT_AUTHOR_NAME" = "Darl McBribe" ];
279         then
280                 skip_commit "$@";
281         else
282                 git commit-tree "$@";
283         fi' HEAD
284 ------------------------------------------------------------------------------
286 The function 'skip_commit' is defined as follows:
288 --------------------------
289 skip_commit()
291         shift;
292         while [ -n "$1" ];
293         do
294                 shift;
295                 map "$1";
296                 shift;
297         done;
299 --------------------------
301 The shift magic first throws away the tree id and then the -p
302 parameters.  Note that this handles merges properly! In case Darl
303 committed a merge between P1 and P2, it will be propagated properly
304 and all children of the merge will become merge commits with P1,P2
305 as their parents instead of the merge commit.
307 *NOTE* the changes introduced by the commits, and which are not reverted
308 by subsequent commits, will still be in the rewritten branch. If you want
309 to throw out _changes_ together with the commits, you should use the
310 interactive mode of 'git rebase'.
312 You can rewrite the commit log messages using `--msg-filter`.  For
313 example, 'git svn-id' strings in a repository created by 'git svn' can
314 be removed this way:
316 -------------------------------------------------------
317 git filter-branch --msg-filter '
318         sed -e "/^git-svn-id:/d"
320 -------------------------------------------------------
322 If you need to add 'Acked-by' lines to, say, the last 10 commits (none
323 of which is a merge), use this command:
325 --------------------------------------------------------
326 git filter-branch --msg-filter '
327         cat &&
328         echo "Acked-by: Bugs Bunny <>"
329 ' HEAD~10..HEAD
330 --------------------------------------------------------
332 To restrict rewriting to only part of the history, specify a revision
333 range in addition to the new branch name.  The new branch name will
334 point to the top-most revision that a 'git rev-list' of this range
335 will print.
337 Consider this history:
339 ------------------
340      D--E--F--G--H
341     /     /
342 A--B-----C
343 ------------------
345 To rewrite only commits D,E,F,G,H, but leave A, B and C alone, use:
347 --------------------------------
348 git filter-branch ... C..H
349 --------------------------------
351 To rewrite commits E,F,G,H, use one of these:
353 ----------------------------------------
354 git filter-branch ... C..H --not D
355 git filter-branch ... D..H --not C
356 ----------------------------------------
358 To move the whole tree into a subdirectory, or remove it from there:
360 ---------------------------------------------------------------
361 git filter-branch --index-filter \
362         'git ls-files -s | sed "s-\t\"*-&newsubdir/-" |
363                 GIT_INDEX_FILE=$ \
364                         git update-index --index-info &&
365          mv "$" "$GIT_INDEX_FILE"' HEAD
366 ---------------------------------------------------------------
370 Checklist for Shrinking a Repository
371 ------------------------------------
373 git-filter-branch is often used to get rid of a subset of files,
374 usually with some combination of `--index-filter` and
375 `--subdirectory-filter`.  People expect the resulting repository to
376 be smaller than the original, but you need a few more steps to
377 actually make it smaller, because git tries hard not to lose your
378 objects until you tell it to.  First make sure that:
380 * You really removed all variants of a filename, if a blob was moved
381   over its lifetime.  `git log --name-only --follow --all -- filename`
382   can help you find renames.
384 * You really filtered all refs: use `--tag-name-filter cat -- --all`
385   when calling git-filter-branch.
387 Then there are two ways to get a smaller repository.  A safer way is
388 to clone, that keeps your original intact.
390 * Clone it with `git clone file:///path/to/repo`.  The clone
391   will not have the removed objects.  See linkgit:git-clone[1].  (Note
392   that cloning with a plain path just hardlinks everything!)
394 If you really don't want to clone it, for whatever reasons, check the
395 following points instead (in this order).  This is a very destructive
396 approach, so *make a backup* or go back to cloning it.  You have been
397 warned.
399 * Remove the original refs backed up by git-filter-branch: say `git
400   for-each-ref --format="%(refname)" refs/original/ | xargs -n 1 git
401   update-ref -d`.
403 * Expire all reflogs with `git reflog expire --expire=now --all`.
405 * Garbage collect all unreferenced objects with `git gc --prune=now`
406   (or if your git-gc is not new enough to support arguments to
407   `--prune`, use `git repack -ad; git prune` instead).
411 Part of the linkgit:git[1] suite