SYNOPSIS
--------
[verse]
-'git filter-branch' [--env-filter <command>] [--tree-filter <command>]
+'git filter-branch' [--setup <command>] [--subdirectory-filter <directory>]
+ [--env-filter <command>] [--tree-filter <command>]
[--index-filter <command>] [--parent-filter <command>]
[--msg-filter <command>] [--commit-filter <command>]
- [--tag-name-filter <command>] [--subdirectory-filter <directory>]
- [--prune-empty]
+ [--tag-name-filter <command>] [--prune-empty]
[--original <namespace>] [-d <directory>] [-f | --force]
- [--] [<rev-list options>...]
+ [--state-branch <branch>] [--] [<rev-list options>...]
DESCRIPTION
-----------
Note that since this operation is very I/O expensive, it might
be a good idea to redirect the temporary directory off-disk with the
-'-d' option, e.g. on tmpfs. Reportedly the speedup is very noticeable.
+`-d` option, e.g. on tmpfs. Reportedly the speedup is very noticeable.
Filters
The filters are applied in the order as listed below. The <command>
argument is always evaluated in the shell context using the 'eval' command
(with the notable exception of the commit filter, for technical reasons).
-Prior to that, the $GIT_COMMIT environment variable will be set to contain
+Prior to that, the `$GIT_COMMIT` environment variable will be set to contain
the id of the commit being rewritten. Also, GIT_AUTHOR_NAME,
GIT_AUTHOR_EMAIL, GIT_AUTHOR_DATE, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL,
and GIT_COMMITTER_DATE are taken from the current commit and exported to
OPTIONS
-------
+--setup <command>::
+ This is not a real filter executed for each commit but a one
+ time setup just before the loop. Therefore no commit-specific
+ variables are defined yet. Functions or variables defined here
+ can be used or modified in the following filter steps except
+ the commit filter, for technical reasons.
+
+--subdirectory-filter <directory>::
+ Only look at the history which touches the given subdirectory.
+ The result will contain that directory (and only that) as its
+ project root. Implies <<Remap_to_ancestor>>.
+
--env-filter <command>::
This filter may be used if you only need to modify the environment
in which the commit will be performed. Specifically, you might
want to rewrite the author/committer name/email/time environment
- variables (see linkgit:git-commit-tree[1] for details). Do not forget
- to re-export the variables.
+ variables (see linkgit:git-commit-tree[1] for details).
--tree-filter <command>::
This is the filter for rewriting the tree and its contents.
author or timestamp (or the tag message for that matter). Tags which point
to other tags will be rewritten to point to the underlying commit.
---subdirectory-filter <directory>::
- Only look at the history which touches the given subdirectory.
- The result will contain that directory (and only that) as its
- project root. Implies <<Remap_to_ancestor>>.
-
--prune-empty::
- Some kind of filters will generate empty commits, that left the tree
- untouched. This switch allow git-filter-branch to ignore such
- commits. Though, this switch only applies for commits that have one
- and only one parent, it will hence keep merges points. Also, this
- option is not compatible with the use of '--commit-filter'. Though you
- just need to use the function 'git_commit_non_empty_tree "$@"' instead
- of the `git commit-tree "$@"` idiom in your commit filter to make that
- happen.
+ Some filters will generate empty commits that leave the tree untouched.
+ This option instructs git-filter-branch to remove such commits if they
+ have exactly one or zero non-pruned parents; merge commits will
+ therefore remain intact. This option cannot be used together with
+ `--commit-filter`, though the same effect can be achieved by using the
+ provided `git_commit_non_empty_tree` function in a commit filter.
--original <namespace>::
Use this option to set the namespace where the original commits
directory or when there are already refs starting with
'refs/original/', unless forced.
+--state-branch <branch>::
+ This option will cause the mapping from old to new objects to
+ be loaded from named branch upon startup and saved as a new
+ commit to that branch upon exit, enabling incremental of large
+ trees. If '<branch>' does not exist it will be created.
+
<rev-list options>...::
Arguments for 'git rev-list'. All positive refs included by
these options are rewritten. You may also specify options
- such as '--all', but you must use '--' to separate them from
+ such as `--all`, but you must use `--` to separate them from
the 'git filter-branch' options. Implies <<Remap_to_ancestor>>.
if test "$GIT_AUTHOR_EMAIL" = "root@localhost"
then
GIT_AUTHOR_EMAIL=john@example.com
- export GIT_AUTHOR_EMAIL
fi
if test "$GIT_COMMITTER_EMAIL" = "root@localhost"
then
GIT_COMMITTER_EMAIL=john@example.com
- export GIT_COMMITTER_EMAIL
fi
' -- --all
--------------------------------------------------------