* [PATCH] Document git rev-list --first-parent
@ 2007-12-24 8:20 Avi Kivity
2007-12-24 8:30 ` Junio C Hamano
0 siblings, 1 reply; 9+ messages in thread
From: Avi Kivity @ 2007-12-24 8:20 UTC (permalink / raw)
To: git
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
^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: [PATCH] Document git rev-list --first-parent
2007-12-24 8:20 [PATCH] Document git rev-list --first-parent Avi Kivity
@ 2007-12-24 8:30 ` Junio C Hamano
2007-12-24 8:36 ` Avi Kivity
0 siblings, 1 reply; 9+ messages in thread
From: Junio C Hamano @ 2007-12-24 8:30 UTC (permalink / raw)
To: Avi Kivity; +Cc: git
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.
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] Document git rev-list --first-parent
2007-12-24 8:30 ` Junio C Hamano
@ 2007-12-24 8:36 ` Avi Kivity
2007-12-24 9:13 ` Junio C Hamano
0 siblings, 1 reply; 9+ messages in thread
From: Avi Kivity @ 2007-12-24 8:36 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git
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
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] Document git rev-list --first-parent
2007-12-24 8:36 ` Avi Kivity
@ 2007-12-24 9:13 ` Junio C Hamano
2007-12-24 9:40 ` Avi Kivity
0 siblings, 1 reply; 9+ messages in thread
From: Junio C Hamano @ 2007-12-24 9:13 UTC (permalink / raw)
To: Avi Kivity; +Cc: git
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.
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] Document git rev-list --first-parent
2007-12-24 9:13 ` Junio C Hamano
@ 2007-12-24 9:40 ` Avi Kivity
2007-12-24 9:58 ` Junio C Hamano
0 siblings, 1 reply; 9+ messages in thread
From: Avi Kivity @ 2007-12-24 9:40 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git
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
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] Document git rev-list --first-parent
2007-12-24 9:40 ` Avi Kivity
@ 2007-12-24 9:58 ` Junio C Hamano
2007-12-24 10:14 ` Avi Kivity
0 siblings, 1 reply; 9+ messages in thread
From: Junio C Hamano @ 2007-12-24 9:58 UTC (permalink / raw)
To: Avi Kivity; +Cc: git
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.
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] Document git rev-list --first-parent
2007-12-24 9:58 ` Junio C Hamano
@ 2007-12-24 10:14 ` Avi Kivity
2007-12-24 16:37 ` Avi Kivity
2007-12-25 9:35 ` Junio C Hamano
0 siblings, 2 replies; 9+ messages in thread
From: Avi Kivity @ 2007-12-24 10:14 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git
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
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] Document git rev-list --first-parent
2007-12-24 10:14 ` Avi Kivity
@ 2007-12-24 16:37 ` Avi Kivity
2007-12-25 9:35 ` Junio C Hamano
1 sibling, 0 replies; 9+ messages in thread
From: Avi Kivity @ 2007-12-24 16:37 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git
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
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] Document git rev-list --first-parent
2007-12-24 10:14 ` Avi Kivity
2007-12-24 16:37 ` Avi Kivity
@ 2007-12-25 9:35 ` Junio C Hamano
1 sibling, 0 replies; 9+ messages in thread
From: Junio C Hamano @ 2007-12-25 9:35 UTC (permalink / raw)
To: Avi Kivity; +Cc: git
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.
^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2007-12-25 9:35 UTC | newest]
Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2007-12-24 8:20 [PATCH] Document git rev-list --first-parent Avi Kivity
2007-12-24 8:30 ` Junio C Hamano
2007-12-24 8:36 ` Avi Kivity
2007-12-24 9:13 ` Junio C Hamano
2007-12-24 9:40 ` Avi Kivity
2007-12-24 9:58 ` Junio C Hamano
2007-12-24 10:14 ` Avi Kivity
2007-12-24 16:37 ` Avi Kivity
2007-12-25 9:35 ` Junio C Hamano
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).