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