git-filter-branch(1)
====================

NAME
----
git-filter-branch - Rewrite branches

SYNOPSIS
--------
[verse]
'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>] [--prune-empty]
	[--original <namespace>] [-d <directory>] [-f | --force]
	[--state-branch <branch>] [--] [<rev-list-options>...]

WARNING
-------
'git filter-branch' has a plethora of pitfalls that can produce non-obvious
manglings of the intended history rewrite (and can leave you with little
time to investigate such problems since it has such abysmal performance).
These safety and performance issues cannot be backward compatibly fixed and
as such, its use is not recommended.  Please use an alternative history
filtering tool such as https://github.com/newren/git-filter-repo/[git
filter-repo].  If you still need to use 'git filter-branch', please
carefully read <<SAFETY>> (and <<PERFORMANCE>>) to learn about the land
mines of filter-branch, and then vigilantly avoid as many of the hazards
listed there as reasonably possible.

DESCRIPTION
-----------
Lets you rewrite Git revision history by rewriting the branches mentioned
in the <rev-list-options>, applying custom filters on each revision.
Those filters can modify each tree (e.g. removing a file or running
a perl rewrite on all files) or information about each commit.
Otherwise, all information (including original commit times or merge
information) will be preserved.

The command will only rewrite the _positive_ refs mentioned in the
command line (e.g. if you pass 'a..b', only 'b' will be rewritten).
If you specify no filters, the commits will be recommitted without any
changes, which would normally have no effect.  Nevertheless, this may be
useful in the future for compensating for some Git bugs or such,
therefore such a usage is permitted.

*NOTE*: This command honors `.git/info/grafts` file and refs in
the `refs/replace/` namespace.
If you have any grafts or replacement refs defined, running this command
will make them permanent.

*WARNING*! The rewritten history will have different object names for all
the objects and will not converge with the original branch.  You will not
be able to easily push and distribute the rewritten branch on top of the
original branch.  Please do not use this command if you do not know the
full implications, and avoid using it anyway, if a simple single commit
would suffice to fix your problem.  (See the "RECOVERING FROM UPSTREAM
REBASE" section in linkgit:git-rebase[1] for further information about
rewriting published history.)

Always verify that the rewritten version is correct: The original refs,
if different from the rewritten ones, will be stored in the namespace
'refs/original/'.

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.


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
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
the environment, in order to affect the author and committer identities of
the replacement commit created by linkgit:git-commit-tree[1] after the
filters have run.

If any evaluation of <command> returns a non-zero exit status, the whole
operation will be aborted.

A 'map' function is available that takes an "original sha1 id" argument
and outputs a "rewritten sha1 id"