filter-branch: fix remnants of old syntax in documentation
Some time ago, filter-branch's syntax changed so that more than one ref can be rewritten at the same time. This involved the removal of the ref name for the result; instead, the refs are rewritten in-place. This updates the last leftovers in the documentation to reflect the new behavior. Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Johannes Schindelin committed
Aug 31, 2007 at 17:42 UTC
082036688f528d28ef5b63d9491a0ec0d701f68a
1 file changed
+18
-14
Documentation/git-filter-branch.txt
+18
-14
@@ -17,19 +17,19 @@ SYNOPSIS
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.
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 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.
27
+The command will only rewrite the _positive_ refs mentioned in the
28
+command line (i.e. 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
@@ -43,8 +43,8 @@ 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.
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
@@ -112,6 +112,9 @@ OPTIONS
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
+Note that the 'map' function is not available in the commit filter yet.
117
+This will be changed in a future version.
118
119
--tag-name-filter <command>::
120
This is the filter for rewriting tag names. When passed,
@@ -186,8 +189,8 @@ order to paste the other history behind the current history:
189
git filter-branch --parent-filter 'sed "s/^\$/-p <graft-id>/"' HEAD
190
-------------------------------------------------------------------
191
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
192
+(if the parent string is empty - which happens when we are dealing with
193
+the initial commit - add graftcommit as a parent). Note that this assumes
194
history with a single root (that is, no merge without common ancestors
195
happened). If this is not the case, use:
196
@@ -232,11 +235,12 @@ range in addition to the new branch name. The new branch name will
235
point to the top-most revision that a 'git rev-list' of this range
236
will print.
237
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
238
+*NOTE* the changes introduced by the commits, and which are not reverted
239
+by subsequent commits, will still be in the rewritten branch. If you want
240
to throw out _changes_ together with the commits, you should use the
241
interactive mode of gitlink:git-rebase[1].
242
243
+
244
Consider this history:
245
246
------------------