{"thread":{"id":"31362","subject":"git checkout -t -B","startedAt":"2012-08-26T07:27:26Z","lastAt":"2012-08-28T20:01:21Z","messageCount":8,"participants":["乙酸鋰","Junio C Hamano","Nguyen Thai Ngoc Duy","Philip Oakley"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"197856","messageId":"CAHtLG6QgnvG6eYEChojY_jB25QWqxis6brbst2ff5FixFLAXAw@mail.gmail.com","threadId":"31362","inReplyTo":null,"subject":"git checkout -t -B","fromName":"乙酸鋰","fromEmail":"ch3cooli@gmail.com","sentAt":"2012-08-26T07:27:26Z","receivedAt":"2012-08-26T07:27:26Z","isPatch":false,"sender":{"key":"ch3cooli@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2804967?v=4"},"body":"Dear Sir,\n\nI want to make current branch abcde a remote tracking branch with origin/abcde.\nSince I am working on current branch abcde, I have to use the force option.\nSo I run\n\ngit checkout -t -B origin/abcde\nworks\n\nbut\ngit checkout -B -t origin/abcde\ndoes not.\n\nCould you document the order of parameters or fix the behaviour?\n\nThanks,\nch3cooli\n"},{"id":"197869","messageId":"7v8vd1v6q2.fsf@alter.siamese.dyndns.org","threadId":"31362","inReplyTo":"CAHtLG6QgnvG6eYEChojY_jB25QWqxis6brbst2ff5FixFLAXAw@mail.gmail.com","subject":"Re: git checkout -t -B","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-08-26T18:38:45Z","receivedAt":"2012-08-26T18:38:45Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"乙酸鋰 <ch3cooli@gmail.com> writes:\n\n> git checkout -t -B origin/abcde\n> works\n>\n> but\n> git checkout -B -t origin/abcde\n> does not.\n>\n> Could you document the order of parameters or fix the behaviour?\n\nIt is crystal clear that -b/-B/--orphan must be followed by the name\nof the branch you are creating from the SYNOPSIS section of the\ndocumentation.\n\n    NAME\n    ----\n    git-checkout - Checkout a branch or paths to the working tree\n\n    SYNOPSIS\n    --------\n    [verse]\n    ...\n    'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<st..\n    ...\n\nHowever, the option description can use some improvement.  It\ncurrently reads:\n\n    -b::\n            Create a new branch named <new_branch> and start it at\n            <start_point>; see linkgit:git-branch[1] for details.\n\nas if it and <new_branch> are freestanding arguments.\n\nI think we should describe the option like this:\n\n    -b <new_branch>::\n            Create a new branch named <new_branch> and start it at\n            <start_point>; see linkgit:git-branch[1] for details.\n\nThe description for \"-B\" and \"--orphan\" options share the same\nissue.\n\nI suspect that documentation for other commands may share this\nissue.  It would be good if somebody can check the option\ndescription section and make sure there is no discrepancy like this\nby comparing it to the SYNOPSIS section (or \"git cmd -h\") for all\nmanual pages.\n\nI'll patch only \"git-checkout.txt\" myself for now; hint, hint.\n\nThanks.\n"},{"id":"197871","messageId":"7v4nnpv6k4.fsf@alter.siamese.dyndns.org","threadId":"31362","inReplyTo":"CAHtLG6QgnvG6eYEChojY_jB25QWqxis6brbst2ff5FixFLAXAw@mail.gmail.com","subject":"[PATCH] doc: \"git checkout -b/-B/--orphan\" always takes a branch name","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-08-26T18:42:19Z","receivedAt":"2012-08-26T18:42:19Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"While the synopsis section makes it clear that the new branch name\nis the parameter to these flags, the option description did not.\n\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n Documentation/git-checkout.txt | 6 +++---\n 1 file changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex c0a96e6..e3270cd 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -84,11 +84,11 @@ entries; instead, unmerged entries are ignored.\n \tWhen checking out paths from the index, check out stage #2\n \t('ours') or #3 ('theirs') for unmerged paths.\n \n--b::\n+-b <new_branch>::\n \tCreate a new branch named <new_branch> and start it at\n \t<start_point>; see linkgit:git-branch[1] for details.\n \n--B::\n+-B <new_branch>::\n \tCreates the branch <new_branch> and start it at <start_point>;\n \tif it already exists, then reset it to <start_point>. This is\n \tequivalent to running \"git branch\" with \"-f\"; see\n@@ -124,7 +124,7 @@ explicitly give a name with '-b' in such a case.\n \t<commit> is not a branch name.  See the \"DETACHED HEAD\" section\n \tbelow for details.\n \n---orphan::\n+--orphan <new_branch>::\n \tCreate a new 'orphan' branch, named <new_branch>, started from\n \t<start_point> and switch to it.  The first commit made on this\n \tnew branch will have no parents and it will be the root of a new\n-- \n1.7.12.252.gef4e272\n"},{"id":"197894","messageId":"CACsJy8A=GooUesw0hJ7AiDO7M3v1Ybbox8+rwWJfn6urJQUUFw@mail.gmail.com","threadId":"31362","inReplyTo":"7v8vd1v6q2.fsf@alter.siamese.dyndns.org","subject":"Re: git checkout -t -B","fromName":"Nguyen Thai Ngoc Duy","fromEmail":"pclouds@gmail.com","sentAt":"2012-08-27T12:20:28Z","receivedAt":"2012-08-27T12:20:28Z","isPatch":false,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Mon, Aug 27, 2012 at 1:38 AM, Junio C Hamano <gitster@pobox.com> wrote:\n> 乙酸鋰 <ch3cooli@gmail.com> writes:\n>\n>> git checkout -t -B origin/abcde\n>> works\n>>\n>> but\n>> git checkout -B -t origin/abcde\n>> does not.\n>>\n>> Could you document the order of parameters or fix the behaviour?\n>\n> It is crystal clear that -b/-B/--orphan must be followed by the name\n> of the branch you are creating from the SYNOPSIS section of the\n> documentation.\n\nYet it's not very clear from the error message:\n\n    fatal: git checkout: updating paths is incompatible with switching branches.\n    Did you intend to checkout 'origin/abcde' which can not be\nresolved as commit?\n\nI wonder if we should reject -t as a value of -[Bb] by adding new\nparseopt flag to reject values starting with '-'. In this case, branch\nnames can't start with '-'. There may be cases where we accept option\nvalue starting with '-', but I suspect the other way is dominant.\n-- \nDuy\n"},{"id":"197919","messageId":"7vk3wks1w4.fsf@alter.siamese.dyndns.org","threadId":"31362","inReplyTo":"CACsJy8A=GooUesw0hJ7AiDO7M3v1Ybbox8+rwWJfn6urJQUUFw@mail.gmail.com","subject":"Re: git checkout -t -B","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-08-27T17:03:39Z","receivedAt":"2012-08-27T17:03:39Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Nguyen Thai Ngoc Duy <pclouds@gmail.com> writes:\n\n> On Mon, Aug 27, 2012 at 1:38 AM, Junio C Hamano <gitster@pobox.com> wrote:\n>> 乙酸鋰 <ch3cooli@gmail.com> writes:\n>>\n>>> git checkout -t -B origin/abcde\n>>> works\n>>>\n>>> but\n>>> git checkout -B -t origin/abcde\n>>> does not.\n>>>\n>>> Could you document the order of parameters or fix the behaviour?\n>>\n>> It is crystal clear that -b/-B/--orphan must be followed by the name\n>> of the branch you are creating from the SYNOPSIS section of the\n>> documentation.\n>\n> Yet it's not very clear from the error message:\n>\n>     fatal: git checkout: updating paths is incompatible with switching branches.\n>     Did you intend to checkout 'origin/abcde' which can not be\n> resolved as commit?\n>\n> I wonder if we should reject -t as a value of -[Bb] by adding new\n> parseopt flag to reject values starting with '-'.\n\nYou should be able to cope with other invalid branch names in the\nsame codepath, but your approach would not help at all if the user\nsaid \"git checkout -B q..f origin/abcde\".  Futzing with parseopt is\nnot a reasonable answer to this one.\n\nIdeally you would want\n\n\tfatal: \"-t\" is not an acceptable name for a branch\n\nin this case; if it is cumbersome to arrange, at the very least, \n\n\tupdating paths is incompatible with checking out the branch \"-t\".\n\nwould be clearer.\n"},{"id":"197947","messageId":"10B409063A944B298250064D2DB0BAB7@PhilipOakley","threadId":"31362","inReplyTo":"7v8vd1v6q2.fsf@alter.siamese.dyndns.org","subject":"Re: git checkout -t -B","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2012-08-27T23:09:44Z","receivedAt":"2012-08-27T23:09:44Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" <gitster@pobox.com>\nSent: Sunday, August 26, 2012 7:38 PM\n> 乙酸鋰 <ch3cooli@gmail.com> writes:\n>\n>> git checkout -t -B origin/abcde\n>> works\n>>\n>> but\n>> git checkout -B -t origin/abcde\n>> does not.\n>>\n>> Could you document the order of parameters or fix the behaviour?\n>\n> It is crystal clear that -b/-B/--orphan must be followed by the name\n> of the branch you are creating from the SYNOPSIS section of the\n> documentation.\n>\n>    NAME\n>    ----\n>    git-checkout - Checkout a branch or paths to the working tree\n>\n>    SYNOPSIS\n>    --------\n>    [verse]\n>    ...\n>    'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>]\n> [<st..\n>    ...\n\nI didn't find it immediately obvious, but with 6/6 hindsight it is \nclearly indicated.\n\nHowever the -t option isn't listed within the synopsis, and does \nimmediately follow the -b & -B in the options list which could confuse \nsome readers who would stick it after the -b ;-)\n\nShould the -t and -l options be shown in the synopsis?\n\n>\n> However, the option description can use some improvement.  It\n> currently reads:\n>\n>    -b::\n>            Create a new branch named <new_branch> and start it at\n>            <start_point>; see linkgit:git-branch[1] for details.\n>\n> as if it and <new_branch> are freestanding arguments.\n>\n> I think we should describe the option like this:\n>\n>    -b <new_branch>::\n>            Create a new branch named <new_branch> and start it at\n>            <start_point>; see linkgit:git-branch[1] for details.\n>\n> The description for \"-B\" and \"--orphan\" options share the same\n> issue.\n>\n> I suspect that documentation for other commands may share this\n> issue.  It would be good if somebody can check the option\n> description section and make sure there is no discrepancy like this\n> by comparing it to the SYNOPSIS section (or \"git cmd -h\") for all\n> manual pages.\n>\n> I'll patch only \"git-checkout.txt\" myself for now; hint, hint.\n\nI searched for all occurrences of '[[' which would indicate a double \noptional argument within the synopsis and only found git-read-tree.\n\nI don't think it has the same problem but I wasn't sure of the priority \norder between the '[]' and '|' selectors in the multi-choice cases.\n\nI haven't seen anything definitive on how one should read the synopsis. \nI thought the order of some option could be exchanged, as rev-parse says \nthat they can be combined (for the right commands).\n\n>\n> Thanks.\n> --\n"},{"id":"197954","messageId":"7vsjb7q5rq.fsf@alter.siamese.dyndns.org","threadId":"31362","inReplyTo":"10B409063A944B298250064D2DB0BAB7@PhilipOakley","subject":"Re: git checkout -t -B","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-08-27T23:22:49Z","receivedAt":"2012-08-27T23:22:49Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" <philipoakley@iee.org> writes:\n\n> I searched for all occurrences of '[[' which would indicate a double \n> optional argument within the synopsis and only found git-read-tree.\n\nDouble-optional?  That is not an issue.\n\nIf an option always takes a parameter, we would have\n\n\tgit cmd [--option parameter]\n\ninstead of one of\n\n\tgit cmd [--option]\n\tgit cmd [--option] parameter\n\tgit cmd [--option] parameter...\n\nand if we had\n\n\t--option::\n        \tThis option distims the parameter ...\n\nthat needs to be updated to\n\n\t--option parameter::\n        \tThis option distims the parameter ...\n"},{"id":"198011","messageId":"87A0826508F54AD6A049B71BC5AD8E0A@PhilipOakley","threadId":"31362","inReplyTo":"7vsjb7q5rq.fsf@alter.siamese.dyndns.org","subject":"Re: git checkout -t -B","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2012-08-28T20:01:21Z","receivedAt":"2012-08-28T20:01:21Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" <gitster@pobox.com>\nSent: Tuesday, August 28, 2012 12:22 AM\n> \"Philip Oakley\" <philipoakley@iee.org> writes:\n>\n>> I searched for all occurrences of '[[' which would indicate a double\n>> optional argument within the synopsis and only found git-read-tree.\n>\n> Double-optional?  That is not an issue.\n\nFor clarification, I was picking out the particular case that I saw in\nthe git checkout syntax of an option (which necessarily starts with a\nfirst `[` ) which is actually then a multi-choice option, so has a\nsecond '[' for that, and then has the required parameter after the\nclosing ']' of the multi-choice, then another ']' after the parameter - \nhence my 'double optional argument' statement.\n\nIt was the multi-choice option, with parameter case that I was looking\nfor, as that multi-choice part would be easy to confuse with the normal\nlist of many options.\n\n>\n> If an option always takes a parameter, we would have\n>\n> git cmd [--option parameter]\n>\n> instead of one of\n>\n> git cmd [--option]\n> git cmd [--option] parameter\n> git cmd [--option] parameter...\n>\n> and if we had\n>\n> --option::\n>        This option distims the parameter ...\n>\n> that needs to be updated to\n>\n> --option parameter::\n>        This option distims the parameter ...\n\nAgreed.\n\nPhilip\n"}]}