Documentation / git-filter-branch.txton commit Fix misspelling of 'suppress' in docs (2be7fcb)
   1git-filter-branch(1)
   2====================
   3
   4NAME
   5----
   6git-filter-branch - Rewrite branches
   7
   8SYNOPSIS
   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        [-d <directory>] [-f | --force] [<rev-list options>...]
  16
  17DESCRIPTION
  18-----------
  19Lets you rewrite git revision history by creating a new branch from
  20your current branch, applying custom filters on each revision.
  21Those filters can modify each tree (e.g. removing a file or running
  22a perl rewrite on all files) or information about each commit.
  23Otherwise, all information (including original commit times or merge
  24information) will be preserved.
  25
  26The command takes the new branch name as a mandatory argument and
  27the filters as optional arguments.  If you specify no filters, the
  28commits will be recommitted without any changes, which would normally
  29have no effect.  Nevertheless, this may be useful in the future for
  30compensating for some git bugs or such, therefore such a usage is
  31permitted.
  32
  33*WARNING*! The rewritten history will have different object names for all
  34the objects and will not converge with the original branch.  You will not
  35be able to easily push and distribute the rewritten branch on top of the
  36original branch.  Please do not use this command if you do not know the
  37full implications, and avoid using it anyway, if a simple single commit
  38would suffice to fix your problem.
  39
  40Always verify that the rewritten version is correct: The original refs,
  41if different from the rewritten ones, will be stored in the namespace
  42'refs/original/'.
  43
  44Note that since this operation is extensively I/O expensive, it might
  45be a good idea to redirect the temporary directory off-disk, e.g. on
  46tmpfs.  Reportedly the speedup is very noticeable.
  47
  48
  49Filters
  50~~~~~~~
  51
  52The filters are applied in the order as listed below.  The <command>
  53argument is always evaluated in shell using the 'eval' command (with the
  54notable exception of the commit filter, for technical reasons).
  55Prior to that, the $GIT_COMMIT environment variable will be set to contain
  56the id of the commit being rewritten.  Also, GIT_AUTHOR_NAME,
  57GIT_AUTHOR_EMAIL, GIT_AUTHOR_DATE, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL,
  58and GIT_COMMITTER_DATE are set according to the current commit.
  59
  60A 'map' function is available that takes an "original sha1 id" argument
  61and outputs a "rewritten sha1 id" if the commit has been already
  62rewritten, and "original sha1 id" otherwise; the 'map' function can
  63return several ids on separate lines if your commit filter emitted
  64multiple commits.
  65
  66
  67OPTIONS
  68-------
  69
  70--env-filter <command>::
  71        This is the filter for modifying the environment in which
  72        the commit will be performed.  Specifically, you might want
  73        to rewrite the author/committer name/email/time environment
  74        variables (see gitlink:git-commit[1] for details).  Do not forget
  75        to re-export the variables.
  76
  77--tree-filter <command>::
  78        This is the filter for rewriting the tree and its contents.
  79        The argument is evaluated in shell with the working
  80        directory set to the root of the checked out tree.  The new tree
  81        is then used as-is (new files are auto-added, disappeared files
  82        are auto-removed - neither .gitignore files nor any other ignore
  83        rules *HAVE ANY EFFECT*!).
  84
  85--index-filter <command>::
  86        This is the filter for rewriting the index.  It is similar to the
  87        tree filter but does not check out the tree, which makes it much
  88        faster.  For hairy cases, see gitlink:git-update-index[1].
  89
  90--parent-filter <command>::
  91        This is the filter for rewriting the commit's parent list.
  92        It will receive the parent string on stdin and shall output
  93        the new parent string on stdout.  The parent string is in
  94        a format accepted by gitlink:git-commit-tree[1]: empty for
  95        the initial commit, "-p parent" for a normal commit and
  96        "-p parent1 -p parent2 -p parent3 ..." for a merge commit.
  97
  98--msg-filter <command>::
  99        This is the filter for rewriting the commit messages.
 100        The argument is evaluated in the shell with the original
 101        commit message on standard input; its standard output is
 102        used as the new commit message.
 103
 104--commit-filter <command>::
 105        This is the filter for performing the commit.
 106        If this filter is specified, it will be called instead of the
 107        gitlink:git-commit-tree[1] command, with arguments of the form
 108        "<TREE_ID> [-p <PARENT_COMMIT_ID>]..." and the log message on
 109        stdin.  The commit id is expected on stdout.
 110+
 111As a special extension, the commit filter may emit multiple
 112commit ids; in that case, ancestors of the original commit will
 113have all of them as parents.
 114
 115--tag-name-filter <command>::
 116        This is the filter for rewriting tag names. When passed,
 117        it will be called for every tag ref that points to a rewritten
 118        object (or to a tag object which points to a rewritten object).
 119        The original tag name is passed via standard input, and the new
 120        tag name is expected on standard output.
 121+
 122The original tags are not deleted, but can be overwritten;
 123use "--tag-name-filter cat" to simply update the tags.  In this
 124case, be very careful and make sure you have the old tags
 125backed up in case the conversion has run afoul.
 126+
 127Note that there is currently no support for proper rewriting of
 128tag objects; in layman terms, if the tag has a message or signature
 129attached, the rewritten tag won't have it.  Sorry.  (It is by
 130definition impossible to preserve signatures at any rate.)
 131
 132--subdirectory-filter <directory>::
 133        Only look at the history which touches the given subdirectory.
 134        The result will contain that directory (and only that) as its
 135        project root.
 136
 137-d <directory>::
 138        Use this option to set the path to the temporary directory used for
 139        rewriting.  When applying a tree filter, the command needs to
 140        temporary checkout the tree to some directory, which may consume
 141        considerable space in case of large projects.  By default it
 142        does this in the '.git-rewrite/' directory but you can override
 143        that choice by this parameter.
 144
 145-f\|--force::
 146        `git filter-branch` refuses to start with an existing temporary
 147        directory or when there are already refs starting with
 148        'refs/original/', unless forced.
 149
 150<rev-list-options>::
 151        When options are given after the new branch name, they will
 152        be passed to gitlink:git-rev-list[1].  Only commits in the resulting
 153        output will be filtered, although the filtered commits can still
 154        reference parents which are outside of that set.
 155
 156
 157Examples
 158--------
 159
 160Suppose you want to remove a file (containing confidential information
 161or copyright violation) from all commits:
 162
 163-------------------------------------------------------
 164git filter-branch --tree-filter 'rm filename' HEAD
 165-------------------------------------------------------
 166
 167A significantly faster version:
 168
 169--------------------------------------------------------------------------
 170git filter-branch --index-filter 'git update-index --remove filename' HEAD
 171--------------------------------------------------------------------------
 172
 173Now, you will get the rewritten history saved in the branch 'newbranch'
 174(your current branch is left untouched).
 175
 176To set a commit (which typically is at the tip of another
 177history) to be the parent of the current initial commit, in
 178order to paste the other history behind the current history:
 179
 180-------------------------------------------------------------------
 181git filter-branch --parent-filter 'sed "s/^\$/-p <graft-id>/"' HEAD
 182-------------------------------------------------------------------
 183
 184(if the parent string is empty - therefore we are dealing with the
 185initial commit - add graftcommit as a parent).  Note that this assumes
 186history with a single root (that is, no merge without common ancestors
 187happened).  If this is not the case, use:
 188
 189--------------------------------------------------------------------------
 190git filter-branch --parent-filter \
 191        'cat; test $GIT_COMMIT = <commit-id> && echo "-p <graft-id>"' HEAD
 192--------------------------------------------------------------------------
 193
 194or even simpler:
 195
 196-----------------------------------------------
 197echo "$commit-id $graft-id" >> .git/info/grafts
 198git filter-branch $graft-id..HEAD
 199-----------------------------------------------
 200
 201To remove commits authored by "Darl McBribe" from the history:
 202
 203------------------------------------------------------------------------------
 204git filter-branch --commit-filter '
 205        if [ "$GIT_AUTHOR_NAME" = "Darl McBribe" ];
 206        then
 207                shift;
 208                while [ -n "$1" ];
 209                do
 210                        shift;
 211                        echo "$1";
 212                        shift;
 213                done;
 214        else
 215                git commit-tree "$@";
 216        fi' HEAD
 217------------------------------------------------------------------------------
 218
 219The shift magic first throws away the tree id and then the -p
 220parameters.  Note that this handles merges properly! In case Darl
 221committed a merge between P1 and P2, it will be propagated properly
 222and all children of the merge will become merge commits with P1,P2
 223as their parents instead of the merge commit.
 224
 225To restrict rewriting to only part of the history, specify a revision
 226range in addition to the new branch name.  The new branch name will
 227point to the top-most revision that a 'git rev-list' of this range
 228will print.
 229
 230Note that the changes introduced by the commits, and not reverted by
 231subsequent commits, will still be in the rewritten branch. If you want
 232to throw out _changes_ together with the commits, you should use the
 233interactive mode of gitlink:git-rebase[1].
 234
 235Consider this history:
 236
 237------------------
 238     D--E--F--G--H
 239    /     /
 240A--B-----C
 241------------------
 242
 243To rewrite only commits D,E,F,G,H, but leave A, B and C alone, use:
 244
 245--------------------------------
 246git filter-branch ... C..H
 247--------------------------------
 248
 249To rewrite commits E,F,G,H, use one of these:
 250
 251----------------------------------------
 252git filter-branch ... C..H --not D
 253git filter-branch ... D..H --not C
 254----------------------------------------
 255
 256To move the whole tree into a subdirectory, or remove it from there:
 257
 258---------------------------------------------------------------
 259git filter-branch --index-filter \
 260        'git ls-files -s | sed "s-\t-&newsubdir/-" |
 261                GIT_INDEX_FILE=$GIT_INDEX_FILE.new \
 262                        git update-index --index-info &&
 263         mv $GIT_INDEX_FILE.new $GIT_INDEX_FILE' HEAD
 264---------------------------------------------------------------
 265
 266
 267Author
 268------
 269Written by Petr "Pasky" Baudis <pasky@suse.cz>,
 270and the git list <git@vger.kernel.org>
 271
 272Documentation
 273--------------
 274Documentation by Petr Baudis and the git list.
 275
 276GIT
 277---
 278Part of the gitlink:git[7] suite