Re: [PATCH] Document git rev-list --first-parent

From: Junio C Hamano <gitster@pobox.com>
Date: Dec 25, 2007, 09:35 UTC
Message-ID: <7vwsr3nmly.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <476F8679.8010706@qumranet.com>

Avi Kivity <avi@qumranet.com> writes:

Show 10 quoted lines

> I'm a mid-level maintainer for a particular subsystem (kvm).  I merge
> patchsets from others and do my own work, but I am careful to keep
> everything linear (no real merges in the git sense).  Every once in a
> while I merge from upstream or some other tree, but these are never
> kvm developments.  Every merge window I rebase the development branch
> to upstream, removing commits that were later reverted, and merging
> fixes into the patches that introduce them and push the result to
> Linus.  Hopefully that's clear as I'm not much of an ascii artist.
> So, for me --first-parent means "commits to the development branch of
> kvm", whether by myself or someone else.

Sure. That's a perfect use case for --first-parent, as you can afford to rebase.

I wanted to point out that the description needs to be clear enough that people know the option is applicable only to some workflow, but not necessarily to their own. Saying "this option gives a better overview" as if it always would felt wrong. For example for Linus, the option will not give a better overview.

Even in your case, if you merged from others' kvm tree, the option becomes useless, as you mentioned ("I am careful to keep everything linear").

If somebody cannot rebase (Linus certainly doesn't, and as a general rule the top-level integration branch would never be rebased) but pulls from people, some merges end up as real merges while some others fast-forward and do not create merge commits. In such a history, --first-parent is not very useful. Some parts of development will see individual commits (i.e. ones applied by the top-level integrator himself, and the ones built and committed by a subsystem person whose merge happened to have fast-forwarded), while other parts will just show merge commits (i.e. all other merges from subsystem people).

I however think the wording "... the evolution of a particular branch" lessens my worries a bit, because it hints that the option is about viewing the history of a topic branch, not the integration mainline. Maybe the wording can be made even more explicit and say something like:

    This option can give a better overview when viewing the
    evolution of a particular topic branch, because merges into
    a topic branch tend to be only about adjusting to updated
    upstream from time to time, and this option allows you to
    ignore the individual commits brought in to your history by
    such a merge.

By the way, the wording "if a branch implements a consistent fast-forward policy" suggests that forcing a real merge when the merged branch is a fast-forward of your history is somehow a good thing, but I think it is backwards to make such an artificial real merge just to keep --first-parent happy.