stash doc: add a warning about using create

diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt
index e2301f5c0106a35e5fa14d63944abeea2cb09e9b..e4c8e82660ddf9aace717e269a50ffa9adf4405e 100644 (file)
--- a/Documentation/git-filter-branch.txt
+++ b/Documentation/git-filter-branch.txt
@@ -18,7 +18,7 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Lets you rewrite git revision history by rewriting the branches mentioned
+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.
@@ -29,7 +29,7 @@ The command will only rewrite the _positive_ refs mentioned in the
 command line (e.g. 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,
+useful in the future for compensating for some Git bugs or such,
 therefore such a usage is permitted.
 
 *NOTE*: This command honors `.git/info/grafts` file and refs in
@@ -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
@@ -374,7 +397,7 @@ git-filter-branch is often used to get rid of a subset of files,
 usually with some combination of `--index-filter` and
 `--subdirectory-filter`.  People expect the resulting repository to
 be smaller than the original, but you need a few more steps to
-actually make it smaller, because git tries hard not to lose your
+actually make it smaller, because Git tries hard not to lose your
 objects until you tell it to.  First make sure that:
 
 * You really removed all variants of a filename, if a blob was moved