Documentation: filter-branch env-filter example

filter-branch --env-filter example that shows how to change the email address in all commits by a certain developer.

---
 Documentation/git-filter-branch.txt | 13 +++++++++++++
 1 file changed, 13 insertions(+)

index dfd12c9..2664cec 100644
@@ -329,6 +329,19 @@ git filter-branch --msg-filter '
 ' HEAD~10..HEAD
 --------------------------------------------------------
 
+You can modify committer/author personal information using `--env-filter`.
+For example, to update some developer's email address use this command:
+
+--------------------------------------------------------
+git filter-branch --env-filter '
+	if [ $GIT_AUTHOR_EMAIL = [email protected] ]
+	then
+		[email protected]
+	fi
+	export GIT_AUTHOR_EMAIL
+' -- --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

1.7.11.7

Thanks. Sign-off?

 Documentation/git-filter-branch.txt | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

index 8ebe999..066548e 100644
@@ -83,8 +83,7 @@ OPTIONS
 	This filter may be used if you only need to modify the environment
 	in which the commit will be performed.  Specifically, you might
 	want to rewrite the author/committer name/email/time environment
-	variables (see linkgit:git-commit-tree[1] for details).  Do not forget
-	to re-export the variables.
+	variables (see linkgit:git-commit-tree[1] for details).
 
 --tree-filter <command>::
 	This is the filter for rewriting the tree and its contents.

@@ -340,12 +339,10 @@ git filter-branch --env-filter '
 	if test "$GIT_AUTHOR_EMAIL" = "root@localhost"
 	then
 		[email protected]
-		export GIT_AUTHOR_EMAIL
 	fi
 	if test "$GIT_COMMITTER_EMAIL" = "root@localhost"
 	then
 		[email protected]
-		export GIT_COMMITTER_EMAIL
 	fi
 ' -- --all
 --------------------------------------------------------

Yeah, definitely. If you are cleaning up a broken ident that cannot be parsed, the failure mode is to put the whole author line in $GIT_AUTHOR_EMAIL, which would almost certainly include spaces.

That looks better, though there are a few English nits; here's my edited version:

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:

I think it has always been the case that we export them after setting them; just look at the preimage from 3c730fab, and you can see exports there.

I think the advice in the documentation about re-exporting is because some versions of the bourne shell will not reliably pass the new version of the variable when you do this:

VAR=old
export VAR
VAR=new
some_subprocess ;# we see $VAR=old here!

I do not recall ever running across such a shell myself, but rather hearing about it third-hand in a portability guide somewhere. Apple's shell documentation seems to indicate that /bin/sh in older versions of OS X had this behavior:

https://developer.apple.com/library/mac/documentation/opensource/conceptual/shellscripting/shell_scripts/shell_scripts.html#//apple_ref/doc/uid/TP40004268-CH237-SW11

which makes me think that BSD ash may behave that way. It is certainly not necessary to re-export under bash or dash. I shudder to think what horrible, 1980's-era behavior is codified in Solaris /bin/sh.

We could explicitly re-export all of the ident variables preemptively before calling commit-tree, just to save the user the hassle of remembering to do so. It would be a no-op on sane shells, and I doubt the runtime cost is very high. I suppose it would break somebody who explicitly did:

unset GIT_COMMITTER_NAME ;# use the value from user.name

in their env-filter, but that seems like a pretty unlikely corner case.

-Peff

The closest I could find in the autoconf shell guidelines[1] is that the automagic export marking for incoming variables is not always accurate:

export
The builtin export dubs a shell variable environment variable. Each update of exported variables corresponds to an update of the environment variables. Conversely, each environment variable received by the shell when it is launched should be imported as a shell variable marked as exported.

Alas, many shells, such as Solaris 2.5, IRIX 6.3, IRIX 5.2, AIX 4.1.5, and Digital UNIX 4.0, forget to export the environment variables they receive. As a result, two variables coexist: the environment variable and the shell variable. The following code demonstrates this failure:

#! /bin/sh
echo $FOO
FOO=bar
echo $FOO
exec /bin/sh $0

when run with FOO=foo' in the environment, these shells will print alternately foo' and bar', although it should only print foo' and then a sequence of `bar's.

Therefore you should export again each environment variable that you update.

I don't know what the behavior would be on such shells of:

	#!/bin/sh
	echo $FOO
	FOO=bar
	export FOO
	echo $FOO
	exec /bin/sh $0

I.e., would the "export" correctly reconcile the local and environment copies of the variable, or are they forever broken? I don't have such a system to test on. But that would more closely match what we are doing.

-Peff

[1] https://www.gnu.org/software/autoconf/manual/autoconf.html#Limitations-of-Builtins

Yeah, I think the only difference is a broken commit case where sed expression did not find what it was looking for, in which case we do not do the export.

Ahh, old and painful memory of Solaris days comes back to me. OK, let's keep the export then.

Thanks.