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

[Avi Kivity <avi@qumranet.com>]

Junio C Hamano wrote:
> 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]

> 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