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