Documentation: filter-branch env-filter example

filter-branch --env-filter example that shows how to change the email
address in all commits before publishing a project.

Signed-off-by: Tadeusz Andrzej Kadłubowski <yess@hell.org.pl>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt
index c915d0570ded2b35075e0b08de32fdd571684e1d..69a40b21077594f3fa8bfa206bb7e6ce9dea6214 100644 (file)
--- a/Documentation/git-filter-branch.txt
+++ b/Documentation/git-filter-branch.txt
@@ -332,6 +332,26 @@ git filter-branch --msg-filter '
 ' HEAD~10..HEAD
 --------------------------------------------------------
 
+The `--env-filter` option can be used to modify committer and/or author
+identity.  For example, if you found out that your commits have the wrong
+identity due to a misconfigured user.email, you can make a correction,
+before publishing the project, like this:
+
+--------------------------------------------------------
+git filter-branch --env-filter '
+       if test "$GIT_AUTHOR_EMAIL" = "root@localhost"
+       then
+               GIT_AUTHOR_EMAIL=john@example.com
+               export GIT_AUTHOR_EMAIL
+       fi
+       if test "$GIT_COMMITTER_EMAIL" = "root@localhost"
+       then
+               GIT_COMMITTER_EMAIL=john@example.com
+               export GIT_COMMITTER_EMAIL
+       fi
+' -- --all
+--------------------------------------------------------
+
 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