@matheusbsbs / matheus-bagliano / commits / c401b33c34
Fork 0

Document git-filter-branch

This moves the documentation in git-filter-branch.sh to its own man page, with a few touch ups (incorporating comments by Frank Lichtenheld). Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Johannes Schindelin committed Jul 4, 2007 at 00:41 UTC c401b33c349beaf4c218c6441c3e2b58a958de6f
3 files changed +266 -184
Documentation/cmd-list.perl
+1
@@ -105,6 +105,7 @@ git-diff-tree plumbinginterrogators
105 git-fast-import ancillarymanipulators
106 git-fetch mainporcelain
107 git-fetch-pack synchingrepositories
108 +git-filter-branch ancillarymanipulators
109 git-fmt-merge-msg purehelpers
110 git-for-each-ref plumbinginterrogators
111 git-format-patch mainporcelain
Documentation/git-filter-branch.txt new
+262
@@ -0,0 +1,262 @@
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
git-filter-branch.sh
+3 -184
@@ -4,190 +4,9 @@
4 # Copyright (c) Petr Baudis, 2006
5 # Minimal changes to "port" it to core-git (c) Johannes Schindelin, 2007
6 #
7 -# Lets you rewrite GIT revision history by creating a new branch from
8 -# your current branch by applying custom filters on each revision.
9 -# Those filters can modify each tree (e.g. removing a file or running
10 -# a perl rewrite on all files) or information about each commit.
11 -# Otherwise, all information (including original commit times or merge
12 -# information) will be preserved.
13 -#
14 -# The command takes the new branch name as a mandatory argument and
15 -# the filters as optional arguments. If you specify no filters, the
16 -# commits will be recommitted without any changes, which would normally
17 -# have no effect and result with the new branch pointing to the same
18 -# branch as your current branch. (Nevertheless, this may be useful in
19 -# the future for compensating for some Git bugs or such, therefore
20 -# such a usage is permitted.)
21 -#
22 -# WARNING! The rewritten history will have different ids for all the
23 -# objects and will not converge with the original branch. You will not
24 -# be able to easily push and distribute the rewritten branch. Please do
25 -# not use this command if you do not know the full implications, and
26 -# avoid using it anyway - do not do what a simple single commit on top
27 -# of the current version would fix.
28 -#
29 -# Always verify that the rewritten version is correct before disposing
30 -# the original branch.
31 -#
32 -# Note that since this operation is extensively I/O expensive, it might
33 -# be a good idea to do it off-disk, e.g. on tmpfs. Reportedly the speedup
34 -# is very noticeable.
35 -#
36 -# OPTIONS
37 -# -------
38 -# -d TEMPDIR:: The path to the temporary tree used for rewriting
39 -# When applying a tree filter, the command needs to temporary
40 -# checkout the tree to some directory, which may consume
41 -# considerable space in case of large projects. By default it
42 -# does this in the '.git-rewrite/' directory but you can override
43 -# that choice by this parameter.
44 -#
45 -# Filters
46 -# ~~~~~~~
47 -# The filters are applied in the order as listed below. The COMMAND
48 -# argument is always evaluated in shell using the 'eval' command.
49 -# The $GIT_COMMIT environment variable is permanently set to contain
50 -# the id of the commit being rewritten. The author/committer environment
51 -# variables are set before the first filter is run.
52 -#
53 -# A 'map' function is available that takes an "original sha1 id" argument
54 -# and outputs a "rewritten sha1 id" if the commit has been already
55 -# rewritten, fails otherwise; the 'map' function can return several
56 -# ids on separate lines if your commit filter emitted multiple commits
57 -# (see below).
58 -#
59 -# --env-filter COMMAND:: The filter for modifying environment
60 -# This is the filter for modifying the environment in which
61 -# the commit will be performed. Specifically, you might want
62 -# to rewrite the author/committer name/email/time environment
63 -# variables (see `git-commit` for details). Do not forget to
64 -# re-export the variables.
65 -#
66 -# --tree-filter COMMAND:: The filter for rewriting tree (and its contents)
67 -# This is the filter for rewriting the tree and its contents.
68 -# The COMMAND argument is evaluated in shell with the working
69 -# directory set to the root of the checked out tree. The new tree
70 -# is then used as-is (new files are auto-added, disappeared files
71 -# are auto-removed - .gitignore files nor any other ignore rules
72 -# HAVE NO EFFECT!).
73 -#
74 -# --index-filter COMMAND:: The filter for rewriting index
75 -# This is the filter for rewriting the Git's directory index.
76 -# It is similar to the tree filter but does not check out the
77 -# tree, which makes it much faster. However, you must use the
78 -# lowlevel Git index manipulation commands to do your work.
79 -#
80 -# --parent-filter COMMAND:: The filter for rewriting parents
81 -# This is the filter for rewriting the commit's parent list.
82 -# It will receive the parent string on stdin and shall output
83 -# the new parent string on stdout. The parent string is in
84 -# format accepted by `git commit-tree`: empty for initial
85 -# commit, "-p parent" for a normal commit and "-p parent1
86 -# -p parent2 -p parent3 ..." for a merge commit.
87 -#
88 -# --msg-filter COMMAND:: The filter for rewriting commit message
89 -# This is the filter for rewriting the commit messages.
90 -# The COMMAND argument is evaluated in shell with the original
91 -# commit message on standard input; its standard output is
92 -# is used as the new commit message.
93 -#
94 -# --commit-filter COMMAND:: The filter for performing the commit
95 -# If this filter is passed, it will be called instead of the
96 -# `git commit-tree` command, with those arguments:
97 -#
98 -# TREE_ID [-p PARENT_COMMIT_ID]...
99 -#
100 -# and the log message on stdin. The commit id is expected on
101 -# stdout. As a special extension, the commit filter may emit
102 -# multiple commit ids; in that case, all of them will be used
103 -# as parents instead of the original commit in further commits.
104 -#
105 -# --tag-name-filter COMMAND:: The filter for rewriting tag names.
106 -# If this filter is passed, it will be called for every tag ref
107 -# that points to a rewritten object (or to a tag object which
108 -# points to a rewritten object). The original tag name is passed
109 -# via standard input, and the new tag name is expected on standard
110 -# output.
111 -#
112 -# The original tags are not deleted, but can be overwritten;
113 -# use "--tag-name-filter=cat" to simply update the tags. In this
114 -# case, be very careful and make sure you have the old tags
115 -# backed up in case the conversion has run afoul.
116 -#
117 -# Note that there is currently no support for proper rewriting of
118 -# tag objects; in layman terms, if the tag has a message or signature
119 -# attached, the rewritten tag won't have it. Sorry. (It is by
120 -# definition impossible to preserve signatures at any rate, though.)
121 -#
122 -# --subdirectory-filter DIRECTORY:: Only regard the history, as seen by
123 -# the given subdirectory. The result will contain that directory as
124 -# its project root.
125 -#
126 -# EXAMPLE USAGE
127 -# -------------
128 -# Suppose you want to remove a file (containing confidential information
129 -# or copyright violation) from all commits:
130 -#
131 -# git-filter-branch --tree-filter 'rm filename' newbranch
132 -#
133 -# A significantly faster version:
134 -#
135 -# git-filter-branch --index-filter 'git update-index --remove filename' newbranch
136 -#
137 -# Now, you will get the rewritten history saved in the branch 'newbranch'
138 -# (your current branch is left untouched).
139 -#
140 -# To "etch-graft" a commit to the revision history (set a commit to be
141 -# the parent of the current initial commit and propagate that):
142 -#
143 -# git-filter-branch --parent-filter sed\ 's/^$/-p graftcommitid/' newbranch
144 -#
145 -# (if the parent string is empty - therefore we are dealing with the
146 -# initial commit - add graftcommit as a parent). Note that this assumes
147 -# history with a single root (that is, no git-merge without common ancestors
148 -# happened). If this is not the case, use:
149 -#
150 -# git-filter-branch --parent-filter 'cat; [ "$GIT_COMMIT" = "COMMIT" ] && echo "-p GRAFTCOMMIT"' newbranch
151 -#
152 -# To remove commits authored by "Darl McBribe" from the history:
153 -#
154 -# git-filter-branch --commit-filter 'if [ "$GIT_AUTHOR_NAME" = "Darl McBribe" ]; then shift; while [ -n "$1" ]; do shift; echo "$1"; shift; done; else git commit-tree "$@"; fi' newbranch
155 -#
156 -# (the shift magic first throws away the tree id and then the -p
157 -# parameters). Note that this handles merges properly! In case Darl
158 -# committed a merge between P1 and P2, it will be propagated properly
159 -# and all children of the merge will become merge commits with P1,P2
160 -# as their parents instead of the merge commit.
161 -#
162 -# To restrict rewriting to only part of the history, specify a revision
163 -# range in addition to the new branch name. The new branch name will
164 -# point to the top-most revision that a 'git rev-list' of this range
165 -# will print.
166 -#
167 -# Consider this history:
168 -#
169 -# D--E--F--G--H
170 -# / /
171 -# A--B-----C
172 -#
173 -# To rewrite commits D,E,F,G,H, use:
174 -#
175 -# git-filter-branch ... new-H C..H
176 -#
177 -# To rewrite commits E,F,G,H, use one of these:
178 -#
179 -# git-filter-branch ... new-H C..H --not D
180 -# git-filter-branch ... new-H D..H --not C
181 -#
182 -# To move the whole tree into a subdirectory, or remove it from there:
183 -#
184 -# git-filter-branch --index-filter \
185 -# 'git ls-files -s | sed "s-\t-&newsubdir/-" |
186 -# GIT_INDEX_FILE=$GIT_INDEX_FILE.new \
187 -# git update-index --index-info &&
188 -# mv $GIT_INDEX_FILE.new $GIT_INDEX_FILE' directorymoved
189 -
190 -# Testsuite: TODO
7 +# Lets you rewrite the revision history of the current branch, creating
8 +# a new branch. You can specify a number of filters to modify the commits,
9 +# files and trees.
10
11 set -e
12