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

> Junio C Hamano <gitster@pobox.com> writes:
>
>> Kevin Ballard <kevin@sb.org> writes:
>>
>>> You're still talking about the parent-filter here. I think you're
>>> quite confused.
>>
>> Blush.  I should go to bed.
>
> Now after following the codepath, your original
>
>    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.
>     +
>     You can use the 'map' convenience function in this filter, and  
> other
>     convenience functions, too.  For example, calling 'skip_commit  
> "$@"'
>
> does make sense to me.  Except for "You probably don't want to do  
> this."
> part.  It is just "the utility of this feature is unknown to us" ;-)
>
> I dug the code with "git blame" and the basic logic has been the same
> since its introduction to git with 6f6826c (Add git-filter-branch,
> 2007-06-03).  The commit-filter itself appeared first in Cogito as  
> d690516
> (cg-admin-rewritehist --commit-filter for omitting commits,  
> 2006-03-26),
> and the commit log message claims that it was primarily meant to  
> _omit_
> unwanted commits from the history, but at the same time it  
> advertises the
> multiple commits case as a "feature" without telling why somebody  
> wants to
> do so.
>
> Except for this gem, which may have been lost in our copy:
>
>    # ... Note that this handles merges properly! In case Darl
>    # committed a merge between P1 and P2, it will be propagated  
> properly
>    # and all children of the merge will become merge commits with  
> P1,P2
>    # as their parents instead of the merge commit.
>
> IOW, to rewrite this history:
>
>        ---A---C---D---E
>              /
>             B
>
> to pretend C never happened, you would give A' and B' back when you
> rewrite C, to end up with this history:
>
>        ---A'--D'--E'
>              /
>             B'
>
> I'd agree with "You probably don't want to do this", but perhaps it  
> needs
> a bit of clarification as to _why_ you would not:
>
> - If the history is being rewritten for the whole tree, this will
>   make D' an evil merge that contains difference between C to D.
>
> - If the filtering of the history is done to ignore parts of the tree
>   that is touched between C and D (iow, history simplification would
>   leave trees C and D the same), you would want to simplify away D'  
> not
>   C'.  IOW, you would want the resulting history to look like:
>
>        ---A'--C'--E'
>              /
>             B'
>
>   and for that you do not need to use this "feature".