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

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

Avi Kivity <avi@qumranet.com> writes:

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