{"thread":{"id":"33869","subject":"[RFC/PATCH 1/2] Doc rebase: Describe rebase as excluding merge commits","startedAt":"2013-05-19T11:52:07Z","lastAt":"2013-05-20T22:29:05Z","messageCount":8,"participants":["Philip Oakley","Jonathan Nieder","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"217888","messageId":"1368964329-1600-1-git-send-email-philipoakley@iee.org","threadId":"33869","inReplyTo":null,"subject":"[RFC/PATCH 0/2] Improve rebase documenation","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2013-05-19T11:52:07Z","receivedAt":"2013-05-19T11:52:07Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Recent discussions have shown that rebase isn't as well understood as\nas perhaps it should be for the basic user. \n\nAdd a softer introductory paragraph to the man page description, and\nin the second patch, add a second paragraph explaining the build up of\nthe command so that users have a historical context in which to\nrationalise the command structure.\n\nThe second patch/paragraph will probably need the quoting checking as\nto which are quoting the generic command and which are the same text\nas a command example.\n\nBasic wording is borrowed from on-list clarifications.\n\nPhilip Oakley (2):\n  Doc rebase: Describe rebase as excluding merge commits\n  Doc rebase: describe the priority of published work\n\n Documentation/git-rebase.txt | 10 ++++++++++\n 1 file changed, 10 insertions(+)\n\n-- \n1.8.1.msysgit.1\n"},{"id":"217887","messageId":"1368964329-1600-2-git-send-email-philipoakley@iee.org","threadId":"33869","inReplyTo":"1368964329-1600-1-git-send-email-philipoakley@iee.org","subject":"[RFC/PATCH 1/2] Doc rebase: Describe rebase as excluding merge commits","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2013-05-19T11:52:08Z","receivedAt":"2013-05-19T11:52:08Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Describe rebase in the description section.\n\nInclude a softer paraphrased version from the crytic, well-loved,\nbut sometimes parodied, Name description, and tell users that merge\ncommits are excluded by default.\n\nSigned-off-by: Philip Oakley <philipoakley@iee.org>\n\n---\n\nhttp://article.gmane.org/gmane.comp.version-control.git/217410\nhttp://article.gmane.org/gmane.comp.version-control.git/217495\n---\n Documentation/git-rebase.txt | 4 ++++\n 1 file changed, 4 insertions(+)\n\ndiff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\nindex aca8405..87a8095 100644\n--- a/Documentation/git-rebase.txt\n+++ b/Documentation/git-rebase.txt\n@@ -16,6 +16,10 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n+'git rebase' will transfer local commits, excluding merge commits\n+by default, to the head of the branch's upstream, or onto a new base\n+if given.\n+\n If <branch> is specified, 'git rebase' will perform an automatic\n `git checkout <branch>` before doing anything else.  Otherwise\n it remains on the current branch.\n-- \n1.8.1.msysgit.1\n"},{"id":"217889","messageId":"1368964329-1600-3-git-send-email-philipoakley@iee.org","threadId":"33869","inReplyTo":"1368964329-1600-1-git-send-email-philipoakley@iee.org","subject":"[RFC/PATCH 2/2] Doc rebase: describe the priority of published work","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2013-05-19T11:52:09Z","receivedAt":"2013-05-19T11:52:09Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Give details of the implied priority in the description section.\n\nSigned-off-by: Philip Oakley <philipoakley@iee.org>\n---\nwording based on:\nhttp://article.gmane.org/gmane.comp.version-control.git/222581\nhttp://article.gmane.org/gmane.comp.version-control.git/223816\nhttp://article.gmane.org/gmane.comp.version-control.git/217410\nhttp://article.gmane.org/gmane.comp.version-control.git/222763\n---\n Documentation/git-rebase.txt | 6 ++++++\n 1 file changed, 6 insertions(+)\n\ndiff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\nindex 87a8095..24d16ef 100644\n--- a/Documentation/git-rebase.txt\n+++ b/Documentation/git-rebase.txt\n@@ -20,6 +20,12 @@ DESCRIPTION\n by default, to the head of the branch's upstream, or onto a new base\n if given.\n \n+In its minimal form, having built locally on the (current) branch,\n+use `git rebase` to catch up with its published upstream state to\n+create a new linear history. Importantly, `git rebase` is a way to\n+replay your work on top of the work of others. It is not about\n+integrating other people's changes into your work.\n+\n If <branch> is specified, 'git rebase' will perform an automatic\n `git checkout <branch>` before doing anything else.  Otherwise\n it remains on the current branch.\n-- \n1.8.1.msysgit.1\n"},{"id":"217925","messageId":"20130519180804.GE3362@elie.Belkin","threadId":"33869","inReplyTo":"1368964329-1600-2-git-send-email-philipoakley@iee.org","subject":"Re: [RFC/PATCH 1/2] Doc rebase: Describe rebase as excluding merge commits","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2013-05-19T18:08:04Z","receivedAt":"2013-05-19T18:08:04Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Philip Oakley wrote:\n\n> Describe rebase in the description section.\n\nIt already does that. :)  I think you mean \"start with a summary\",\nwhich is a valuable improvement.\n\n> Include a softer paraphrased version from the crytic, well-loved,\n> but sometimes parodied, Name description, and tell users that merge\n> commits are excluded by default.\n\nI don't really follow this paragraph.  Are you saying \"The NAME line\nis cryptic, but let's copy it anyway, since it is better than nothing\"?\n\n[...]\n> --- a/Documentation/git-rebase.txt\n> +++ b/Documentation/git-rebase.txt\n> @@ -16,6 +16,10 @@ SYNOPSIS\n>  \n>  DESCRIPTION\n>  -----------\n> +'git rebase' will transfer local commits, excluding merge commits\n> +by default, to the head of the branch's upstream, or onto a new base\n> +if given.\n> +\n\nNot about this patch, but some day it would be nice to standardize on\none tense for the DESCRIPTION sections of manpages.  Some git commands\nuse the imperative (\"Reply local commits, excluding merge commits, on\ntop of ...\"), some use the present indicative (\"Replays local commits,\nexcluding merge commits, ...\"), and some use the future (\"Will replay\nlocal commits, excluding merge commits, ...\").\n\nThe traditional tense for Unix manpages is the present indicative.\nBut you are right to match the rest of the description here.\n\n>  If <branch> is specified, 'git rebase' will perform an automatic\n>  `git checkout <branch>` before doing anything else.  Otherwise\n>  it remains on the current branch.\n\nThe description has become very long by now.  I wonder if it's\npossible to break it into chunks, like so?\n\n\tDESCRIPTION\n\t-----------\n\t<brief description of the purpose of the command, including some token\n\tmention of *why* a user would want to use it (e.g., \"so that the patches\n\tapply cleanly to their new base\").>\n\n\tIt proceeds using the following steps:\n\n\t 1. If <branch> is specified, ...\n\t 2. Decides which commits will need to be applied.\n\t    These are plain, non-merge commits that are ancestors of HEAD but\n\t    not of <upstream>.\n\t 3. Checks out <upstream>.  (<Explanation that technically it\n\t    detaches HEAD at this step.>)\n\t 4. Reapplies the commits listed on step (2), one by one, in order.\n\t    If merge failures are encountered, the program will exit and allow\n\t    the user to resolve them and resume or cancel the rebase.  See\n\t    the RESPONDING TO MERGE CONFLICTS section below for details.\n\t 5. Once all of the commits from step (2) have been applied, updates\n\t    <branch> to point to the new HEAD.\n\n\tThe result is an updated <branch> that ...\n\n\tOPTIONS\n\t-------\n\t...\n\n\tEXAMPLES\n\t--------\n\tAssume the following history exists and the current branch is \"topic\":\n\t...\n\nDescription of specific options like \"--preserve-merges\" and \"--onto\"\ncould move out of the DESCRIPTION section and to the OPTIONS section.\n\nWhat do you think?\n\nThanks,\nJonathan\n"},{"id":"217950","messageId":"3E0A16E68BA845B5A1FFA22E066E59B1@PhilipOakley","threadId":"33869","inReplyTo":"20130519180804.GE3362@elie.Belkin","subject":"Re: [RFC/PATCH 1/2] Doc rebase: Describe rebase as excluding merge commits","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2013-05-19T22:41:58Z","receivedAt":"2013-05-19T22:41:58Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Jonathan Nieder\" <jrnieder@gmail.com>\nSent: Sunday, May 19, 2013 7:08 PM\n> Philip Oakley wrote:\n>\n>> Describe rebase in the description section.\n>\n> It already does that. :)  I think you mean \"start with a summary\",\n> which is a valuable improvement.\nYes.\n\n>\n>> Include a softer paraphrased version from the crytic, well-loved,\n>> but sometimes parodied, Name description, and tell users that merge\n>> commits are excluded by default.\n>\n> I don't really follow this paragraph.  Are you saying \"The NAME line\n> is cryptic, but let's copy it anyway, since it is better than \n> nothing\"?\n\nI was keeping the 'cryptic/esoteric' NAME line, because it is commented \non in a few blogs [1]. It is accurate but let's not spoil those blogs...\n\nThe fundamental reason for the update was to introduce 'somewhere'  in \nthe text the \"excluding merge commits by default\" note, and I couldn't \nfind an easy way of updating the NAME line, and then realised a softer \nintroduction wiould kill two birds with one stone.\n>\n> [...]\n>> --- a/Documentation/git-rebase.txt\n>> +++ b/Documentation/git-rebase.txt\n>> @@ -16,6 +16,10 @@ SYNOPSIS\n>>\n>>  DESCRIPTION\n>>  -----------\n>> +'git rebase' will transfer local commits, excluding merge commits\n>> +by default, to the head of the branch's upstream, or onto a new base\n>> +if given.\n>> +\n>\n> Not about this patch, but some day it would be nice to standardize on\n> one tense for the DESCRIPTION sections of manpages.  Some git commands\n> use the imperative (\"Reply local commits, excluding merge commits, on\n> top of ...\"), some use the present indicative (\"Replays local commits,\n> excluding merge commits, ...\"), and some use the future (\"Will replay\n> local commits, excluding merge commits, ...\").\n>\n> The traditional tense for Unix manpages is the present indicative.\n> But you are right to match the rest of the description here.\n>\n>>  If <branch> is specified, 'git rebase' will perform an automatic\n>>  `git checkout <branch>` before doing anything else.  Otherwise\n>>  it remains on the current branch.\n>\n> The description has become very long by now.  I wonder if it's\n> possible to break it into chunks, like so?\n>\n> DESCRIPTION\n> -----------\n> <brief description of the purpose of the command, including some token\n> mention of *why* a user would want to use it (e.g., \"so that the \n> patches\n> apply cleanly to their new base\").>\n>\n> It proceeds using the following steps:\n>\n> 1. If <branch> is specified, ...\n> 2. Decides which commits will need to be applied.\n>     These are plain, non-merge commits that are ancestors of HEAD but\n>     not of <upstream>.\n> 3. Checks out <upstream>.  (<Explanation that technically it\n>     detaches HEAD at this step.>)\n> 4. Reapplies the commits listed on step (2), one by one, in order.\n>     If merge failures are encountered, the program will exit and allow\n>     the user to resolve them and resume or cancel the rebase.  See\n>     the RESPONDING TO MERGE CONFLICTS section below for details.\n> 5. Once all of the commits from step (2) have been applied, updates\n>     <branch> to point to the new HEAD.\n>\n> The result is an updated <branch> that ...\n>\n> OPTIONS\n> -------\n> ...\n>\n> EXAMPLES\n> --------\n> Assume the following history exists and the current branch is \"topic\":\n> ...\n>\n> Description of specific options like \"--preserve-merges\" and \"--onto\"\n> could move out of the DESCRIPTION section and to the OPTIONS section.\n>\n> What do you think?\n\nIt's probably something I'd need help on (to ensure correctness). I'll \nhave a go based on your suggestions in the next few days.\n\n>\n> Thanks,\n> Jonathan\n> --\n\n[1] http://steveko.wordpress.com/2012/02/24/10-things-i-hate-about-git/ \nsection 3 'update'. \n"},{"id":"217955","messageId":"7v1u92xnuw.fsf@alter.siamese.dyndns.org","threadId":"33869","inReplyTo":"20130519180804.GE3362@elie.Belkin","subject":"Re: [RFC/PATCH 1/2] Doc rebase: Describe rebase as excluding merge commits","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-05-20T04:43:35Z","receivedAt":"2013-05-20T04:43:35Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder <jrnieder@gmail.com> writes:\n\n> Philip Oakley wrote:\n>\n>> Describe rebase in the description section.\n>\n> It already does that. :)  I think you mean \"start with a summary\",\n> which is a valuable improvement.\n\nIt indeed is a good idea to give the \"high-level introduction\" at\nthe very beginning, but I do not think it should describe only one\nof the three major modes of \"git rebase\" (i.e. no -m, no -i), like\nthe proposed patch text does.  We should instead say what it is used\nfor and why the user would want to use it that is common across\nthese modes at a very high level.\n\n> \tDESCRIPTION\n> \t-----------\n> \t<brief description of the purpose of the command, including some token\n> \tmention of *why* a user would want to use it (e.g., \"so that the patches\n> \tapply cleanly to their new base\").>\n\nExactly.\n"},{"id":"218005","messageId":"2F59222ECBA14673815BF42E6A7CE5A5@PhilipOakley","threadId":"33869","inReplyTo":"7v1u92xnuw.fsf@alter.siamese.dyndns.org","subject":"Re: [RFC/PATCH 1/2] Doc rebase: Describe rebase as excluding merge commits","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2013-05-20T21:55:21Z","receivedAt":"2013-05-20T21:55:21Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" <gitster@pobox.com>\nSent: Monday, May 20, 2013 5:43 AM\n> Jonathan Nieder <jrnieder@gmail.com> writes:\n>\n>> Philip Oakley wrote:\n>>\n>>> Describe rebase in the description section.\n>>\n>> It already does that. :)  I think you mean \"start with a summary\",\n>> which is a valuable improvement.\n>\n> It indeed is a good idea to give the \"high-level introduction\" at\n> the very beginning, but I do not think it should describe only one\n> of the three major modes of \"git rebase\" (i.e. no -m, no -i), like\n> the proposed patch text does.  We should instead say what it is used\n> for and why the user would want to use it that is common across\n> these modes at a very high level.\n\nThat would repeat the NAME issue (of trying too hard to be exact & \nprecise). This introductory text is that \"summary\". The patch 2/2 should \nbe the one for the extra detail of the various whys and wherefores - at \nleast that was my intent.\n\n>\n>> DESCRIPTION\n>> -----------\n>> <brief description of the purpose of the command, including some \n>> token\n>> mention of *why* a user would want to use it (e.g., \"so that the \n>> patches\n>> apply cleanly to their new base\").>\n>\n> Exactly.\n> --\n"},{"id":"218008","messageId":"7vwqqtthe6.fsf@alter.siamese.dyndns.org","threadId":"33869","inReplyTo":"2F59222ECBA14673815BF42E6A7CE5A5@PhilipOakley","subject":"Re: [RFC/PATCH 1/2] Doc rebase: Describe rebase as excluding merge commits","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-05-20T22:29:05Z","receivedAt":"2013-05-20T22:29:05Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" <philipoakley@iee.org> writes:\n\n> From: \"Junio C Hamano\" <gitster@pobox.com>\n> Sent: Monday, May 20, 2013 5:43 AM\n>> Jonathan Nieder <jrnieder@gmail.com> writes:\n>>\n>>> Philip Oakley wrote:\n>>>\n>>>> Describe rebase in the description section.\n>>>\n>>> It already does that. :)  I think you mean \"start with a summary\",\n>>> which is a valuable improvement.\n>>\n>> It indeed is a good idea to give the \"high-level introduction\" at\n>> the very beginning, but I do not think it should describe only one\n>> of the three major modes of \"git rebase\" (i.e. no -m, no -i), like\n>> the proposed patch text does.  We should instead say what it is used\n>> for and why the user would want to use it that is common across\n>> these modes at a very high level.\n>\n> That would repeat the NAME issue (of trying too hard to be exact &\n> precise). This introductory text is that \"summary\".\n\nIf that is \"summary\", it should never talk about \"skips merges\",\nwhich only applies to the mode without -m, no?\n\nThe highest level view of what the command is for (the motivation\nwhy the user would want to consider learning how to use the command)\nis \"You have a history built on top of some commit, and you want to\nrebuild the history on top of another commit, e.g. you earlier built\non the tip of a branch that has some other work, and you want to\nrebuild the history on top of the updated tip of that other branch\".\n\nThe details of how the history is \"rebuilt\" can differ while using\nvarious modes of operation.  Some may skip merges, some may try to\npreserve the topology, some may even let you insert new commits by\nletting you tell it to stop in the middle.  That is not \"summary\"\nbut is part of mode specific description.\n"}]}