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

From: Junio C Hamano <gitster@pobox.com>
Date: Dec 24, 2007, 09:13 UTC
Message-ID: <7vprwwsbey.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <476F6F95.1030506@qumranet.com>

Avi Kivity <avi@qumranet.com> writes:

Show 18 quoted lines

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