{"thread":{"id":"11397","subject":"[PATCH] Document git rev-list --first-parent","startedAt":"2007-12-24T08:20:50Z","lastAt":"2007-12-25T09:35:05Z","messageCount":9,"participants":["Avi Kivity","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"64064","messageId":"1198484450-16454-1-git-send-email-avi@qumranet.com","threadId":"11397","inReplyTo":null,"subject":"[PATCH] Document git rev-list --first-parent","fromName":"Avi Kivity","fromEmail":"avi@qumranet.com","sentAt":"2007-12-24T08:20:50Z","receivedAt":"2007-12-24T08:20:50Z","isPatch":true,"sender":{"key":"avi@qumranet.com","avatar":null},"body":"Document git rev-list's --first-parent option. Documentation taken from\ngit log.\n\nSigned-off-by: Avi Kivity \n---\n Documentation/git-rev-list.txt | 6 ++++++\n 1 files changed, 6 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt\nindex a03f9fe..b049086 100644\n--- a/Documentation/git-rev-list.txt\n+++ b/Documentation/git-rev-list.txt\n@@ -15,6 +15,7 @@ SYNOPSIS\n \t [ \\--min-age=timestamp ]\n \t [ \\--sparse ]\n \t [ \\--no-merges ]\n+\t [ \\--first-parent ]\n \t [ \\--remove-empty ]\n \t [ \\--full-history ]\n \t [ \\--not ]\n@@ -256,6 +257,11 @@ limiting may be applied.\n \n \tDo not print commits with more than one parent.\n \n+--first-parent::\n+\tFollow only the first parent commit upon seeing a merge\n+\tcommit. This option gives a better overview of the\n+\tevolution of a particular branch.\n+\n --not::\n \n \tReverses the meaning of the '{caret}' prefix (or lack thereof)\n-- \n1.5.3.7\n"},{"id":"64065","messageId":"7v3atstry4.fsf@gitster.siamese.dyndns.org","threadId":"11397","inReplyTo":"1198484450-16454-1-git-send-email-avi@qumranet.com","subject":"Re: [PATCH] Document git rev-list --first-parent","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-12-24T08:30:59Z","receivedAt":"2007-12-24T08:30:59Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Avi Kivity writes:\n\n> Document git rev-list's --first-parent option. Documentation taken from\n> git log.\n> ...\n> +--first-parent::\n> +\tFollow only the first parent commit upon seeing a merge\n> +\tcommit. This option gives a better overview of the\n> +\tevolution of a particular branch.\n> +\n\nI am afraid that this description is not sufficient. The\nhistory given by --first-parent is useful only in a very limited\nuse case, and the user needs to be aware of it.\n"},{"id":"64066","messageId":"476F6F95.1030506@qumranet.com","threadId":"11397","inReplyTo":"7v3atstry4.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] Document git rev-list --first-parent","fromName":"Avi Kivity","fromEmail":"avi@qumranet.com","sentAt":"2007-12-24T08:36:37Z","receivedAt":"2007-12-24T08:36:37Z","isPatch":true,"sender":{"key":"avi@qumranet.com","avatar":null},"body":"Junio C Hamano wrote:\n> Avi Kivity writes:\n>\n> \n>> Document git rev-list's --first-parent option. Documentation taken from\n>> git log.\n>> ...\n>> +--first-parent::\n>> +\tFollow only the first parent commit upon seeing a merge\n>> +\tcommit. This option gives a better overview of the\n>> +\tevolution of a particular branch.\n>> +\n>> \n>\n> I am afraid that this description is not sufficient. The\n> history given by --first-parent is useful only in a very limited\n> use case, and the user needs to be aware of it.\n> \n\nI don't know which use case you are referring to; I can describe my own:\n\nI have a post-receive hook which sends all patches since the last push. \nTo avoid sending the constituent commits of a pull, I use --first-parent \nto throw away anything I did not commit directly.\n\n[Initially I used ^origin to cancel out these merges, but that failed as \nsoon as I merged from some other branch]\n\nI'm not sure this is what you meant. Let me know, and I will update the \npatch.\n\n-- \nerror compiling committee.c: too many arguments to function\n"},{"id":"64068","messageId":"7vprwwsbey.fsf@gitster.siamese.dyndns.org","threadId":"11397","inReplyTo":"476F6F95.1030506@qumranet.com","subject":"Re: [PATCH] Document git rev-list --first-parent","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-12-24T09:13:25Z","receivedAt":"2007-12-24T09:13:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Avi Kivity writes:\n\n> Junio C Hamano wrote:\n>> Avi Kivity writes:\n>>\n>>> Document git rev-list's --first-parent option. Documentation taken from\n>>> git log.\n>>> ...\n>>> +--first-parent::\n>>> +\tFollow only the first parent commit upon seeing a merge\n>>> +\tcommit. This option gives a better overview of the\n>>> +\tevolution of a particular branch.\n>>> +\n>>>\n>>\n>> I am afraid that this description is not sufficient. The\n>> history given by --first-parent is useful only in a very limited\n>> use case, and the user needs to be aware of it.\n>\n> I don't know which use case you are referring to...\n\nPlease read the commit log message you snarfed the description\nagain.\n\nFirst-parent is useful only if you are the primary integrator\nand do not fast-forward from other people. Only in that case,\nyou will see the overview of \"the primary integration branch\".\nOtherwise you will observe the history viewed by whoever\nhappened to make a merge, which would switch every time you\ncross the fast-forward boundary.\n\nMaking it sound as if it always will give a better overview is\nmisleading.\n"},{"id":"64069","messageId":"476F7EA4.1030001@qumranet.com","threadId":"11397","inReplyTo":"7vprwwsbey.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] Document git rev-list --first-parent","fromName":"Avi Kivity","fromEmail":"avi@qumranet.com","sentAt":"2007-12-24T09:40:52Z","receivedAt":"2007-12-24T09:40:52Z","isPatch":true,"sender":{"key":"avi@qumranet.com","avatar":null},"body":"Junio C Hamano wrote:\n> Avi Kivity writes:\n>\n> \n>> Junio C Hamano wrote:\n>> \n>>> Avi Kivity writes:\n>>>\n>>> \n>>>> Document git rev-list's --first-parent option. Documentation taken from\n>>>> git log.\n>>>> ...\n>>>> +--first-parent::\n>>>> +\tFollow only the first parent commit upon seeing a merge\n>>>> +\tcommit. This option gives a better overview of the\n>>>> +\tevolution of a particular branch.\n>>>> +\n>>>>\n>>>> \n>>> I am afraid that this description is not sufficient. The\n>>> history given by --first-parent is useful only in a very limited\n>>> use case, and the user needs to be aware of it.\n>>> \n>> I don't know which use case you are referring to...\n>> \n>\n> Please read the commit log message you snarfed the description\n> again.\n>\n> \n\n[I assume you mean 0053e902; I just copied the output of git log --help]\n\n> First-parent is useful only if you are the primary integrator\n> and do not fast-forward from other people. Only in that case,\n> you will see the overview of \"the primary integration branch\".\n> Otherwise you will observe the history viewed by whoever\n> happened to make a merge, which would switch every time you\n> cross the fast-forward boundary.\n>\n> \n\nWell, my use case is different. All of the development merges are \nfast-forwards (or plain patch applications); the only multiple-parent \nmerges are pulls I do from the main tree in order to advance the \nbaseline, or from upstream submission branches (which are very \nsimilar). So, for me --first-parent means \"show me actual development, \nnot syncs with upstream or cleanup branches\".\n\n> Making it sound as if it always will give a better overview is\n> misleading.\n> \n\nI'll try to come up with better wording and submit a new patch.\n\n-- \nerror compiling committee.c: too many arguments to function\n"},{"id":"64070","messageId":"7vejdcs9cb.fsf@gitster.siamese.dyndns.org","threadId":"11397","inReplyTo":"476F7EA4.1030001@qumranet.com","subject":"Re: [PATCH] Document git rev-list --first-parent","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-12-24T09:58:12Z","receivedAt":"2007-12-24T09:58:12Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Avi Kivity writes:\n\n> Junio C Hamano wrote:\n>> Avi Kivity writes:\n>>\n>>\n>>> Junio C Hamano wrote:\n>>>\n>>>> Avi Kivity writes:\n>>>>\n>>>>\n>>>>> Document git rev-list's --first-parent option. Documentation taken from\n>>>>> git log.\n>> ...\n> [I assume you mean 0053e902; I just copied the output of git log --help]\n\nAhh, sorry, I thought you did \"log -S--first-parent\".\n\n> Well, my use case is different. All of the development merges are\n> fast-forwards (or plain patch applications); the only multiple-parent\n> merges are pulls I do from the main tree in order to advance the\n> baseline,...\n\nYeah, that is what I meant as a special case. If you submit\npatches and rebase the remainder of your changes to the updated\nupstream (as x.org folks seem to do), then the --first-parent\nhistory will not be your own development but \"the global trunk\nhistory.\" If you are the top-level maintainer and your pull\nsometimes ends up as a fast forward and sometimes a real merge,\nyou will sometimes get a full history of a topic done by\nsomebody else (if that person rebased on top of you) or just a\nsummary single merge (otherwise), and the distinction between\nthese two cases does not have anything to do with whose commits\nthey are (i.e. mine vs others) or the scope of the changes\n(i.e. the trunk history vs side branch development). It would\nnot be as useful as the \"looking at the list of one's own\ncommits while summarizing out others' developments as merge\ncommits\" world view the --first-parent would give you in your\nhistory.\n"},{"id":"64071","messageId":"476F8679.8010706@qumranet.com","threadId":"11397","inReplyTo":"7vejdcs9cb.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] Document git rev-list --first-parent","fromName":"Avi Kivity","fromEmail":"avi@qumranet.com","sentAt":"2007-12-24T10:14:17Z","receivedAt":"2007-12-24T10:14:17Z","isPatch":true,"sender":{"key":"avi@qumranet.com","avatar":null},"body":"Junio C Hamano wrote:\n>> Well, my use case is different. All of the development merges are\n>> fast-forwards (or plain patch applications); the only multiple-parent\n>> merges are pulls I do from the main tree in order to advance the\n>> baseline,...\n>> \n>\n> Yeah, that is what I meant as a special case. If you submit\n> patches and rebase the remainder of your changes to the updated\n> upstream (as x.org folks seem to do), then the --first-parent\n> history will not be your own development but \"the global trunk\n> history.\" If you are the top-level maintainer and your pull\n> sometimes ends up as a fast forward and sometimes a real merge,\n> you will sometimes get a full history of a topic done by\n> somebody else (if that person rebased on top of you) or just a\n> summary single merge (otherwise), and the distinction between\n> these two cases does not have anything to do with whose commits\n> they are (i.e. mine vs others) or the scope of the changes\n> (i.e. the trunk history vs side branch development). It would\n> not be as useful as the \"looking at the list of one's own\n> commits while summarizing out others' developments as merge\n> commits\" world view the --first-parent would give you in your\n> history.\n> \n\nSorry, I'm confused now. I'll try to explain more carefully what I'm doing.\n\nI'm a mid-level maintainer for a particular subsystem (kvm). I merge \npatchsets from others and do my own work, but I am careful to keep \neverything linear (no real merges in the git sense). Every once in a \nwhile I merge from upstream or some other tree, but these are never kvm \ndevelopments. Every merge window I rebase the development branch to \nupstream, removing commits that were later reverted, and merging fixes \ninto the patches that introduce them and push the result to Linus. \nHopefully that's clear as I'm not much of an ascii artist.\n\nSo, for me --first-parent means \"commits to the development branch of \nkvm\", whether by myself or someone else. It specifically excludes kvm \ncommits to mainline, since that would result in a bunch of duplicated \ncommits. But it seems to be quite different from what you're describing.\n\n-- \nerror compiling committee.c: too many arguments to function\n"},{"id":"64078","messageId":"476FE04C.9040408@qumranet.com","threadId":"11397","inReplyTo":"476F8679.8010706@qumranet.com","subject":"Re: [PATCH] Document git rev-list --first-parent","fromName":"Avi Kivity","fromEmail":"avi@qumranet.com","sentAt":"2007-12-24T16:37:32Z","receivedAt":"2007-12-24T16:37:32Z","isPatch":true,"sender":{"key":"avi@qumranet.com","avatar":null},"body":"Avi Kivity wrote:\n> Junio C Hamano wrote:\n>>> Well, my use case is different. All of the development merges are\n>>> fast-forwards (or plain patch applications); the only multiple-parent\n>>> merges are pulls I do from the main tree in order to advance the\n>>> baseline,...\n>>> \n>>\n>> Yeah, that is what I meant as a special case. If you submit\n>> patches and rebase the remainder of your changes to the updated\n>> upstream (as x.org folks seem to do), then the --first-parent\n>> history will not be your own development but \"the global trunk\n>> history.\" If you are the top-level maintainer and your pull\n>> sometimes ends up as a fast forward and sometimes a real merge,\n>> you will sometimes get a full history of a topic done by\n>> somebody else (if that person rebased on top of you) or just a\n>> summary single merge (otherwise), and the distinction between\n>> these two cases does not have anything to do with whose commits\n>> they are (i.e. mine vs others) or the scope of the changes\n>> (i.e. the trunk history vs side branch development). It would\n>> not be as useful as the \"looking at the list of one's own\n>> commits while summarizing out others' developments as merge\n>> commits\" world view the --first-parent would give you in your\n>> history.\n>> \n>\n> Sorry, I'm confused now. I'll try to explain more carefully what I'm \n> doing.\n>\n> I'm a mid-level maintainer for a particular subsystem (kvm). I merge \n> patchsets from others and do my own work, but I am careful to keep \n> everything linear (no real merges in the git sense). Every once in a \n> while I merge from upstream or some other tree, but these are never \n> kvm developments. Every merge window I rebase the development branch \n> to upstream, removing commits that were later reverted, and merging \n> fixes into the patches that introduce them and push the result to \n> Linus. Hopefully that's clear as I'm not much of an ascii artist.\n>\n> So, for me --first-parent means \"commits to the development branch of \n> kvm\", whether by myself or someone else. It specifically excludes kvm \n> commits to mainline, since that would result in a bunch of duplicated \n> commits. But it seems to be quite different from what you're describing.\n>\n\nAnyway, here's what I came up with:\n\n--first-parent::\n Follow only the first parent commit upon seeing a merge\n commit. This option gives a better overview of the\n evolution of a particular branch.\n\n Note that this is only useful if the branch implements a consistent\n fast-forward merge policy. One example is to never do a fast-forward\n merge (so that --first-parent returns strictly local commits). Another\n possible policy is to always fast-forward development related to the \nbranch's\n topic, and only merge synchronizations with upstream or with other\n topic branches.\n\n\n\n\n-- \nerror compiling committee.c: too many arguments to function\n"},{"id":"64091","messageId":"7vwsr3nmly.fsf@gitster.siamese.dyndns.org","threadId":"11397","inReplyTo":"476F8679.8010706@qumranet.com","subject":"Re: [PATCH] Document git rev-list --first-parent","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-12-25T09:35:05Z","receivedAt":"2007-12-25T09:35:05Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Avi Kivity writes:\n\n> I'm a mid-level maintainer for a particular subsystem (kvm). I merge\n> patchsets from others and do my own work, but I am careful to keep\n> everything linear (no real merges in the git sense). Every once in a\n> while I merge from upstream or some other tree, but these are never\n> kvm developments. Every merge window I rebase the development branch\n> to upstream, removing commits that were later reverted, and merging\n> fixes into the patches that introduce them and push the result to\n> Linus. Hopefully that's clear as I'm not much of an ascii artist.\n> So, for me --first-parent means \"commits to the development branch of\n> kvm\", whether by myself or someone else.\n\nSure. That's a perfect use case for --first-parent, as you can\nafford to rebase.\n\nI wanted to point out that the description needs to be clear\nenough that people know the option is applicable only to some\nworkflow, but not necessarily to their own. Saying \"this option\ngives a better overview\" as if it always would felt wrong. For\nexample for Linus, the option will not give a better overview.\n\nEven in your case, if you merged from others' kvm tree, the\noption becomes useless, as you mentioned (\"I am careful to keep\neverything linear\").\n\nIf somebody cannot rebase (Linus certainly doesn't, and as a\ngeneral rule the top-level integration branch would never be\nrebased) but pulls from people, some merges end up as real\nmerges while some others fast-forward and do not create merge\ncommits. In such a history, --first-parent is not very useful.\nSome parts of development will see individual commits (i.e. ones\napplied by the top-level integrator himself, and the ones built\nand committed by a subsystem person whose merge happened to have\nfast-forwarded), while other parts will just show merge commits\n(i.e. all other merges from subsystem people).\n\nI however think the wording \"... the evolution of a particular\nbranch\" lessens my worries a bit, because it hints that the\noption is about viewing the history of a topic branch, not the\nintegration mainline. Maybe the wording can be made even more\nexplicit and say something like:\n\n This option can give a better overview when viewing the\n evolution of a particular topic branch, because merges into\n a topic branch tend to be only about adjusting to updated\n upstream from time to time, and this option allows you to\n ignore the individual commits brought in to your history by\n such a merge.\n\nBy the way, the wording \"if a branch implements a consistent\nfast-forward policy\" suggests that forcing a real merge when the\nmerged branch is a fast-forward of your history is somehow a\ngood thing, but I think it is backwards to make such an\nartificial real merge just to keep --first-parent happy.\n"}]}