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

[Avi Kivity <avi@qumranet.com>]

Avi Kivity wrote:
> Junio C Hamano wrote:
>>> 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,...
>>>     
>>
>> Yeah, that is what I meant as a special case.  If you submit
>> patches and rebase the remainder of your changes to the updated
>> upstream (as x.org folks seem to do), then the --first-parent
>> history will not be your own development but "the global trunk
>> history."  If you are the top-level maintainer and your pull
>> sometimes ends up as a fast forward and sometimes a real merge,
>> you will sometimes get a full history of a topic done by
>> somebody else (if that person rebased on top of you) or just a
>> summary single merge (otherwise), and the distinction between
>> these two cases does not have anything to do with whose commits
>> they are (i.e. mine vs others) or the scope of the changes
>> (i.e. the trunk history vs side branch development).  It would
>> not be as useful as the "looking at the list of one's own
>> commits while summarizing out others' developments as merge
>> commits" world view the --first-parent would give you in your
>> history.
>>   
>
> Sorry, I'm confused now.  I'll try to explain more carefully what I'm 
> doing.
>
> 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.  It specifically excludes kvm 
> commits to mainline, since that would result in a bunch of duplicated 
> commits.  But it seems to be quite different from what you're describing.
>

Anyway, here's what I came up with:

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

    Note that this is only useful if the branch implements a consistent
    fast-forward merge policy.  One example is to never do a fast-forward
    merge (so that --first-parent returns strictly local commits). Another
    possible policy is to always fast-forward development related to the 
branch's
    topic, and only merge synchronizations with upstream or with other
    topic branches.




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