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

From: Avi Kivity <avi@qumranet.com>
Date: Dec 24, 2007, 09:40 UTC
Message-ID: <476F7EA4.1030001@qumranet.com>
In-Reply-To: <7vprwwsbey.fsf@gitster.siamese.dyndns.org>

Junio C Hamano wrote:

Show 29 quoted lines

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

[I assume you mean 0053e902;  I just copied the output of git log --help]

Show 8 quoted lines

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

Well, my use case is different. All of the development merges are fast-forwards (or plain patch applications); the only multiple-parent merges are pulls I do from the main tree in order to advance the baseline, or from upstream submission branches (which are very similar). So, for me --first-parent means "show me actual development, not syncs with upstream or cleanup branches".

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

I'll try to come up with better wording and submit a new patch.

-- 
error compiling committee.c: too many arguments to function