--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 the section called
'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 git-commit-tree(1)
for details).
--tree-filter <command>
This is the filter for rewriting the tree and its contents.
The argument is evaluated in shell with the working directory
set to the root of the checked out tree. The new tree is then
used as-is (new files are auto-added, disappeared files are
auto-removed - neither .gitignore files nor any other ignore
rules HAVE ANY EFFECT!).
--index-filter <command>
This is the filter for rewriting the index. It is similar to
the tree filter but does not check out the tree, which makes
it much faster. Frequently used with git rm --cached
--ignore-unmatch ..., see EXAMPLES below. For hairy cases,
see git-update-index(1).
--parent-filter <command>
This is the filter for rewriting the commit's parent list. It
will receive the parent string on stdin and shall output the
new parent string on stdout. The parent string is in the
format described in git-commit-tree(1): empty for the initial
commit, "-p parent" for a normal commit and "-p parent1 -p
parent2 -p parent3 ..." for a merge commit.
--msg-filter <command>
This is the filter for rewriting the commit messages. The
argument is evaluated in the shell with the original commit
message on standard input; its standard output is used as the
new commit message.
--commit-filter <command>
This is the filter for performing the commit. If this filter
is specified, it will be called instead of the git
commit-tree command, with arguments of the form "<TREE_ID>
[(-p <PARENT_COMMIT_ID>)...]" and the log message on stdin.
The commit id is expected on stdout.
As a special extension, the commit filter may emit multiple
commit ids; in that case, the rewritten children of the
original commit will have all of them as parents.
You can use the map convenience function in this filter, and
other convenience functions, too. For example, calling
skip_commit "$@" will leave out the current commit (but not
its changes! If you want that, use git rebase instead).
You can also use the git_commit_non_empty_tree "$@" instead
of git commit-tree "$@" if you don't wish to keep commits
with a single parent and that makes no change to the tree.
--tag-name-filter <command>
This is the filter for rewriting tag names. When passed, it
will be called for every tag ref that points to a rewritten
object (or to a tag object which points to a rewritten
object). The original tag name is passed via standard input,
and the new tag name is expected on standard output.
The original tags are not deleted, but can be overwritten;
use "--tag-name-filter cat" to simply update the tags. In
this case, be very careful and make sure you have the old
tags backed up in case the conversion has run afoul.
Nearly proper rewriting of tag objects is supported. If the
tag has a message attached, a new tag object will be created
with the same message, author, and timestamp. If the tag has
a signature attached, the signature will be stripped. It is
by definition impossible to preserve signatures. The reason
this is "nearly" proper, is because ideally if the tag did
not change (points to the same object, has the same name,
etc.) it should retain any signature. That is not the case,
signatures will always be removed, buyer beware. There is
also no support for changing the 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.
--prune-empty
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 will be stored. The default value is refs/original.
-d <directory>
Use this option to set the path to the temporary directory
used for rewriting. When applying a tree filter, the command
needs to temporarily check out the tree to some directory,
which may consume considerable space in case of large
projects. By default it does this in the .git-rewrite/
directory but you can override that choice by this parameter.
-f, --force
git filter-branch refuses to start with an existing temporary
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 the
git filter-branch options. Implies the section called 'Remap
to ancestor'.
Remap to ancestor
By using git-rev-list(1) arguments, e.g., path limiters, you can
limit the set of revisions which get rewritten. However, positive
refs on the command line are distinguished: we don't let them be
excluded by such limiters. For this purpose, they are instead
rewritten to point at the nearest ancestor that was not excluded.
