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