Re: [PATCH] Documentation/git-filter-branch.txt: Fix description of --commit-filter

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

Kevin Ballard <kevin@sb.org> writes:

> The old description was misleading and logically impossible. It claimed that
> the ancestors of the original commit would be re-written to have the multiple
> emitted ids as parents. Not only would this modify existing objects, but it
> would create a cycle. What this actually does is pass the multiple emitted ids
> to the newly-created children to use as parents.
>
> Signed-off-by: Kevin Ballard <kevin@sb.org>
> ---
>  Documentation/git-filter-branch.txt |    4 ++--
>  1 files changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt
> index 506c37a..541bf23 100644
> --- a/Documentation/git-filter-branch.txt
> +++ b/Documentation/git-filter-branch.txt
> @@ -113,8 +113,8 @@ OPTIONS
>  	stdin.  The commit id is expected on stdout.
>  +
>  As a special extension, the commit filter may emit multiple
> -commit ids; in that case, ancestors of the original commit will
> -have all of them as parents.
> +commit ids; in that case, the rewritten children of the original commit will
> +have all of them as parents. You probably don't want to do this.
>  +

Now I am _very_ confused.

The original description sounds as if:

        In this history, when rewriting commit C, if we emit A from the
        filter:

                     B
                      \
                ---A---C---D
               
        We will somehow make 'A' and 'B' have A as their parents.

which is wrong as you pointed out.

But I am also confused by the new description:

        In that history, we will make sure that rewritten D (original
        commit being C) have A as parent.  IOW, we will have

                --A'--C'  D'
                         /
                        A

which is not what happens.  What it does is that the commits in the output
from the filter (i.e. A) are first mapped to the corresponding commits in
the rewritten history (i.e. A'), and they will be used as the parents of
the rewritten commit, to form this history:

                --A'--C'

isn't it?

Also you did not defend why you added "You probably don't want to do this"
to the description.