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

From: Junio C Hamano <gitster@pobox.com>
Date: May 31, 2008, 22:33 UTC
Message-ID: <7vskvydrys.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <7v1w3jgs51.fsf@gitster.siamese.dyndns.org>

Junio C Hamano <gitster@pobox.com> writes:

Show 6 quoted lines

> 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".