Documentation/git-filter-branch.txt

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