Re: [PATCH] git-filter-branch.txt: Add picture to explain the graft-id

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

Jari Aalto <jari.aalto@cante.net> writes:

> diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt
> index 543a1cf..73939e2 100644
> --- a/Documentation/git-filter-branch.txt
> +++ b/Documentation/git-filter-branch.txt
> @@ -186,7 +186,7 @@ Now, you will get the rewritten history saved in HEAD.
>  
>  To set a commit (which typically is at the tip of another
>  history) to be the parent of the current initial commit, in
> -order to paste the other history behind the current history:
> +order to paste the other history behind the current history.
>  
>  -------------------------------------------------------------------
>  git filter-branch --parent-filter 'sed "s/^\$/-p <graft-id>/"' HEAD

Why?  I think ":" in the original is correct here, just like what you can
see in the pre-context in the next hunk.

> @@ -198,6 +198,12 @@ history with a single root (that is, no merge without common ancestors
>  happened).  If this is not the case, use:
>  
>  --------------------------------------------------------------------------
> +
> +    The plan: supposing we're merging A with B
> +    commit sequence A: a-b-c			graft-id  = b
> +    commit sequence B: c'-d'-e'			commit-id = c'
> +    Result	     : a-b-c'-d'-e'
> +
>  git filter-branch --parent-filter \
>  	'test $GIT_COMMIT = <commit-id> && echo "-p <graft-id>" || cat' HEAD
>  --------------------------------------------------------------------------

It is not "merging".  As seen in the first hunk you are "pasting" (or
grafting).

Also I think it would be easier to read without made-up words like
"xxx-id", if you are illustrating.

The example is unclear what HEAD is.  If you are clarifying the example,
it is better to state that we are filtering starting at the tip of the
second sequence.

Perhaps...

    Suppose we have these two unrelated histories:

	---A---B---C (tip of the branch "one")

	---D---E---F (tip of the branch "two")

    and the commits C and D have the same trees and are logically at the
    corresponding places in the global history.  You want to rewrite these
    histories by pasting them together at C/D, so that the result looks
    like this:

        ---A---B---D---E---F (rewritten branch "two")

    You can use --parent-filter to rewrite the parent of D to be B by
    telling it to say "the parent is B" when (and only when) filter-branch
    reaches D and processes it (for other commits, you just say "whatever
    parents the original commit had is just fine" by running "cat" to emit
    what you get from your standard input).  Hence, the command line to
    filter the history, starting at F, becomes:

	git filter-branch --parent-filter '
		if test $GIT_COMMIT = D
                then
                	echo "-p B
		else
                	cat
		fi
        ' two

    After filter-branch finishes, the branch "two" would have the desired
    history.