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

Tadeusz Andrzej Kadłubowski· Feb 21, 2013, 20:22 UTC · lore

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.

Signed-off-by: Tadeusz Andrzej Kadłubowski <yess@hell.org.pl>
---
 Documentation/git-filter-branch.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

Show changes to Documentation/git-filter-branch.txt +3 −3

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.
  A 'map' function is available that takes an "original sha1 id" argument
 and outputs a "rewritten sha1 id" if the commit has been already

-- 
1.7.11.7

Junio C Hamano· Feb 21, 2013, 20:46 UTC · re: Tadeusz Andrzej Kadłubowski · lore

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

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.

Show 19 quoted lines

> 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

patch, 2 partsgit-filter-branch.txt: clarify ident variables usage