summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJohannes Schindelin <Johannes.Schindelin@gmx.de>2007-08-31 16:42:33 (GMT)
committerJunio C Hamano <gitster@pobox.com>2007-09-01 06:22:51 (GMT)
commit082036688f528d28ef5b63d9491a0ec0d701f68a (patch)
tree2ef14bf905fa35fca5f6408aad056723c803b5ea
parent88e21dc7461dca1ebc70d8579bcc9246364511ee (diff)
downloadgit-082036688f528d28ef5b63d9491a0ec0d701f68a.zip
git-082036688f528d28ef5b63d9491a0ec0d701f68a.tar.gz
git-082036688f528d28ef5b63d9491a0ec0d701f68a.tar.bz2
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>
-rw-r--r--Documentation/git-filter-branch.txt32
1 files changed, 18 insertions, 14 deletions
diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt
index ae03514..4f89c04 100644
--- a/Documentation/git-filter-branch.txt
+++ b/Documentation/git-filter-branch.txt
@@ -17,19 +17,19 @@ SYNOPSIS
DESCRIPTION
-----------
-Lets you rewrite git revision history by creating a new branch from
-your current branch, applying custom filters on each revision.
+Lets you rewrite git revision history by rewriting the branches mentioned
+in the <rev-list options>, applying custom filters on each revision.
Those filters can modify each tree (e.g. removing a file or running
a perl rewrite on all files) or information about each commit.
Otherwise, all information (including original commit times or merge
information) will be preserved.
-The command takes the new branch name as a mandatory argument and
-the filters as optional arguments. If you specify no filters, the
-commits will be recommitted without any changes, which would normally
-have no effect. Nevertheless, this may be useful in the future for
-compensating for some git bugs or such, therefore such a usage is
-permitted.
+The command will only rewrite the _positive_ refs mentioned in the
+command line (i.e. if you pass 'a..b', only 'b' will be rewritten).
+If you specify no filters, the commits will be recommitted without any
+changes, which would normally have no effect. Nevertheless, this may be
+useful in the future for compensating for some git bugs or such,
+therefore such a usage is permitted.
*WARNING*! The rewritten history will have different object names for all
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
'refs/original/'.
Note that since this operation is extensively I/O expensive, it might
-be a good idea to redirect the temporary directory off-disk, e.g. on
-tmpfs. Reportedly the speedup is very noticeable.
+be a good idea to redirect the temporary directory off-disk with the
+'-d' option, e.g. on tmpfs. Reportedly the speedup is very noticeable.
Filters
@@ -112,6 +112,9 @@ OPTIONS
As a special extension, the commit filter may emit multiple
commit ids; in that case, ancestors of the original commit will
have all of them as parents.
++
+Note that the 'map' function is not available in the commit filter yet.
+This will be changed in a future version.
--tag-name-filter <command>::
This is the filter for rewriting tag names. When passed,
@@ -186,8 +189,8 @@ order to paste the other history behind the current history:
git filter-branch --parent-filter 'sed "s/^\$/-p <graft-id>/"' HEAD
-------------------------------------------------------------------
-(if the parent string is empty - therefore we are dealing with the
-initial commit - add graftcommit as a parent). Note that this assumes
+(if the parent string is empty - which happens when we are dealing with
+the initial commit - add graftcommit as a parent). Note that this assumes
history with a single root (that is, no merge without common ancestors
happened). If this is not the case, use:
@@ -232,11 +235,12 @@ range in addition to the new branch name. The new branch name will
point to the top-most revision that a 'git rev-list' of this range
will print.
-Note that the changes introduced by the commits, and not reverted by
-subsequent commits, will still be in the rewritten branch. If you want
+*NOTE* the changes introduced by the commits, and which are not reverted
+by subsequent commits, will still be in the rewritten branch. If you want
to throw out _changes_ together with the commits, you should use the
interactive mode of gitlink:git-rebase[1].
+
Consider this history:
------------------