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

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

Avi Kivity <avi@qumranet.com> writes:

> Junio C Hamano wrote:
>> Avi Kivity <avi@qumranet.com> writes:
>>
>>> Document git rev-list's --first-parent option.  Documentation taken from
>>> git log.
>>> ...
>>> +--first-parent::
>>> +	Follow only the first parent commit upon seeing a merge
>>> +	commit.  This  option gives a better overview of the
>>> +	evolution of a particular branch.
>>> +
>>>
>>
>> I am afraid that this description is not sufficient.  The
>> history given by --first-parent is useful only in a very limited
>> use case, and the user needs to be aware of it.
>
> I don't know which use case you are referring to...

Please read the commit log message you snarfed the description
again.

First-parent is useful only if you are the primary integrator
and do not fast-forward from other people.  Only in that case,
you will see the overview of "the primary integration branch".
Otherwise you will observe the history viewed by whoever
happened to make a merge, which would switch every time you
cross the fast-forward boundary.

Making it sound as if it always will give a better overview is
misleading.