{"thread":{"id":"31260","subject":"[PATCH] man: git pull -r is a short for --rebase","startedAt":"2012-08-16T09:50:18Z","lastAt":"2012-08-17T20:22:32Z","messageCount":19,"participants":["Miklos Vajna","Junio C Hamano","Philip Oakley","Johannes Sixt"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"197083","messageId":"20120816095018.GD5489@suse.cz","threadId":"31260","inReplyTo":null,"subject":"[PATCH] man: git pull -r is a short for --rebase","fromName":"Miklos Vajna","fromEmail":"vmiklos@suse.cz","sentAt":"2012-08-16T09:50:18Z","receivedAt":"2012-08-16T09:50:18Z","isPatch":true,"sender":{"key":"vmiklos@frugalware.org","avatar":"https://gravatar.com/avatar/401c1cbbb3a5d13e650c691a2c71d6fd0b80df1a01bc74d9f1972675dd58f2bd?d=mp&s=160"},"body":"---\n Documentation/git-pull.txt | 1 +\n 1 files changed, 1 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt\nindex defb544..67fa5ee 100644\n--- a/Documentation/git-pull.txt\n+++ b/Documentation/git-pull.txt\n@@ -101,6 +101,7 @@ include::merge-options.txt[]\n \n :git-pull: 1\n \n+-r::\n --rebase::\n \tRebase the current branch on top of the upstream branch after\n \tfetching. If there is a remote-tracking branch corresponding to\n-- \n1.7.7\n"},{"id":"197105","messageId":"7v1uj63iyx.fsf@alter.siamese.dyndns.org","threadId":"31260","inReplyTo":"20120816095018.GD5489@suse.cz","subject":"Re: [PATCH] man: git pull -r is a short for --rebase","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-08-16T16:22:14Z","receivedAt":"2012-08-16T16:22:14Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Miklos Vajna writes:\n\n> ---\n> Documentation/git-pull.txt | 1 +\n> 1 files changed, 1 insertions(+), 0 deletions(-)\n>\n> diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt\n> index defb544..67fa5ee 100644\n> --- a/Documentation/git-pull.txt\n> +++ b/Documentation/git-pull.txt\n> @@ -101,6 +101,7 @@ include::merge-options.txt[]\n> \n> :git-pull: 1\n> \n> +-r::\n> --rebase::\n> \tRebase the current branch on top of the upstream branch after\n> \tfetching. If there is a remote-tracking branch corresponding to\n\nI am not sure if this is worth it, as it comes from a natural\n\"abbreviated options\" support, i.e.\n\n\t-r|--r|--re|--reb|--reba|--rebas|--rebase)\n\t\trebase=true\n\nAnd I do not think we particularly want to do\n\n +-r::\n +--r::\n +--re::\n +--reb::\n +--reba::\n +--rebas::\n --rebase::\n Rebase the current...\n\nfor obvious reasons.\n"},{"id":"197113","messageId":"20120816194552.GA3167@suse.cz","threadId":"31260","inReplyTo":"7v1uj63iyx.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] man: git pull -r is a short for --rebase","fromName":"Miklos Vajna","fromEmail":"vmiklos@suse.cz","sentAt":"2012-08-16T19:45:52Z","receivedAt":"2012-08-16T19:45:52Z","isPatch":true,"sender":{"key":"vmiklos@frugalware.org","avatar":"https://gravatar.com/avatar/401c1cbbb3a5d13e650c691a2c71d6fd0b80df1a01bc74d9f1972675dd58f2bd?d=mp&s=160"},"body":"Hi,\n\nOn Thu, Aug 16, 2012 at 09:22:14AM -0700, Junio C Hamano wrote:\n> I am not sure if this is worth it, as it comes from a natural\n> \"abbreviated options\" support, i.e.\n> \n> \t-r|--r|--re|--reb|--reba|--rebas|--rebase)\n> \t\trebase=true\n\nI sent the patch as a (newcomer) friend today asked if it's intentional\nthat -r is undocumented in 'man git-pull'.\n\n> And I do not think we particularly want to do\n> \n> +-r::\n> +--r::\n> +--re::\n> +--reb::\n> +--reba::\n> +--rebas::\n> --rebase::\n> Rebase the current...\n> \n> for obvious reasons.\n\nI agree, however, we already document -q and --quiet, or -v and\n--verbose in the same manpage, so I think it would be consistent to have\n-r there as well.\n\nThanks,\n\nMiklos\n"},{"id":"197115","messageId":"2BB1E674DD214C66B06660612F34109D@PhilipOakley","threadId":"31260","inReplyTo":"7v1uj63iyx.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] man: git pull -r is a short for --rebase","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2012-08-16T19:59:52Z","receivedAt":"2012-08-16T19:59:52Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \nSent: Thursday, August 16, 2012 5:22 PM\n> Miklos Vajna writes:\n>\n>> ---\n>> Documentation/git-pull.txt | 1 +\n>> 1 files changed, 1 insertions(+), 0 deletions(-)\n>>\n>> diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt\n>> index defb544..67fa5ee 100644\n>> --- a/Documentation/git-pull.txt\n>> +++ b/Documentation/git-pull.txt\n>> @@ -101,6 +101,7 @@ include::merge-options.txt[]\n>>\n>> :git-pull: 1\n>>\n>> +-r::\n>> --rebase::\n>> Rebase the current branch on top of the upstream branch after\n>> fetching. If there is a remote-tracking branch corresponding to\n>\n> I am not sure if this is worth it, as it comes from a natural\n> \"abbreviated options\" support, i.e.\n\nI wasn't aware of the \"abbreviated options\" capability. Is meant to be \nin the man pages as I couldn't find it, or is it described differently?\n\nJust adding the '-r' part of the option did seem sensible to me as a \nrelative newbie.\n\n>\n> -r|--r|--re|--reb|--reba|--rebas|--rebase)\n> rebase=true\n>\n> And I do not think we particularly want to do\n>\n> +-r::\n> +--r::\n> +--re::\n> +--reb::\n> +--reba::\n> +--rebas::\n> --rebase::\n> Rebase the current...\n>\n> for obvious reasons.\n> --\n\nThe extra one liner (-r|--r|--re|--reb|--reba|--rebas) would be \nreadable though not pretty, but the seven line version would be \nhorrible!\n\nPhilip \n"},{"id":"197116","messageId":"7vobma1tb9.fsf@alter.siamese.dyndns.org","threadId":"31260","inReplyTo":"20120816194552.GA3167@suse.cz","subject":"Re: [PATCH] man: git pull -r is a short for --rebase","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-08-16T20:21:46Z","receivedAt":"2012-08-16T20:21:46Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Miklos Vajna writes:\n\n> On Thu, Aug 16, 2012 at 09:22:14AM -0700, Junio C Hamano wrote:\n>> I am not sure if this is worth it, as it comes from a natural\n>> \"abbreviated options\" support, i.e.\n>> \n>> \t-r|--r|--re|--reb|--reba|--rebas|--rebase)\n>> \t\trebase=true\n>\n> I sent the patch as a (newcomer) friend today asked if it's intentional\n> that -r is undocumented in 'man git-pull'.\n\nIt is more intentional than it is by accident that we don't.\n\nWe would really think hard to avoid breaking when introducing new\noptions whose long name could begin with \"v\" or \"q\" to avoid\nbreaking \"-v\" and \"-q\" that are common across commands, but it is\nentirely plausible that we want to add a new option whose name\nbegins with \"re\", and at that point, \"-r\" or \"--re\" stop being the\nunique short form to trigger \"git pull --rebase\".\n\nIf somebody figures out \"git pull --reba\" or even \"git pull -r\"\nworks by accident _today_ and gets used to using it, that is fine,\nbut we do not want to guarantee the future. We reserve the right to\nintroduce \"git pull --repurpose\" in a later version of Git, and make\n\"git pull --re\" error out for ambiguity, breaking fingers of such\npeople who relied on \"used to be but no longer\" unique\nabbreviations.\n\n> ...\n> I agree, however, we already document -q and --quiet, or -v and\n> --verbose in the same manpage, so I think it would be consistent to have\n> -r there as well.\n\nSee above.\n\nThanks.\n"},{"id":"197117","messageId":"7vk3wy1t7l.fsf@alter.siamese.dyndns.org","threadId":"31260","inReplyTo":"2BB1E674DD214C66B06660612F34109D@PhilipOakley","subject":"Re: [PATCH] man: git pull -r is a short for --rebase","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-08-16T20:23:58Z","receivedAt":"2012-08-16T20:23:58Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" writes:\n\n> I wasn't aware of the \"abbreviated options\" capability. Is meant to\n> be in the man pages as I couldn't find it, or is it described\n> differently?\n\n$ git help gitcli\n\nis the closest that comes to mind.\n\nIf it is not reachable from \"git help git\", we may want to sprinkle\nsome more linkgit:gitfoo[$n] around the documentation sources. I\ndidn't check.\n"},{"id":"197118","messageId":"7vfw7m1t3l.fsf@alter.siamese.dyndns.org","threadId":"31260","inReplyTo":"7vobma1tb9.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] man: git pull -r is a short for --rebase","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-08-16T20:26:22Z","receivedAt":"2012-08-16T20:26:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> We would really think hard to avoid breaking when introducing new\n> options whose long name could begin with \"v\" or \"q\" to avoid\n> breaking \"-v\" and \"-q\" that are common across commands\n\n[today's lesson for me; do not type while eating]\n\nSorry.\n\n We would really think hard to avoid breaking \"-v\" and \"-q\"\n that are common across commands, when introducing new\n options whose long names could begin with \"v\" or \"q\".\n\nI tried to rephrase/reorganize the sentence a few times by moving\nwords around, but did a terrible job at it.\n"},{"id":"197120","messageId":"502D5D97.3020906@kdbg.org","threadId":"31260","inReplyTo":"7v1uj63iyx.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] man: git pull -r is a short for --rebase","fromName":"Johannes Sixt","fromEmail":"j6t@kdbg.org","sentAt":"2012-08-16T20:52:39Z","receivedAt":"2012-08-16T20:52:39Z","isPatch":true,"sender":{"key":"j6t@kdbg.org","avatar":"https://avatars.githubusercontent.com/u/14810926?v=4"},"body":"Am 16.08.2012 18:22, schrieb Junio C Hamano:\n> Miklos Vajna writes:\n> \n>> ---\n>> Documentation/git-pull.txt | 1 +\n>> 1 files changed, 1 insertions(+), 0 deletions(-)\n>>\n>> diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt\n>> index defb544..67fa5ee 100644\n>> --- a/Documentation/git-pull.txt\n>> +++ b/Documentation/git-pull.txt\n>> @@ -101,6 +101,7 @@ include::merge-options.txt[]\n>> \n>> :git-pull: 1\n>> \n>> +-r::\n>> --rebase::\n>> \tRebase the current branch on top of the upstream branch after\n>> \tfetching. If there is a remote-tracking branch corresponding to\n> \n> I am not sure if this is worth it, as it comes from a natural\n> \"abbreviated options\" support,\n\nAre you sure? This adds '-r', not '--r', i.e., the single-letter option\n'r', to the documentation, which is not something we want to hide, usually.\n\n-- Hannes\n"},{"id":"197121","messageId":"7v4no21raw.fsf@alter.siamese.dyndns.org","threadId":"31260","inReplyTo":"502D5D97.3020906@kdbg.org","subject":"Re: [PATCH] man: git pull -r is a short for --rebase","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-08-16T21:05:11Z","receivedAt":"2012-08-16T21:05:11Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Johannes Sixt writes:\n\n> Are you sure? This adds '-r', not '--r', i.e., the single-letter option\n> 'r', to the documentation, which is not something we want to hide, usually.\n\nI actually think \"--rebase\" squatting on short-and-sweet \"-r\" was an\naccident, and we are saved by not endorsing \"pull -r\" by documenting\nit. We can still use \"-r\" for \"--recurse-submodules\" if that proves\nto give more value than \"--rebase\" to our users.\n\nSo I dunno. I personally do not think either deserves a short-and-sweet\nsingle letter option.\n"},{"id":"197122","messageId":"7vzk5uzgqa.fsf@alter.siamese.dyndns.org","threadId":"31260","inReplyTo":"7v4no21raw.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] man: git pull -r is a short for --rebase","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-08-16T21:09:33Z","receivedAt":"2012-08-16T21:09:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Johannes Sixt writes:\n>\n>> Are you sure? This adds '-r', not '--r', i.e., the single-letter option\n>> 'r', to the documentation, which is not something we want to hide, usually.\n>\n> I actually think \"--rebase\" squatting on short-and-sweet \"-r\" was an\n> accident, and we are saved by not endorsing \"pull -r\" by documenting\n> it. We can still use \"-r\" for \"--recurse-submodules\" if that proves\n> to give more value than \"--rebase\" to our users.\n>\n> So I dunno. I personally do not think either deserves a short-and-sweet\n> single letter option.\n\nI guess the above needs a bit of clarification.\n\nThe reason I do not think \"pull -r\" gives much value to the users to\ntrigger \"pull --rebase\" is because the use of \"pull --rebase\" is\nvery project specific. If you are working on a project that forbids\nmerges, you would _always_ want to run \"pull --rebase\", which means\nyou would likely have it configured and would not be typing from the\ncommand line.\n"},{"id":"197129","messageId":"B7310EA0CC00423EB5B26E3FAAB54541@PhilipOakley","threadId":"31260","inReplyTo":"7vk3wy1t7l.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] man: git pull -r is a short for --rebase","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2012-08-16T22:36:11Z","receivedAt":"2012-08-16T22:36:11Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \nSent: Thursday, August 16, 2012 9:23 PM\n> \"Philip Oakley\" writes:\n>\n>> I wasn't aware of the \"abbreviated options\" capability. Is meant to\n>> be in the man pages as I couldn't find it, or is it described\n>> differently?\n>\n> $ git help gitcli\n>\n> is the closest that comes to mind.\n>\n> If it is not reachable from \"git help git\", we may want to sprinkle\n> some more linkgit:gitfoo[$n] around the documentation sources. I\n> didn't check.\n>\n\nI eventually found a reference in the parse-options API to the fact that\n'Long options may be abbreviated, as long as the abbreviation is\nunambiguous.'\n\nIt may be worth bringing some of those parse-options API basics bullets'\nforward into the gitcli page, if appropriate.\n"},{"id":"197161","messageId":"20120817053826.GB22313@suse.cz","threadId":"31260","inReplyTo":"7vzk5uzgqa.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] man: git pull -r is a short for --rebase","fromName":"Miklos Vajna","fromEmail":"vmiklos@suse.cz","sentAt":"2012-08-17T05:38:26Z","receivedAt":"2012-08-17T05:38:26Z","isPatch":true,"sender":{"key":"vmiklos@frugalware.org","avatar":"https://gravatar.com/avatar/401c1cbbb3a5d13e650c691a2c71d6fd0b80df1a01bc74d9f1972675dd58f2bd?d=mp&s=160"},"body":"On Thu, Aug 16, 2012 at 02:09:33PM -0700, Junio C Hamano wrote:\n> The reason I do not think \"pull -r\" gives much value to the users to\n> trigger \"pull --rebase\" is because the use of \"pull --rebase\" is\n> very project specific. If you are working on a project that forbids\n> merges, you would _always_ want to run \"pull --rebase\", which means\n> you would likely have it configured and would not be typing from the\n> command line.\n\nI agree that it's a bit strange, but based on a quick search, it seems\nmultiple projects already advertise git pull -r (i.e. not --rebase and\nnot a configuration option):\n\nhttp://lilypond.org/doc/v2.15/Documentation/contributor/pulling-and-rebasing\nhttp://wiki.documentfoundation.org/Git_For_LibreOffice_Developers\nhttp://www.wiremod.com/forum/wiremod-general-chat/29517-git-introduction-incomplete-unformatted.html\n\nSo it seems making -r refer to --recurse-submodules would already cause\nquite some pain to users.\n"},{"id":"197164","messageId":"7vk3wyvy67.fsf@alter.siamese.dyndns.org","threadId":"31260","inReplyTo":"20120817053826.GB22313@suse.cz","subject":"Re: [PATCH] man: git pull -r is a short for --rebase","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-08-17T06:18:40Z","receivedAt":"2012-08-17T06:18:40Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Miklos Vajna writes:\n\n> I agree that it's a bit strange, but based on a quick search, it seems\n> multiple projects already advertise git pull -r (i.e. not --rebase and\n> not a configuration option):\n>\n> http://lilypond.org/doc/v2.15/Documentation/contributor/pulling-and-rebasing\n> http://wiki.documentfoundation.org/Git_For_LibreOffice_Developers\n> http://www.wiremod.com/forum/wiremod-general-chat/29517-git-introduction-incomplete-unformatted.html\n>\n> So it seems making -r refer to --recurse-submodules would already cause\n> quite some pain to users.\n\nYuck. I could say it's not our problem that others spread something\nwe didn't document ;-) but I am too nice to say that.\n\nLet's do this, then, but you have to sign off your patch.\n\nThanks for investigating.\n\n-- >8 --\nFrom: Miklos Vajna \nDate: Thu, 16 Aug 2012 11:50:18 +0200\nSubject: [PATCH] man: git pull -r is a short for --rebase\n\nLetting the \"--rebase\" option squat on the short-and-sweet single\nletter option \"-r\" was an unintended accident and was not even\ndocumented, but the short option seems to be already used in the\nwild. Let's document it so that other options that begin with \"r\"\nwould not be tempted to steal it.\n---\n Documentation/git-pull.txt | 1 +\n 1 file changed, 1 insertion(+)\n\ndiff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt\nindex defb544..67fa5ee 100644\n--- a/Documentation/git-pull.txt\n+++ b/Documentation/git-pull.txt\n@@ -101,6 +101,7 @@ include::merge-options.txt[]\n \n :git-pull: 1\n \n+-r::\n --rebase::\n \tRebase the current branch on top of the upstream branch after\n \tfetching. If there is a remote-tracking branch corresponding to\n-- \n1.7.12.rc3.2.gbd120e3\n"},{"id":"197165","messageId":"7vfw7mvy40.fsf_-_@alter.siamese.dyndns.org","threadId":"31260","inReplyTo":"B7310EA0CC00423EB5B26E3FAAB54541@PhilipOakley","subject":"Re* [PATCH] man: git pull -r is a short for --rebase","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-08-17T06:19:59Z","receivedAt":"2012-08-17T06:19:59Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" writes:\n\n> From: \"Junio C Hamano\" \n> Sent: Thursday, August 16, 2012 9:23 PM\n>> \"Philip Oakley\" writes:\n>>\n>>> I wasn't aware of the \"abbreviated options\" capability. Is meant to\n>>> be in the man pages as I couldn't find it, or is it described\n>>> differently?\n>>\n>> $ git help gitcli\n>>\n>> is the closest that comes to mind.\n>>\n>> If it is not reachable from \"git help git\", we may want to sprinkle\n>> some more linkgit:gitfoo[$n] around the documentation sources. I\n>> didn't check.\n>>\n>\n> I eventually found a reference in the parse-options API to the fact that\n> 'Long options may be abbreviated, as long as the abbreviation is\n> unambiguous.'\n>\n> It may be worth bringing some of those parse-options API basics bullets'\n> forward into the gitcli page, if appropriate.\n\nOK, how about doing this? Sort of killing two birds with one stone.\n\n-- >8 --\nSubject: [PATCH] gitcli: describe abbreviation of long options\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/gitcli.txt | 8 ++++++++\n 1 file changed, 8 insertions(+)\n\ndiff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt\nindex ea17f7a..3e72a5d 100644\n--- a/Documentation/gitcli.txt\n+++ b/Documentation/gitcli.txt\n@@ -62,6 +62,14 @@ scripting git:\n `git log -1 HEAD` but write `git log -1 HEAD --`; the former will not work\n if you happen to have a file called `HEAD` in the work tree.\n \n+ * many commands allow a long option \"--option\" to be abbreviated\n+ only to their unique prefix (e.g. if there is no other option\n+ whose name begins with \"opt\", you may be able to spell \"--opt\" to\n+ invoke the \"--option\" flag), but you should fully spell them out\n+ when writing your scripts; later versions of Git may introduce a\n+ new option whose name shares the same prefix, e.g. \"--optimize\",\n+ to make a short prefix that used to be unique no longer unique.\n+\n \n ENHANCED OPTION PARSER\n ----------------------\n-- \n1.7.12.rc3.2.gbd120e3\n"},{"id":"197168","messageId":"20120817070406.GD22313@suse.cz","threadId":"31260","inReplyTo":"7vk3wyvy67.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] man: git pull -r is a short for --rebase","fromName":"Miklos Vajna","fromEmail":"vmiklos@suse.cz","sentAt":"2012-08-17T07:04:07Z","receivedAt":"2012-08-17T07:04:07Z","isPatch":true,"sender":{"key":"vmiklos@frugalware.org","avatar":"https://gravatar.com/avatar/401c1cbbb3a5d13e650c691a2c71d6fd0b80df1a01bc74d9f1972675dd58f2bd?d=mp&s=160"},"body":"On Thu, Aug 16, 2012 at 11:18:40PM -0700, Junio C Hamano wrote:\n> From: Miklos Vajna \n> Date: Thu, 16 Aug 2012 11:50:18 +0200\n> Subject: [PATCH] man: git pull -r is a short for --rebase\n> \n> Letting the \"--rebase\" option squat on the short-and-sweet single\n> letter option \"-r\" was an unintended accident and was not even\n> documented, but the short option seems to be already used in the\n> wild. Let's document it so that other options that begin with \"r\"\n> would not be tempted to steal it.\n\nSigned-off-by: Miklos Vajna \n"},{"id":"197171","messageId":"7v7gsyvuqt.fsf@alter.siamese.dyndns.org","threadId":"31260","inReplyTo":"20120817070406.GD22313@suse.cz","subject":"Re: [PATCH] man: git pull -r is a short for --rebase","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-08-17T07:32:42Z","receivedAt":"2012-08-17T07:32:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Miklos Vajna writes:\n\n> On Thu, Aug 16, 2012 at 11:18:40PM -0700, Junio C Hamano wrote:\n>> From: Miklos Vajna \n>> Date: Thu, 16 Aug 2012 11:50:18 +0200\n>> Subject: [PATCH] man: git pull -r is a short for --rebase\n>> \n>> Letting the \"--rebase\" option squat on the short-and-sweet single\n>> letter option \"-r\" was an unintended accident and was not even\n>> documented, but the short option seems to be already used in the\n>> wild. Let's document it so that other options that begin with \"r\"\n>> would not be tempted to steal it.\n>\n> Signed-off-by: Miklos Vajna \n\nThanks.\n"},{"id":"197205","messageId":"4E6C3BEFBD5345CC9FE0DC3C3AD41788@PhilipOakley","threadId":"31260","inReplyTo":"7vfw7mvy40.fsf_-_@alter.siamese.dyndns.org","subject":"Re: Re* [PATCH] man: git pull -r is a short for --rebase","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2012-08-17T18:22:04Z","receivedAt":"2012-08-17T18:22:04Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \nSent: Friday, August 17, 2012 7:19 AM\n> \"Philip Oakley\" writes:\n>\n>> From: \"Junio C Hamano\" \n>> Sent: Thursday, August 16, 2012 9:23 PM\n>>> \"Philip Oakley\" writes:\n>>>\n>>>> I wasn't aware of the \"abbreviated options\" capability. Is meant \n>>>> to\n>>>> be in the man pages as I couldn't find it, or is it described\n>>>> differently?\n>>>\n>>> $ git help gitcli\n>>>\n>>> is the closest that comes to mind.\n>>>\n>>> If it is not reachable from \"git help git\", we may want to sprinkle\n>>> some more linkgit:gitfoo[$n] around the documentation sources. I\n>>> didn't check.\n>>>\n>>\n>> I eventually found a reference in the parse-options API to the fact \n>> that\n>> 'Long options may be abbreviated, as long as the abbreviation is\n>> unambiguous.'\n>>\n>> It may be worth bringing some of those parse-options API basics \n>> bullets'\n>> forward into the gitcli page, if appropriate.\n>\n> OK, how about doing this? Sort of killing two birds with one stone.\n>\n> -- >8 --\n> Subject: [PATCH] gitcli: describe abbreviation of long options\n>\n> Signed-off-by: Junio C Hamano \n> ---\n> Documentation/gitcli.txt | 8 ++++++++\n> 1 file changed, 8 insertions(+)\n>\n> diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt\n> index ea17f7a..3e72a5d 100644\n> --- a/Documentation/gitcli.txt\n> +++ b/Documentation/gitcli.txt\n> @@ -62,6 +62,14 @@ scripting git:\n> `git log -1 HEAD` but write `git log -1 HEAD --`; the former will \n> not work\n> if you happen to have a file called `HEAD` in the work tree.\n>\n> + * many commands allow a long option \"--option\" to be abbreviated\n> + only to their unique prefix (e.g. if there is no other option\n> + whose name begins with \"opt\", you may be able to spell \"--opt\" to\n> + invoke the \"--option\" flag), but you should fully spell them out\n> + when writing your scripts; later versions of Git may introduce a\n> + new option whose name shares the same prefix, e.g. \"--optimize\",\n> + to make a short prefix that used to be unique no longer unique.\n> +\n>\n> ENHANCED OPTION PARSER\n> ----------------------\n> -- \n> 1.7.12.rc3.2.gbd120e3\n\nAcked-by: Philip Oakley philipoakley@iee.org\n\n I'd also suggest a patch to the 'git' page to bring out the command \nline interface man page, including an emphasis on each of the other \ninformation pages, along the lines of (probably managled/see attached):\n\n -- >8 --\nFrom 655c6e968fc4bb497e7ade90f2d879aadec795d9 Mon Sep 17 00:00:00 2001\nFrom: Philip Oakley \nDate: Fri, 17 Aug 2012 17:53:48 +0100\nSubject: Include 'see gitcli' link, and separate the other links\n\nProvide a link to the git command line interface information,\nand separate for readability, the differing Tutorial, User-manual,\nand CVS instruction links.\n\nSigned-off-by: Philip Oakley \n---\n Documentation/git.txt | 12 +++++++-----\n 1 files changed, 7 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex ca85d1d..75b35ce 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -22,11 +22,13 @@ unusually rich command set that provides both \nhigh-level operations\n and full access to internals.\n\n See linkgit:gittutorial[7] to get started, then see\n-link:everyday.html[Everyday Git] for a useful minimum set of commands, \nand\n-\"man git-commandname\" for documentation of each command. CVS users may\n-also want to read linkgit:gitcvs-migration[7]. See\n-the link:user-manual.html[Git User's Manual] for a more in-depth\n-introduction.\n+link:everyday.html[Everyday Git] for a useful minimum set of commands.\n+Use \"man git-commandname\" for documentation of each command, or \"git \nhelp\".\n+\n+CVS users may also want to read linkgit:gitcvs-migration[7].\n+\n+See the link:user-manual.html[Git User's Manual] for a more in-depth\n+introduction, and linkgit:gitcli[7] for details of git's command line \ninterface.\n\n The '' is either a name of a Git command (see below) or an \nalias\n as defined in the configuration file (see linkgit:git-config[1]).\n-- \n1.7.8.msysgit.0\n\n\n\n\n\n>From 655c6e968fc4bb497e7ade90f2d879aadec795d9 Mon Sep 17 00:00:00 2001\nFrom: Philip Oakley \nDate: Fri, 17 Aug 2012 17:53:48 +0100\nSubject: Include 'see gitcli' link, and separate the other links\n\nProvide a link to the git command line interface information,\nand separate for readability, the differing Tutorial, User-manual,\nand CVS instruction links.\n\nSigned-off-by: Philip Oakley \n---\n Documentation/git.txt | 12 +++++++-----\n 1 files changed, 7 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex ca85d1d..75b35ce 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -22,11 +22,13 @@ unusually rich command set that provides both high-level operations\n and full access to internals.\n \n See linkgit:gittutorial[7] to get started, then see\n-link:everyday.html[Everyday Git] for a useful minimum set of commands, and\n-\"man git-commandname\" for documentation of each command. CVS users may\n-also want to read linkgit:gitcvs-migration[7]. See\n-the link:user-manual.html[Git User's Manual] for a more in-depth\n-introduction.\n+link:everyday.html[Everyday Git] for a useful minimum set of commands.\n+Use \"man git-commandname\" for documentation of each command, or \"git help\".\n+\n+CVS users may also want to read linkgit:gitcvs-migration[7].\n+\n+See the link:user-manual.html[Git User's Manual] for a more in-depth\n+introduction, and linkgit:gitcli[7] for details of git's command line interface.\n \n The '' is either a name of a Git command (see below) or an alias\n as defined in the configuration file (see linkgit:git-config[1]).\n-- \n1.7.8.msysgit.0\n\n"},{"id":"197206","messageId":"7vk3wxti3f.fsf@alter.siamese.dyndns.org","threadId":"31260","inReplyTo":"4E6C3BEFBD5345CC9FE0DC3C3AD41788@PhilipOakley","subject":"Re: Re* [PATCH] man: git pull -r is a short for --rebase","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-08-17T19:48:52Z","receivedAt":"2012-08-17T19:48:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" writes:\n\n> diff --git a/Documentation/git.txt b/Documentation/git.txt\n> index ca85d1d..75b35ce 100644\n> --- a/Documentation/git.txt\n> +++ b/Documentation/git.txt\n> @@ -22,11 +22,13 @@ unusually rich command set that provides both high-level operations\n> and full access to internals.\n> \n> See linkgit:gittutorial[7] to get started, then see\n> -link:everyday.html[Everyday Git] for a useful minimum set of commands, and\n> -\"man git-commandname\" for documentation of each command. CVS users may\n> -also want to read linkgit:gitcvs-migration[7]. See\n> -the link:user-manual.html[Git User's Manual] for a more in-depth\n> -introduction.\n> +link:everyday.html[Everyday Git] for a useful minimum set of commands.\n> +Use \"man git-commandname\" for documentation of each command, or \"git help\".\n> +\n> +CVS users may also want to read linkgit:gitcvs-migration[7].\n> +\n> +See the link:user-manual.html[Git User's Manual] for a more in-depth\n> +introduction, and linkgit:gitcli[7] for details of git's command line interface.\n> \n> The '' is either a name of a Git command (see below) or an alias\n> as defined in the configuration file (see linkgit:git-config[1]).\n\nI would prefer to keep the description section of git(1) not overly\nlong.\n\nThe first paragraph (not much shown above) concisely describes what\nGit is, so that people who were interested in other \"git\" can\nquickly tell that this is not a page to read about it. I think it\nis in good shape.\n\nThe purpose of the second paragraph is to guide people who are not\nready to dive into this page and refer them to other pages with the\nintroductory material, and also tell them that they can come back to\nthis page to learn the set of commands Git offers once they are\nfamiliar with the concepts.\n\nAnd then, before going into the list of commands, we should tell\nthem what we are listing, and where they can find more information.\n\nSo in that sense, we would really want to keep the second paragraph\nshort and to the point. Referring migrating CVS users to another\npage before they get acquainted with Git like the current page does\nis a mistake. On the other hand, gitcli may deserve to be mentioned\nin the third paragraph that gives the reader the sense of the overall\nstructure of the documentation.\n\nThe mention of cvs migration used to be more important in earlier\ndays, but I think it was out of place to have it early in the\ndocument even back then. It probably can be moved down to the\nFURTHER DOCUMENTATION section.\n\nSo how about doing it this way?\n\n-- >8 --\nSubject: [PATCH] Documentation: update the introductory section\n\nThe second paragraph in the git(1) description section were meant to\nguide people who are not ready to dive into this page away from here.\nReferring migrating CVS users to another page before they get\nacquainted with Git was somewhat out of place. Move the reference to\nthe \"FURTHER DOCUMENTATION\" section and push that section down.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/git.txt | 60 +++++++++++++++++++++++++++------------------------\n 1 file changed, 32 insertions(+), 28 deletions(-)\n\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex eb6b2c0..33028a9 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -22,18 +22,17 @@ unusually rich command set that provides both high-level operations\n and full access to internals.\n \n See linkgit:gittutorial[7] to get started, then see\n-link:everyday.html[Everyday Git] for a useful minimum set of commands, and\n-\"man git-commandname\" for documentation of each command. CVS users may\n-also want to read linkgit:gitcvs-migration[7]. See\n-the link:user-manual.html[Git User's Manual] for a more in-depth\n-introduction.\n+link:everyday.html[Everyday Git] for a useful minimum set of\n+commands. The link:user-manual.html[Git User's Manual] has a more\n+in-depth introduction.\n \n-The '' is either a name of a Git command (see below) or an alias\n-as defined in the configuration file (see linkgit:git-config[1]).\n+After you mastered the basic concepts, you can come back to this\n+page to learn what commands git offers. You can learn more about\n+individual git commands with \"git help command\". linkgit:gitcli[7]\n+manual page gives you an overview of the command line command syntax.\n \n-Formatted and hyperlinked version of the latest git\n-documentation can be viewed at\n-`http://git-htmldocs.googlecode.com/git/git.html`.\n+Formatted and hyperlinked version of the latest git documentation\n+can be viewed at `http://git-htmldocs.googlecode.com/git/git.html`.\n \n ifdef::stalenotes[]\n [NOTE]\n@@ -406,24 +405,6 @@ help ...`.\n \tlinkgit:git-replace[1] for more information.\n \n \n-FURTHER DOCUMENTATION\n----------------------\n-\n-See the references above to get started using git. The following is\n-probably more detail than necessary for a first-time user.\n-\n-The link:user-manual.html#git-concepts[git concepts chapter of the\n-user-manual] and linkgit:gitcore-tutorial[7] both provide\n-introductions to the underlying git architecture.\n-\n-See linkgit:gitworkflows[7] for an overview of recommended workflows.\n-\n-See also the link:howto-index.html[howto] documents for some useful\n-examples.\n-\n-The internals are documented in the\n-link:technical/api-index.html[GIT API documentation].\n-\n GIT COMMANDS\n ------------\n \n@@ -843,6 +824,29 @@ The index is also capable of storing multiple entries (called \"stages\")\n for a given pathname. These stages are used to hold the various\n unmerged version of a file when a merge is in progress.\n \n+FURTHER DOCUMENTATION\n+---------------------\n+\n+See the references in the \"description\" section to get started\n+using git. The following is probably more detail than necessary\n+for a first-time user.\n+\n+The link:user-manual.html#git-concepts[git concepts chapter of the\n+user-manual] and linkgit:gitcore-tutorial[7] both provide\n+introductions to the underlying git architecture.\n+\n+See linkgit:gitworkflows[7] for an overview of recommended workflows.\n+\n+See also the link:howto-index.html[howto] documents for some useful\n+examples.\n+\n+The internals are documented in the\n+link:technical/api-index.html[GIT API documentation].\n+\n+Users migrating from CVS may also want to\n+read linkgit:gitcvs-migration[7].\n+\n+\n Authors\n -------\n Git was started by Linus Torvalds, and is currently maintained by Junio\n-- \n1.7.12.rc3.71.ge297db8\n"},{"id":"197207","messageId":"907441D729554B0B8D876AD38B0FE7E0@PhilipOakley","threadId":"31260","inReplyTo":"7vk3wxti3f.fsf@alter.siamese.dyndns.org","subject":"Re: Re* [PATCH] man: git pull -r is a short for --rebase","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2012-08-17T20:22:32Z","receivedAt":"2012-08-17T20:22:32Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \nSent: Friday, August 17, 2012 8:48 PM\n> \"Philip Oakley\" writes:\n>\n>> diff --git a/Documentation/git.txt b/Documentation/git.txt\n>> index ca85d1d..75b35ce 100644\n>> --- a/Documentation/git.txt\n>> +++ b/Documentation/git.txt\n>> @@ -22,11 +22,13 @@ unusually rich command set that provides both\n>> high-level operations\n>> and full access to internals.\n>>\n>> See linkgit:gittutorial[7] to get started, then see\n>> -link:everyday.html[Everyday Git] for a useful minimum set of\n>> commands, and\n>> -\"man git-commandname\" for documentation of each command. CVS users\n>> may\n>> -also want to read linkgit:gitcvs-migration[7]. See\n>> -the link:user-manual.html[Git User's Manual] for a more in-depth\n>> -introduction.\n>> +link:everyday.html[Everyday Git] for a useful minimum set of\n>> commands.\n>> +Use \"man git-commandname\" for documentation of each command, or \"git\n>> help\".\n>> +\n>> +CVS users may also want to read linkgit:gitcvs-migration[7].\n>> +\n>> +See the link:user-manual.html[Git User's Manual] for a more in-depth\n>> +introduction, and linkgit:gitcli[7] for details of git's command\n>> line interface.\n>>\n>> The '' is either a name of a Git command (see below) or an\n>> alias\n>> as defined in the configuration file (see linkgit:git-config[1]).\n>\n> I would prefer to keep the description section of git(1) not overly\n> long.\n>\n> The first paragraph (not much shown above) concisely describes what\n> Git is, so that people who were interested in other \"git\" can\n> quickly tell that this is not a page to read about it. I think it\n> is in good shape.\n>\n> The purpose of the second paragraph is to guide people who are not\n> ready to dive into this page and refer them to other pages with the\n> introductory material, and also tell them that they can come back to\n> this page to learn the set of commands Git offers once they are\n> familiar with the concepts.\n>\n> And then, before going into the list of commands, we should tell\n> them what we are listing, and where they can find more information.\n>\n> So in that sense, we would really want to keep the second paragraph\n> short and to the point. Referring migrating CVS users to another\n> page before they get acquainted with Git like the current page does\n> is a mistake. On the other hand, gitcli may deserve to be mentioned\n> in the third paragraph that gives the reader the sense of the overall\n> structure of the documentation.\n\nCertainly for those learning and in need of help, keeping paragraphs\nshort, to the point, and easy to read is a definate advantage. Once they\nhave found the right command then the documentation can become terse man\npages providing precise details. Your arrangement makes sense.\n\n>\n> The mention of cvs migration used to be more important in earlier\n> days, but I think it was out of place to have it early in the\n> document even back then. It probably can be moved down to the\n> FURTHER DOCUMENTATION section.\n\nTrue.\n\nAt some point (in the future) the method of accessing the \nguides/articles (rather than the commands) should be mentioned \n(somewhere). e.g. that gittutorial can be accessed via 'git \ntutorial --help' or 'git help tutorial', along with 'git k' etc.\n>\n> So how about doing it this way?\n>\nI'm on msysgit so don't have the ascii docs tool chain, so I'm \nvisualising. Ack.\n> -- >8 --\n> Subject: [PATCH] Documentation: update the introductory section\n>\n> The second paragraph in the git(1) description section were meant to\n> guide people who are not ready to dive into this page away from here.\n> Referring migrating CVS users to another page before they get\n> acquainted with Git was somewhat out of place. Move the reference to\n> the \"FURTHER DOCUMENTATION\" section and push that section down.\n>\n> Signed-off-by: Junio C Hamano \n> ---\n> Documentation/git.txt | 60\n> +++++++++++++++++++++++++++------------------------\n> 1 file changed, 32 insertions(+), 28 deletions(-)\n>\n> diff --git a/Documentation/git.txt b/Documentation/git.txt\n> index eb6b2c0..33028a9 100644\n> --- a/Documentation/git.txt\n> +++ b/Documentation/git.txt\n> @@ -22,18 +22,17 @@ unusually rich command set that provides both\n> high-level operations\n> and full access to internals.\n>\n> See linkgit:gittutorial[7] to get started, then see\n> -link:everyday.html[Everyday Git] for a useful minimum set of\n> commands, and\n> -\"man git-commandname\" for documentation of each command. CVS users\n> may\n> -also want to read linkgit:gitcvs-migration[7]. See\n> -the link:user-manual.html[Git User's Manual] for a more in-depth\n> -introduction.\n> +link:everyday.html[Everyday Git] for a useful minimum set of\n> +commands. The link:user-manual.html[Git User's Manual] has a more\n> +in-depth introduction.\n>\n> -The '' is either a name of a Git command (see below) or an\n> alias\n> -as defined in the configuration file (see linkgit:git-config[1]).\n> +After you mastered the basic concepts, you can come back to this\n> +page to learn what commands git offers. You can learn more about\n> +individual git commands with \"git help command\". linkgit:gitcli[7]\n> +manual page gives you an overview of the command line command syntax.\n>\n> -Formatted and hyperlinked version of the latest git\n> -documentation can be viewed at\n> -`http://git-htmldocs.googlecode.com/git/git.html`.\n> +Formatted and hyperlinked version of the latest git documentation\n> +can be viewed at `http://git-htmldocs.googlecode.com/git/git.html`.\n>\n> ifdef::stalenotes[]\n> [NOTE]\n> @@ -406,24 +405,6 @@ help ...`.\n> linkgit:git-replace[1] for more information.\n>\n>\n> -FURTHER DOCUMENTATION\n> ----------------------\n> -\n> -See the references above to get started using git. The following is\n> -probably more detail than necessary for a first-time user.\n> -\n> -The link:user-manual.html#git-concepts[git concepts chapter of the\n> -user-manual] and linkgit:gitcore-tutorial[7] both provide\n> -introductions to the underlying git architecture.\n> -\n> -See linkgit:gitworkflows[7] for an overview of recommended workflows.\n> -\n> -See also the link:howto-index.html[howto] documents for some useful\n> -examples.\n> -\n> -The internals are documented in the\n> -link:technical/api-index.html[GIT API documentation].\n> -\n> GIT COMMANDS\n> ------------\n>\n> @@ -843,6 +824,29 @@ The index is also capable of storing multiple\n> entries (called \"stages\")\n> for a given pathname. These stages are used to hold the various\n> unmerged version of a file when a merge is in progress.\n>\n> +FURTHER DOCUMENTATION\n> +---------------------\n> +\n> +See the references in the \"description\" section to get started\n> +using git. The following is probably more detail than necessary\n> +for a first-time user.\n> +\n> +The link:user-manual.html#git-concepts[git concepts chapter of the\n> +user-manual] and linkgit:gitcore-tutorial[7] both provide\n> +introductions to the underlying git architecture.\n> +\n> +See linkgit:gitworkflows[7] for an overview of recommended workflows.\n> +\n> +See also the link:howto-index.html[howto] documents for some useful\n> +examples.\n> +\n> +The internals are documented in the\n> +link:technical/api-index.html[GIT API documentation].\n> +\n> +Users migrating from CVS may also want to\n> +read linkgit:gitcvs-migration[7].\n> +\n> +\n> Authors\n> -------\n> Git was started by Linus Torvalds, and is currently maintained by\n> Junio\n> -- \n> 1.7.12.rc3.71.ge297db8\n>\nAcked-by: Philip Oakley \n"}]}