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

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

[Avi Kivity]

Document git rev-list's --first-parent option.  Documentation taken from
git log.

Signed-off-by: Avi Kivity <avi@qumranet.com>
---
 Documentation/git-rev-list.txt |    6 ++++++
 1 files changed, 6 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
index a03f9fe..b049086 100644
--- a/Documentation/git-rev-list.txt
+++ b/Documentation/git-rev-list.txt
@@ -15,6 +15,7 @@ SYNOPSIS
 	     [ \--min-age=timestamp ]
 	     [ \--sparse ]
 	     [ \--no-merges ]
+	     [ \--first-parent ]
 	     [ \--remove-empty ]
 	     [ \--full-history ]
 	     [ \--not ]
@@ -256,6 +257,11 @@ limiting may be applied.
 
 	Do not print commits with more than one parent.
 
+--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.
+
 --not::
 
 	Reverses the meaning of the '{caret}' prefix (or lack thereof)
-- 
1.5.3.7

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

[Junio C Hamano]

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.

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

[Avi Kivity]

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; I can describe my own:

I have a post-receive hook which sends all patches since the last push.  
To avoid sending the constituent commits of a pull, I use --first-parent 
to throw away anything I did not commit directly.

[Initially I used ^origin to cancel out these merges, but that failed as 
soon as I merged from some other branch]

I'm not sure this is what you meant.  Let me know, and I will update the 
patch.

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

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

[Junio C Hamano]

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.

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

[Avi Kivity]

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

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

[Junio C Hamano]

Avi Kivity <avi@qumranet.com> writes:

> 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.
>> ...
> [I assume you mean 0053e902;  I just copied the output of git log --help]

Ahh, sorry, I thought you did "log -S--first-parent".

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

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

[Avi Kivity]

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.

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

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

[Avi Kivity]

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

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

[Junio C Hamano]

Avi Kivity <avi@qumranet.com> writes:

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

Sure.  That's a perfect use case for --first-parent, as you can
afford to rebase.

I wanted to point out that the description needs to be clear
enough that people know the option is applicable only to some
workflow, but not necessarily to their own.  Saying "this option
gives a better overview" as if it always would felt wrong.  For
example for Linus, the option will not give a better overview.

Even in your case, if you merged from others' kvm tree, the
option becomes useless, as you mentioned ("I am careful to keep
everything linear").

If somebody cannot rebase (Linus certainly doesn't, and as a
general rule the top-level integration branch would never be
rebased) but pulls from people, some merges end up as real
merges while some others fast-forward and do not create merge
commits.  In such a history, --first-parent is not very useful.
Some parts of development will see individual commits (i.e. ones
applied by the top-level integrator himself, and the ones built
and committed by a subsystem person whose merge happened to have
fast-forwarded), while other parts will just show merge commits
(i.e. all other merges from subsystem people).

I however think the wording "... the evolution of a particular
branch" lessens my worries a bit, because it hints that the
option is about viewing the history of a topic branch, not the
integration mainline.  Maybe the wording can be made even more
explicit and say something like:

    This option can give a better overview when viewing the
    evolution of a particular topic branch, because merges into
    a topic branch tend to be only about adjusting to updated
    upstream from time to time, and this option allows you to
    ignore the individual commits brought in to your history by
    such a merge.

By the way, the wording "if a branch implements a consistent
fast-forward policy" suggests that forcing a real merge when the
merged branch is a fast-forward of your history is somehow a
good thing, but I think it is backwards to make such an
artificial real merge just to keep --first-parent happy.