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