Merge branch 'jc/perl-cat-blob' into maint
[gitweb.git] / Documentation / git-filter-branch.txt
index dfd12c94e42b577e40665b0b10a78af184702abb..e4c8e82660ddf9aace717e269a50ffa9adf4405e 100644 (file)
@@ -64,8 +64,11 @@ argument is always evaluated in the shell context using the 'eval' command
 Prior to that, the $GIT_COMMIT environment variable will be set to contain
 the id of the commit being rewritten.  Also, GIT_AUTHOR_NAME,
 GIT_AUTHOR_EMAIL, GIT_AUTHOR_DATE, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL,
-and GIT_COMMITTER_DATE are set according to the current commit.  The values
-of these variables after the filters have run, are used for the new commit.
+and GIT_COMMITTER_DATE are taken from the current commit and exported to
+the environment, in order to affect the author and committer identities of
+the replacement commit created by linkgit:git-commit-tree[1] after the
+filters have run.
+
 If any evaluation of <command> returns a non-zero exit status, the whole
 operation will be aborted.
 
@@ -329,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