Merge branch 'gp/maint-diffdoc' into maint

diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt
index 4f89c04a88260bb82d02458767bef18b08121395..895d7503100632f5ab79af548fed3b3a6d79c413 100644 (file)
--- a/Documentation/git-filter-branch.txt
+++ b/Documentation/git-filter-branch.txt
@@ -113,8 +113,10 @@ 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.
+You can use the 'map' convenience function in this filter, and other
+convenience functions, too.  For example, calling 'skip_commit "$@"'
+will leave out the current commit (but not its changes! If you want
+that, use gitlink:git-rebase[1] instead).
 
 --tag-name-filter <command>::
        This is the filter for rewriting tag names. When passed,
@@ -150,7 +152,7 @@ definition impossible to preserve signatures at any rate.)
        does this in the '.git-rewrite/' directory but you can override
        that choice by this parameter.
 
--f\|--force::
+-f|--force::
        `git filter-branch` refuses to start with an existing temporary
        directory or when there are already refs starting with
        'refs/original/', unless forced.
@@ -178,8 +180,7 @@ A significantly faster version:
 git filter-branch --index-filter 'git update-index --remove filename' HEAD
 --------------------------------------------------------------------------
 
-Now, you will get the rewritten history saved in the branch 'newbranch'
-(your current branch is left untouched).
+Now, you will get the rewritten history saved in HEAD.
 
 To set a commit (which typically is at the tip of another
 history) to be the parent of the current initial commit, in
@@ -212,24 +213,34 @@ To remove commits authored by "Darl McBribe" from the history:
 git filter-branch --commit-filter '
        if [ "$GIT_AUTHOR_NAME" = "Darl McBribe" ];
        then
-               shift;
-               while [ -n "$1" ];
-               do
-                       shift;
-                       echo "$1";
-                       shift;
-               done;
+               skip_commit "$@";
        else
                git commit-tree "$@";
        fi' HEAD
 ------------------------------------------------------------------------------
 
+The function 'skip_commit' is defined as follows:
+
+--------------------------
+skip_commit()
+{
+       shift;
+       while [ -n "$1" ];
+       do
+               shift;
+               map "$1";
+               shift;
+       done;
+}
+--------------------------
+
 The shift magic first throws away the tree id and then the -p
 parameters.  Note that this handles merges properly! In case Darl
 committed a merge between P1 and P2, it will be propagated properly
 and all children of the merge will become merge commits with P1,P2
 as their parents instead of the merge commit.
 
+
 To restrict rewriting to only part of the history, specify a revision
 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