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 <<Remap_to_ancestor>>.


[[Remap_to_ancestor]]
Remap to ancestor
~~~~~~~~~~~~~~~~~

By using linkgit: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.


EXIT STATUS
-----------

On success, the exit status is `0`.  If the filter can't find any commits to
rewrite, the exit status is `2`.  On any other error, the exit status may be
any other non-zero value.


EXAMPLES
--------

Suppose you want to remove a file (containing confidential information
or copyright violation) from all commits:

-------------------------------------------------------
git filter-branch --tree-filter 'rm filename' HEAD
-------------------------------------------------------

However, if the file is absent from the tree of some commit,
a simple `rm filename` will fail for that tree and commit.
Thus you may instead want to use `rm -f filename` as the script.

Using `--index-filter` with 'git rm' yields a significantly faster
version.  Like with using `rm filename`, `git rm --cached filename`
will fail if the file is absent from the tree of a commit.  If you
want to "completely forget" a file, it does not matter when it entered
history, so we also add `--ignore-unmatch`:

--------------------------------------------------------------------------
git filter-branch --index-filter 'git rm --cached --ignore-unmatch filename' HEAD
--------------------------------------------------------------------------

Now, you will get the rewritten history saved in HEAD.

To rewrite the repository to look as if `foodir/` had been its project
root, and discard all other history:

-------------------------------------------------------
git filter-branch --subdirectory-filter foodir -- --all
-------------------------------------------------------

Thus you can, e.g., turn a library subdirectory into a repository of
its own.  Note the `--` that separates 'filter-branch' options from
revision options, and the `--all` to rewrite all branches and tags.

To set a commit (which typically is at the tip of another
history) to be the parent of the current initial commit, in
order to paste the other history behind the current history:

-------------------------------------------------------------------
git filter-branch --parent-filter 'sed "s/^\$/-p <graft-id>/"' HEAD
-------------------------------------------------------------------

(if the parent string is empty - which happens when we are dealing with
the initial commit - add graftcommit as a parent).  Note that this assumes
history with a single root (that is, no merge without common ancestors
happened).  If this is not the case, use:

--------------------------------------------------------------------------