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>] [-f | --force] [<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.  Nevertheless, this may be useful in the future for
  30 compensating for some git bugs or such, therefore such a usage is
  31 permitted.
  32
  33 *WARNING*! The rewritten history will have different object names for all
  34 the objects and will not converge with the original branch.  You will not
  35 be able to easily push and distribute the rewritten branch on top of the
  36 original branch.  Please do not use this command if you do not know the
  37 full implications, and avoid using it anyway, if a simple single commit
  38 would suffice to fix your problem.
  39
  40 Always verify that the rewritten version is correct: The original refs,
  41 if different from the rewritten ones, will be stored in the namespace
  42 'refs/original/'.
  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 (with the
  54 notable exception of the commit filter, for technical reasons).
  55 Prior to that, the $GIT_COMMIT environment variable will be set to contain
  56 the id of the commit being rewritten.  Also, GIT_AUTHOR_NAME,
  57 GIT_AUTHOR_EMAIL, GIT_AUTHOR_DATE, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL,
  58 and GIT_COMMITTER_DATE are set according to the current commit.
  59
  60 A 'map' function is available that takes an "original sha1 id" argument
  61 and outputs a "rewritten sha1 id" if the commit has been already
  62 rewritten, and "original sha1 id" otherwise; the 'map' function can
  63 return several ids on separate lines if your commit filter emitted
  64 multiple commits.
  65
  66
  67 OPTIONS
  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 +
 111 As a special extension, the commit filter may emit multiple
 112 commit ids; in that case, ancestors of the original commit will
 113 have 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 +
 122 The original tags are not deleted, but can be overwritten;
 123 use "--tag-name-filter=cat" to simply update the tags.  In this
 124 case, be very careful and make sure you have the old tags
 125 backed up in case the conversion has run afoul.
 126 +
 127 Note that there is currently no support for proper rewriting of
 128 tag objects; in layman terms, if the tag has a message or signature
 129 attached, the rewritten tag won't have it.  Sorry.  (It is by
 130 definition 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
 157 Examples
 158 --------
 159
 160 Suppose you want to remove a file (containing confidential information
 161 or copyright violation) from all commits:
 162
 163 -------------------------------------------------------
 164 git filter-branch --tree-filter 'rm filename' HEAD
 165 -------------------------------------------------------
 166
 167 A significantly faster version:
 168
 169 --------------------------------------------------------------------------
 170 git filter-branch --index-filter 'git update-index --remove filename' HEAD
 171 --------------------------------------------------------------------------
 172
 173 Now, you will get the rewritten history saved in the branch 'newbranch'
 174 (your current branch is left untouched).
 175
 176 To set a commit (which typically is at the tip of another
 177 history) to be the parent of the current initial commit, in
 178 order to paste the other history behind the current history:
 179
 180 -------------------------------------------------------------------
 181 git 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
 185 initial commit - add graftcommit as a parent).  Note that this assumes
 186 history with a single root (that is, no merge without common ancestors
 187 happened).  If this is not the case, use:
 188
 189 --------------------------------------------------------------------------
 190 git filter-branch --parent-filter \
 191         'cat; test $GIT_COMMIT = <commit-id> && echo "-p <graft-id>"' HEAD
 192 --------------------------------------------------------------------------
 193
 194 or even simpler:
 195
 196 -----------------------------------------------
 197 echo "$commit-id $graft-id" >> .git/info/grafts
 198 git filter-branch $graft-id..HEAD
 199 -----------------------------------------------
 200
 201 To remove commits authored by "Darl McBribe" from the history:
 202
 203 ------------------------------------------------------------------------------
 204 git 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
 219 The shift magic first throws away the tree id and then the -p
 220 parameters.  Note that this handles merges properly! In case Darl
 221 committed a merge between P1 and P2, it will be propagated properly
 222 and all children of the merge will become merge commits with P1,P2
 223 as their parents instead of the merge commit.
 224
 225 To restrict rewriting to only part of the history, specify a revision
 226 range in addition to the new branch name.  The new branch name will
 227 point to the top-most revision that a 'git rev-list' of this range
 228 will print.
 229
 230 Note that the changes introduced by the commits, and not reverted by
 231 subsequent commits, will still be in the rewritten branch. If you want
 232 to throw out _changes_ together with the commits, you should use the
 233 interactive mode of gitlink:git-rebase[1].
 234
 235 Consider this history:
 236
 237 ------------------
 238      D--E--F--G--H
 239     /     /
 240 A--B-----C
 241 ------------------
 242
 243 To rewrite only commits D,E,F,G,H, but leave A, B and C alone, use:
 244
 245 --------------------------------
 246 git filter-branch ... C..H
 247 --------------------------------
 248
 249 To rewrite commits E,F,G,H, use one of these:
 250
 251 ----------------------------------------
 252 git filter-branch ... C..H --not D
 253 git filter-branch ... D..H --not C
 254 ----------------------------------------
 255
 256 To move the whole tree into a subdirectory, or remove it from there:
 257
 258 ---------------------------------------------------------------
 259 git 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
 267 Author
 268 ------
 269 Written by Petr "Pasky" Baudis <pasky@suse.cz>,
 270 and the git list <git@vger.kernel.org>
 271
 272 Documentation
 273 --------------
 274 Documentation by Petr Baudis and the git list.
 275
 276 GIT
 277 ---
 278 Part of the gitlink:git[7] suite