Re: [PATCH 1/2] git-filter-branch.txt: clarify ident variables usage

[Junio C Hamano <gitster@pobox.com>]

Tadeusz Andrzej Kadłubowski  <yess@hell.org.pl> writes:

> There is a rare edge case of git-filter-branch: a filter that unsets
> identity variables from the environment. Link to git-commit-tree
> clarifies how Git would fall back in this situation.

I find it unclear in the updated text _why_ the reader may want to
refer to that other documentation.

> Signed-off-by: Tadeusz Andrzej Kadłubowski <yess@hell.org.pl>
> ---
>  Documentation/git-filter-branch.txt | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt
> index dfd12c9..e50ee2f 100644
> --- a/Documentation/git-filter-branch.txt
> +++ b/Documentation/git-filter-branch.txt
> @@ -65,9 +65,9 @@ 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.
> -If any evaluation of <command> returns a non-zero exit status, the whole
> -operation will be aborted.
> +of these variables after the filters have run, are used for the new commit
> +(see linkgit:git-commit-tree[1] for details).  If any evaluation of <command>
> +returns a non-zero exit status, the whole operation will be aborted.

Here is my attempt to clarify it a bit.

	Also, ...<variables>... 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.

A user who contemplates to unset them should be able to guess the
consequences, even though the above text does not single out such an
insane misuse to put an undue stress on it.

>   A 'map' function is available that takes an "original sha1 id" argument
>  and outputs a "rewritten sha1 id" if the commit has been already