{"thread":{"id":"32366","subject":"[PATCH 0/2] Documentation: clarify usage of checkout","startedAt":"2012-12-17T06:45:00Z","lastAt":"2012-12-18T16:43:38Z","messageCount":23,"participants":["Chris Rorvick","Junio C Hamano","Andrew Ardill","Johannes Sixt","Philip Oakley"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"205011","messageId":"1355726702-27974-1-git-send-email-chris@rorvick.com","threadId":"32366","inReplyTo":null,"subject":"[PATCH 0/2] Documentation: clarify usage of checkout","fromName":"Chris Rorvick","fromEmail":"chris@rorvick.com","sentAt":"2012-12-17T06:45:00Z","receivedAt":"2012-12-17T06:45:00Z","isPatch":true,"sender":{"key":"chris@rorvick.com","avatar":"https://avatars.githubusercontent.com/u/824726?v=4"},"body":"This is response to the questions posed in:\n\n http://thread.gmane.org/gmane.comp.version-control.git/211624\n\nIt doesn't seem like the behavior implemented in 70c9ac2 is documented.\n\nChris Rorvick (2):\n Documentation/git-checkout.txt: clarify usage\n Documentation/git-checkout.txt: document 70c9ac2 behavior\n\n Documentation/git-checkout.txt | 34 +++++++++++++++++++++++++---------\n 1 file changed, 25 insertions(+), 9 deletions(-)\n\n-- \n1.8.1.rc1.203.g1ddc124\n"},{"id":"205013","messageId":"1355726702-27974-2-git-send-email-chris@rorvick.com","threadId":"32366","inReplyTo":"1355726702-27974-1-git-send-email-chris@rorvick.com","subject":"[PATCH 1/2] Documentation/git-checkout.txt: clarify usage","fromName":"Chris Rorvick","fromEmail":"chris@rorvick.com","sentAt":"2012-12-17T06:45:01Z","receivedAt":"2012-12-17T06:45:01Z","isPatch":true,"sender":{"key":"chris@rorvick.com","avatar":"https://avatars.githubusercontent.com/u/824726?v=4"},"body":"The forms of checkout that do not take a path are lumped together in the\nDESCRIPTION section, but the description for this group is dominated by\nexplanation of the -b|-B form. Split these apart for more clarity.\n\nSigned-off-by: Chris Rorvick \n---\n Documentation/git-checkout.txt | 26 +++++++++++++++++---------\n 1 file changed, 17 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex 7958a47..a47555c 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -22,17 +22,18 @@ also update `HEAD` to set the specified branch as the current\n branch.\n \n 'git checkout' []::\n+\n+\tUpdate the index, working tree, and HEAD to reflect the\n+\tspecified branch.\n+\n 'git checkout' -b|-B []::\n-'git checkout' [--detach] []::\n \n-\tThis form switches branches by updating the index, working\n-\ttree, and HEAD to reflect the specified branch or commit.\n-+\n-If `-b` is given, a new branch is created as if linkgit:git-branch[1]\n-were called and then checked out; in this case you can\n-use the `--track` or `--no-track` options, which will be passed to\n-'git branch'. As a convenience, `--track` without `-b` implies branch\n-creation; see the description of `--track` below.\n+\tSpecifying `-b` causes a new branch to be created as if\n+\tlinkgit:git-branch[1] were called and then checked out. In\n+\tthis case you can use the `--track` or `--no-track` options,\n+\twhich will be passed to 'git branch'. As a convenience,\n+\t`--track` without `-b` implies branch creation; see the\n+\tdescription of `--track` below.\n +\n If `-B` is given, is created if it doesn't exist; otherwise, it\n is reset. This is the transactional equivalent of\n@@ -45,6 +46,13 @@ $ git checkout \n that is to say, the branch is not reset/created unless \"git checkout\" is\n successful.\n \n+'git checkout' [--detach] []::\n+\n+\tUpdate the index and working tree to reflect the specified\n+\tcommit and set HEAD to point directly to (see\n+\t\"DETACHED HEAD\" section.) Passing `--detach` forces this\n+\tbehavior even if is a branch.\n+\n 'git checkout' [-p|--patch] [] [--] ...::\n \n \tWhen or `--patch` are given, 'git checkout' does *not*\n-- \n1.8.1.rc1.203.g1ddc124\n"},{"id":"205012","messageId":"1355726702-27974-3-git-send-email-chris@rorvick.com","threadId":"32366","inReplyTo":"1355726702-27974-1-git-send-email-chris@rorvick.com","subject":"[PATCH 2/2] Documentation/git-checkout.txt: document 70c9ac2 behavior","fromName":"Chris Rorvick","fromEmail":"chris@rorvick.com","sentAt":"2012-12-17T06:45:02Z","receivedAt":"2012-12-17T06:45:02Z","isPatch":true,"sender":{"key":"chris@rorvick.com","avatar":"https://avatars.githubusercontent.com/u/824726?v=4"},"body":"Document the behavior implemented in 70c9ac2 (DWIM \"git checkout\nfrotz\" to \"git checkout -b frotz origin/frotz\").\n\nSigned-off-by: Chris Rorvick \n---\n Documentation/git-checkout.txt | 8 ++++++++\n 1 file changed, 8 insertions(+)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex a47555c..db89cf7 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -25,6 +25,14 @@ branch.\n \n \tUpdate the index, working tree, and HEAD to reflect the\n \tspecified branch.\n++\n+If is not found but there does exist a tracking branch in\n+exactly one remote (call it ) with a matching name, treat as\n+equivalent to\n++\n+------------\n+$ git checkout -b --track /\n+------------\n \n 'git checkout' -b|-B []::\n \n-- \n1.8.1.rc1.203.g1ddc124\n"},{"id":"205020","messageId":"7vhanlnnz7.fsf@alter.siamese.dyndns.org","threadId":"32366","inReplyTo":"1355726702-27974-2-git-send-email-chris@rorvick.com","subject":"Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-12-17T07:21:00Z","receivedAt":"2012-12-17T07:21:00Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Chris Rorvick writes:\n\n> The forms of checkout that do not take a path are lumped together in the\n> DESCRIPTION section, but the description for this group is dominated by\n> explanation of the -b|-B form. Split these apart for more clarity.\n>\n> Signed-off-by: Chris Rorvick \n> ---\n> Documentation/git-checkout.txt | 26 +++++++++++++++++---------\n> 1 file changed, 17 insertions(+), 9 deletions(-)\n>\n> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\n> index 7958a47..a47555c 100644\n> --- a/Documentation/git-checkout.txt\n> +++ b/Documentation/git-checkout.txt\n> @@ -22,17 +22,18 @@ also update `HEAD` to set the specified branch as the current\n> branch.\n> \n> 'git checkout' []::\n> +\n> +\tUpdate the index, working tree, and HEAD to reflect the\n> +\tspecified branch.\n\nThis is to \"check out the branch\" ;-)\n\nBut of course, we cannot define \"checkout\" in terms of \"checkout\",\nso we need to phrase it without saying \"checkout\" and explain what\nit *means* to check out the branch.\n\nI am not sure \"Reflect\" is a good word. Making the result similar\nto the branch is only one aspect of the act of checking out the\nbranch. The other equally important aspect is that this is done to\nadvance the history of the branch.\n\nPerhaps...\n\n\tPrepare to work on building new history on , by\n\tpointing the HEAD to the branch and updating the index and\n\tthe files in the working tree. Local modifications to the\n\tfiles in the working tree are kept, so that they can be\n\tcommitted on the .\n\n> 'git checkout' -b|-B []::\n> \n> +\tSpecifying `-b` causes a new branch to be created as if\n> +\tlinkgit:git-branch[1] were called and then checked out. In\n> +\tthis case you can use the `--track` or `--no-track` options,\n> +\twhich will be passed to 'git branch'. As a convenience,\n> +\t`--track` without `-b` implies branch creation; see the\n> +\tdescription of `--track` below.\n> +\n> If `-B` is given, is created if it doesn't exist; otherwise, it\n> is reset. This is the transactional equivalent of\n> @@ -45,6 +46,13 @@ $ git checkout \n> that is to say, the branch is not reset/created unless \"git checkout\" is\n> successful.\n> \n> +'git checkout' [--detach] []::\n> +\n> +\tUpdate the index and working tree to reflect the specified\n> +\tcommit and set HEAD to point directly to (see\n> +\t\"DETACHED HEAD\" section.) Passing `--detach` forces this\n> +\tbehavior even if is a branch.\n\n\tPrepare to work on building new history on top of ,\n by detaching HEAD at the commit and ...(likewise)...\n"},{"id":"205021","messageId":"7vd2y9nnyb.fsf@alter.siamese.dyndns.org","threadId":"32366","inReplyTo":"1355726702-27974-3-git-send-email-chris@rorvick.com","subject":"Re: [PATCH 2/2] Documentation/git-checkout.txt: document 70c9ac2 behavior","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-12-17T07:21:32Z","receivedAt":"2012-12-17T07:21:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Chris Rorvick writes:\n\n> Document the behavior implemented in 70c9ac2 (DWIM \"git checkout\n> frotz\" to \"git checkout -b frotz origin/frotz\").\n>\n> Signed-off-by: Chris Rorvick \n> ---\n> Documentation/git-checkout.txt | 8 ++++++++\n> 1 file changed, 8 insertions(+)\n>\n> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\n> index a47555c..db89cf7 100644\n> --- a/Documentation/git-checkout.txt\n> +++ b/Documentation/git-checkout.txt\n> @@ -25,6 +25,14 @@ branch.\n> \n> \tUpdate the index, working tree, and HEAD to reflect the\n> \tspecified branch.\n> ++\n> +If is not found but there does exist a tracking branch in\n> +exactly one remote (call it ) with a matching name, treat as\n> +equivalent to\n> ++\n> +------------\n> +$ git checkout -b --track /\n> +------------\n> \n> 'git checkout' -b|-B []::\n\nThanks; does it format well (I didn't check)?\n"},{"id":"205025","messageId":"CAH5451kutMLhjGJbeQ0gw_DC8sE_9r2Hjg1SvTa75B5n7eXO1g@mail.gmail.com","threadId":"32366","inReplyTo":"7vd2y9nnyb.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 2/2] Documentation/git-checkout.txt: document 70c9ac2 behavior","fromName":"Andrew Ardill","fromEmail":"andrew.ardill@gmail.com","sentAt":"2012-12-17T07:23:57Z","receivedAt":"2012-12-17T07:23:57Z","isPatch":true,"sender":{"key":"andrew.ardill@gmail.com","avatar":"https://gravatar.com/avatar/da14cb7c091dd44dc6c63a4d3361b149acaf25226dc78eb4131a17b93d9b0993?d=mp&s=160"},"body":"On 17 December 2012 18:21, Junio C Hamano wrote:\n> does it format well (I didn't check)?\n\nIt applied cleanly for me on latest master, and the output looked\nconsistent with existing documentation.\n\nRegards,\n\nAndrew Ardill\n"},{"id":"205026","messageId":"7v4njlnnql.fsf@alter.siamese.dyndns.org","threadId":"32366","inReplyTo":"CAH5451kutMLhjGJbeQ0gw_DC8sE_9r2Hjg1SvTa75B5n7eXO1g@mail.gmail.com","subject":"Re: [PATCH 2/2] Documentation/git-checkout.txt: document 70c9ac2 behavior","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-12-17T07:26:10Z","receivedAt":"2012-12-17T07:26:10Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Andrew Ardill writes:\n\n> On 17 December 2012 18:21, Junio C Hamano wrote:\n>> does it format well (I didn't check)?\n>\n> It applied cleanly for me on latest master, and the output looked\n> consistent with existing documentation.\n\nThanks.\n"},{"id":"205031","messageId":"50CED5D4.5040705@viscovery.net","threadId":"32366","inReplyTo":"7vhanlnnz7.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage","fromName":"Johannes Sixt","fromEmail":"j.sixt@viscovery.net","sentAt":"2012-12-17T08:20:36Z","receivedAt":"2012-12-17T08:20:36Z","isPatch":true,"sender":{"key":"j6t@kdbg.org","avatar":"https://avatars.githubusercontent.com/u/14810926?v=4"},"body":"Am 12/17/2012 8:21, schrieb Junio C Hamano:\n> Chris Rorvick writes:\n>> 'git checkout' []::\n\nIs really optional in this form?\n\nBTW, what does plain 'git checkout' do? Just report ahead/behind information?\n\n>> +\n>> +\tUpdate the index, working tree, and HEAD to reflect the\n>> +\tspecified branch.\n...\n>> +'git checkout' [--detach] []::\n\nThe title here is better spelled as two lines:\n\n'git checkout' ::\n'git checkout' --detach ::\n\nI don't think that or should be indicated as optional here.\n\n>> +\n>> +\tUpdate the index and working tree to reflect the specified\n>> +\tcommit and set HEAD to point directly to (see\n>> +\t\"DETACHED HEAD\" section.) Passing `--detach` forces this\n>> +\tbehavior even if is a branch.\n> \n> \tPrepare to work on building new history on top of ,\n> by detaching HEAD at the commit and ...(likewise)...\n\n-- Hannes\n"},{"id":"205034","messageId":"7vk3shm5d5.fsf@alter.siamese.dyndns.org","threadId":"32366","inReplyTo":"50CED5D4.5040705@viscovery.net","subject":"Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-12-17T08:48:22Z","receivedAt":"2012-12-17T08:48:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Here is what I tentatively have (so that I do not forget) on 'pu',\nmarked with \"(squash???)\", as a suggested update on top of Chris's\npatches.\n\n Documentation/git-checkout.txt | 29 +++++++++++++++++++++--------\n 1 file changed, 21 insertions(+), 8 deletions(-)\n\ndiff --git c/Documentation/git-checkout.txt w/Documentation/git-checkout.txt\nindex db89cf7..0e50eeb 100644\n--- c/Documentation/git-checkout.txt\n+++ w/Documentation/git-checkout.txt\n@@ -21,10 +21,13 @@ or the specified tree. If no paths are given, 'git checkout' will\n also update `HEAD` to set the specified branch as the current\n branch.\n \n-'git checkout' []::\n+'git checkout' ::\n \n-\tUpdate the index, working tree, and HEAD to reflect the\n-\tspecified branch.\n+\tPrepare to work on building new history on , by\n+\tpointing the HEAD to the branch and updating the index and\n+\tthe files in the working tree. Local modifications to the\n+\tfiles in the working tree are kept, so that they can be\n+\tcommitted on the .\n +\n If is not found but there does exist a tracking branch in\n exactly one remote (call it ) with a matching name, treat as\n@@ -33,6 +36,11 @@ equivalent to\n ------------\n $ git checkout -b --track /\n ------------\n++\n+You could omit , in which case the command degenerates to\n+\"check out the current branch\", which is a glorified no-op with a\n+rather expensive side-effects to show only the tracking information,\n+if exists, for the current branch.\n \n 'git checkout' -b|-B []::\n \n@@ -54,12 +62,17 @@ $ git checkout \n that is to say, the branch is not reset/created unless \"git checkout\" is\n successful.\n \n-'git checkout' [--detach] []::\n+'git checkout' --detach []::\n+'git checkout' ::\n \n-\tUpdate the index and working tree to reflect the specified\n-\tcommit and set HEAD to point directly to (see\n-\t\"DETACHED HEAD\" section.) Passing `--detach` forces this\n-\tbehavior even if is a branch.\n+\tPrepare to work on building new history on top of ,\n+\tby detaching HEAD at the commit (see \"DETACHED HEAD\"\n+\tsection), and updating the index and the files in the\n+\tworking tree. Local modifications to the files in the\n+\tworking tree are kept, so that they can be committed on the\n+\t.\n++\n+Passing `--detach` forces this behavior even if is a branch.\n \n 'git checkout' [-p|--patch] [] [--] ...::\n \n"},{"id":"205035","messageId":"CAH5451=U47Aastune7==e67nK9X4A9khdtZvKzhpwkC-eR=o8A@mail.gmail.com","threadId":"32366","inReplyTo":"50CED5D4.5040705@viscovery.net","subject":"Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage","fromName":"Andrew Ardill","fromEmail":"andrew.ardill@gmail.com","sentAt":"2012-12-17T08:53:19Z","receivedAt":"2012-12-17T08:53:19Z","isPatch":true,"sender":{"key":"andrew.ardill@gmail.com","avatar":"https://gravatar.com/avatar/da14cb7c091dd44dc6c63a4d3361b149acaf25226dc78eb4131a17b93d9b0993?d=mp&s=160"},"body":"Regards,\n\nAndrew Ardill\n\n\nOn 17 December 2012 19:20, Johannes Sixt wrote:\n> Am 12/17/2012 8:21, schrieb Junio C Hamano:\n>> Chris Rorvick writes:\n>>> 'git checkout' []::\n>\n> Is really optional in this form?\n>\n> BTW, what does plain 'git checkout' do? Just report ahead/behind information?\n\nI think it defaults to either HEAD or the current branch, which shows\nuncommitted changes and relationship to upstream.\n\n>>> +\n>>> + Update the index, working tree, and HEAD to reflect the\n>>> + specified branch.\n> ...\n>>> +'git checkout' [--detach] []::\n>\n> The title here is better spelled as two lines:\n>\n> 'git checkout' ::\n> 'git checkout' --detach ::\n>\n> I don't think that or should be indicated as optional here.\n\ndoing 'git checkout --detach' will detach from the current branch if\nyou have one, but maybe listing as optional would work in\nthat case?\n\n\nHere is my suggestion, differing from what Junio put forward primarily\nby first indicating that a checkout is a 'switch' to a different\nbranch or commit. This makes sense to me, and is used elsewhere in the\ndocumentation, so I thought it might make sense here too.\n\n-->8--\n\nFrom: Andrew Ardill \nDate: Mon, 17 Dec 2012 18:53:41 +1100\nSubject: [PATCH] Documentation/git-checkout.txt: Use consistent terminology\n\ngit checkout is described as 'switching' branches in places. Use this\nterminology more consistently.\n\nExpand on the purpose of switching to a branch or commit, which is\ntypically to prepare to build history on top of that branch or commit.\n\nSigned-off-by: Andrew Ardill \n---\n Documentation/git-checkout.txt | 18 ++++++++++++------\n 1 file changed, 12 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex db89cf7..e6db14f 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -23,8 +23,11 @@ branch.\n\n 'git checkout' []::\n\n- Update the index, working tree, and HEAD to reflect the\n- specified branch.\n+ Switch to the specified . Prepares for building new\n+ history on , by updating the index and the files in the\n+ working tree, and by pointing HEAD at the branch. Local\n+ modifications to the files in the working tree are kept, so that\n+ they can be committed on the .\n +\n If is not found but there does exist a tracking branch in\n exactly one remote (call it ) with a matching name, treat as\n@@ -56,10 +59,13 @@ successful.\n\n 'git checkout' [--detach] []::\n\n- Update the index and working tree to reflect the specified\n- commit and set HEAD to point directly to (see\n- \"DETACHED HEAD\" section.) Passing `--detach` forces this\n- behavior even if is a branch.\n+ Switch to the specified . Prepares for building new\n+ history on top of , by updating the index and the files\n+ in the working tree, and by pointing HEAD at . Local\n+ modifications to the files in the working tree are kept, so that\n+ they can be committed on top of . Passing `--detach`\n+ forces HEAD to point directly at even if is a\n+ branch (see \"DETACHED HEAD\" section.)\n\n 'git checkout' [-p|--patch] [] [--] ...::\n\n--\n"},{"id":"205037","messageId":"50CEDF0A.7040603@viscovery.net","threadId":"32366","inReplyTo":"7vk3shm5d5.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage","fromName":"Johannes Sixt","fromEmail":"j.sixt@viscovery.net","sentAt":"2012-12-17T08:59:54Z","receivedAt":"2012-12-17T08:59:54Z","isPatch":true,"sender":{"key":"j6t@kdbg.org","avatar":"https://avatars.githubusercontent.com/u/14810926?v=4"},"body":"Am 12/17/2012 9:48, schrieb Junio C Hamano:\n> Here is what I tentatively have ...\n\nThanks!\n\n> -'git checkout' [--detach] []::\n> +'git checkout' --detach []::\n> +'git checkout' ::\n> \n> -\tUpdate the index and working tree to reflect the specified\n> -\tcommit and set HEAD to point directly to (see\n> -\t\"DETACHED HEAD\" section.) Passing `--detach` forces this\n> -\tbehavior even if is a branch.\n> +\tPrepare to work on building new history on top of ,\n> +\tby detaching HEAD at the commit (see \"DETACHED HEAD\"\n> +\tsection), and updating the index and the files in the\n> +\tworking tree. Local modifications to the files in the\n> +\tworking tree are kept, so that they can be committed on the\n> +\t.\n\nThe last half-sentence should better be removed.\n\n> ++\n> +Passing `--detach` forces this behavior even if is a branch.\n> \n> 'git checkout' [-p|--patch] [] [--] ...::\n\n-- Hannes\n"},{"id":"205063","messageId":"7vbodsmr1r.fsf@alter.siamese.dyndns.org","threadId":"32366","inReplyTo":"50CEDF0A.7040603@viscovery.net","subject":"Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-12-17T19:12:16Z","receivedAt":"2012-12-17T19:12:16Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Johannes Sixt writes:\n\n> Am 12/17/2012 9:48, schrieb Junio C Hamano:\n>> Here is what I tentatively have ...\n>\n> Thanks!\n>\n>> -'git checkout' [--detach] []::\n>> +'git checkout' --detach []::\n>> +'git checkout' ::\n>> \n>> -\tUpdate the index and working tree to reflect the specified\n>> -\tcommit and set HEAD to point directly to (see\n>> -\t\"DETACHED HEAD\" section.) Passing `--detach` forces this\n>> -\tbehavior even if is a branch.\n>> +\tPrepare to work on building new history on top of ,\n>> +\tby detaching HEAD at the commit (see \"DETACHED HEAD\"\n>> +\tsection), and updating the index and the files in the\n>> +\tworking tree. Local modifications to the files in the\n>> +\tworking tree are kept, so that they can be committed on the\n>> +\t.\n>\n> The last half-sentence should better be removed.\n\nTrue; we do not have a particular \"on the \" in this state.\nAt least, \"on the \" needs to be removed. But I think we may\nwant a more different wording here, including the earlier \"work on\nbuilding new history on top of\" part.\n\nThe detached HEAD state primarily is a sightseeing mode, where the\nuser is expected to view but not touch. Even for experienced users,\ncommits on a detached HEAD are for keeping snapshots of interim\nstates during a throw-away experiment, so the purpose of detaching\nis not exactly \"to work on *building* new history\" in the first\nplace.\n\nCarefree experimentation is encouraged by not forbidding commmits\nfrom this state, with the expectation that:\n\n (1) if it does not lead to interesting result, another \"git\n checkout \" will wipe the throw-away experiment without\n affecting any of your more important branches; and\n\n (2) an experiment that yielded something useful can be further\n polished on a concrete branch by \"git checkout -b \".\n\nI think the above discussion on detached HEAD can be added to its\nown section.\n\n\tPrepare to work on top of , by detaching HEAD at it\n\t(see \"DETACHED HEAD\" section), and updating te index and the\n\tfiles in the working tree. Local modifications to the files\n\tin the working tree are kept, so that the resulting working\n\ttree will be the state recorded in the commit plus the local\n\tmodifications.\n\nOr something, perhaps?\n"},{"id":"205074","messageId":"17103971665F4C4495C6C96086A58B8F@PhilipOakley","threadId":"32366","inReplyTo":"7vhanlnnz7.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":null,"receivedAt":"2012-12-17T20:41:49Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" Sent: Monday, December 17,\n2012 7:21 AM\n> Chris Rorvick writes:\n>\n>> The forms of checkout that do not take a path are lumped together in\n>> the\n>> DESCRIPTION section, but the description for this group is dominated\n>> by\n>> explanation of the -b|-B form. Split these apart for more clarity.\n>>\n>> Signed-off-by: Chris Rorvick \n>> ---\n>> Documentation/git-checkout.txt | 26 +++++++++++++++++---------\n>> 1 file changed, 17 insertions(+), 9 deletions(-)\n>>\n>> diff --git a/Documentation/git-checkout.txt\n>> b/Documentation/git-checkout.txt\n>> index 7958a47..a47555c 100644\n>> --- a/Documentation/git-checkout.txt\n>> +++ b/Documentation/git-checkout.txt\n>> @@ -22,17 +22,18 @@ also update `HEAD` to set the specified branch as\n>> the current\n>> branch.\n>>\n>> 'git checkout' []::\n>> +\n>> + Update the index, working tree, and HEAD to reflect the\n>> + specified branch.\n>\n> This is to \"check out the branch\" ;-)\n>\n> But of course, we cannot define \"checkout\" in terms of \"checkout\",\n> so we need to phrase it without saying \"checkout\" and explain what\n> it *means* to check out the branch.\n>\n> I am not sure \"Reflect\" is a good word. Making the result similar\n> to the branch is only one aspect of the act of checking out the\n> branch. The other equally important aspect is that this is done to\n> advance the history of the branch.\n>\n> Perhaps...\n>\n> Prepare to work on building new history on , by\n> pointing the HEAD to the branch and updating the index and\n> the files in the working tree. Local modifications to the\n> files in the working tree are kept, so that they can be\n> committed on the .\n\n>From a user perspective it's better to refer to the working directory\nfirst rather than the internal mechanics. Perhaps:\n\n Prepare to work on , by updating the files in the\n working tree and index to the branch's previous content, and\n pointing HEAD to it.\n\n Local modifications to the files in the working tree are kept,\n so that they can be committed on the .\n\n>\n>> 'git checkout' -b|-B []::\n>>\n>> + Specifying `-b` causes a new branch to be created as if\n>> + linkgit:git-branch[1] were called and then checked out. In\n>> + this case you can use the `--track` or `--no-track` options,\n>> + which will be passed to 'git branch'. As a convenience,\n>> + `--track` without `-b` implies branch creation; see the\n>> + description of `--track` below.\n>> +\n>> If `-B` is given, is created if it doesn't exist;\n>> otherwise, it\n>> is reset. This is the transactional equivalent of\n>> @@ -45,6 +46,13 @@ $ git checkout \n>> that is to say, the branch is not reset/created unless \"git\n>> checkout\" is\n>> successful.\n>>\n>> +'git checkout' [--detach] []::\n>> +\n>> + Update the index and working tree to reflect the specified\n>> + commit and set HEAD to point directly to (see\n>> + \"DETACHED HEAD\" section.) Passing `--detach` forces this\n>> + behavior even if is a branch.\n>\n> Prepare to work on building new history on top of ,\n> by detaching HEAD at the commit and ...(likewise)...\n"},{"id":"205075","messageId":"7v1ueol6ut.fsf@alter.siamese.dyndns.org","threadId":"32366","inReplyTo":"17103971665F4C4495C6C96086A58B8F@PhilipOakley","subject":"Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-12-17T21:13:46Z","receivedAt":"2012-12-17T21:13:46Z","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\" Sent: Monday, December 17,\n>> This is to \"check out the branch\" ;-)\n>> ...\n>\n> From a user perspective it's better to refer to the working directory\n> first rather than the internal mechanics.\n>\n> Prepare to work on , by updating the files in the\n> working tree and index to the branch's previous content, and\n> pointing HEAD to it.\n\nI agree that the mention of \"pointing HEAD to\" may be better to be\nrephrased in the user facing terms.\n\nBecause the primary purpose of \"git checkout \" is to \"check\nout the branch so that further work is done on that branch\", that\naspect of the behaviour should be mentioned first. Updating of the\nworking tree files and the index is the implemenation detail of\nstarting to work on that branch.\n\nSo your suggestion is going backwards, I'd have to say.\n"},{"id":"205079","messageId":"CAH5451nVe1VcD3VzCO7EtKSkzv9CyJs=uqQ9MkMTJEXMTwEvmw@mail.gmail.com","threadId":"32366","inReplyTo":"7v1ueol6ut.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage","fromName":"Andrew Ardill","fromEmail":"andrew.ardill@gmail.com","sentAt":"2012-12-17T21:50:15Z","receivedAt":"2012-12-17T21:50:15Z","isPatch":true,"sender":{"key":"andrew.ardill@gmail.com","avatar":"https://gravatar.com/avatar/da14cb7c091dd44dc6c63a4d3361b149acaf25226dc78eb4131a17b93d9b0993?d=mp&s=160"},"body":"On 18 December 2012 08:13, Junio C Hamano wrote:\n> \"Philip Oakley\" writes:\n>\n>> From: \"Junio C Hamano\" Sent: Monday, December 17,\n>>> This is to \"check out the branch\" ;-)\n>>> ...\n>>\n>> From a user perspective it's better to refer to the working directory\n>> first rather than the internal mechanics.\n>>\n>> Prepare to work on , by updating the files in the\n>> working tree and index to the branch's previous content, and\n>> pointing HEAD to it.\n>\n> I agree that the mention of \"pointing HEAD to\" may be better to be\n> rephrased in the user facing terms.\n>\n> Because the primary purpose of \"git checkout \" is to \"check\n> out the branch so that further work is done on that branch\", that\n> aspect of the behaviour should be mentioned first. Updating of the\n> working tree files and the index is the implemenation detail of\n> starting to work on that branch.\n\nEven if the primary purpose of \"git checkout \" is to \"check\nout the branch so that further work is done on that branch\", I don't\nbelieve that means it has to be stated first. In fact, I would say\nthat there are enough other use cases that the language should be\nslightly more use-case agnostic in the first situation. For example,\nsomeone might switch to another branch or commit simply to see what\nstate the tree was in at that point. Some people use checkout to\ndeploy a tag of the working tree onto a production server. The first\nexample in particular is, I think, a common enough operation that\nrestricting the opening lines of documentation to talking about\nbuilding further work is misleading.\n\nMy earlier submission dealt with this by using the 'Switch to the\nspecified ...' terminology. For me this is implicitly stating 'Switch\nthe state of the repository to be the same as the specified ...' but\nperhaps it would do to be more explicit? I prefer the shorter form\nmyself.\n\nBy following this with the typical use case it makes it clear what the\nintended use of the command is, and some idea about the mechanics of\nits function.\n\nI realised that my signature was improperly placed when I submitted my\nsuggestion last, so I will include it here as reference for anyone who\nskipped over it. It builds on top of the two original patches.\n\nRegards,\n\nAndrew Ardill\n\n-->8--\n\nFrom: Andrew Ardill \nDate: Mon, 17 Dec 2012 18:53:41 +1100\nSubject: [PATCH] Documentation/git-checkout.txt: Use consistent terminology\n\ngit checkout is described as 'switching' branches in places. Use this\nterminology more consistently.\n\nExpand on the purpose of switching to a branch or commit, which is\ntypically to prepare to build history on top of that branch or commit.\n\nSigned-off-by: Andrew Ardill \n---\n Documentation/git-checkout.txt | 18 ++++++++++++------\n 1 file changed, 12 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex db89cf7..e6db14f 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -23,8 +23,11 @@ branch.\n\n 'git checkout' []::\n\n- Update the index, working tree, and HEAD to reflect the\n- specified branch.\n+ Switch to the specified . Prepares for building new\n+ history on , by updating the index and the files in the\n+ working tree, and by pointing HEAD at the branch. Local\n+ modifications to the files in the working tree are kept, so that\n+ they can be committed on the .\n +\n If is not found but there does exist a tracking branch in\n exactly one remote (call it ) with a matching name, treat as\n@@ -56,10 +59,13 @@ successful.\n\n 'git checkout' [--detach] []::\n\n- Update the index and working tree to reflect the specified\n- commit and set HEAD to point directly to (see\n- \"DETACHED HEAD\" section.) Passing `--detach` forces this\n- behavior even if is a branch.\n+ Switch to the specified . Prepares for building new\n+ history on top of , by updating the index and the files\n+ in the working tree, and by pointing HEAD at . Local\n+ modifications to the files in the working tree are kept, so that\n+ they can be committed on top of . Passing `--detach`\n+ forces HEAD to point directly at even if is a\n+ branch (see \"DETACHED HEAD\" section.)\n\n 'git checkout' [-p|--patch] [] [--] ...::\n\n--\n"},{"id":"205080","messageId":"7vobhsjq6a.fsf@alter.siamese.dyndns.org","threadId":"32366","inReplyTo":"CAH5451nVe1VcD3VzCO7EtKSkzv9CyJs=uqQ9MkMTJEXMTwEvmw@mail.gmail.com","subject":"Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-12-17T21:59:25Z","receivedAt":"2012-12-17T21:59:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Andrew Ardill writes:\n\n> Even if the primary purpose of \"git checkout \" is to \"check\n> out the branch so that further work is done on that branch\", I don't\n> believe that means it has to be stated first. In fact, I would say\n> that there are enough other use cases that the language should be\n> slightly more use-case agnostic in the first situation. For example,\n> someone might switch to another branch or commit simply to see what\n> state the tree was in at that point.\n\nI've been deliberately avoiding the term \"switch\", actually. I\nagree that it may be familiar to people with prior exposure to\nsubversion, but that is not the primary audience of the manual.\n\n> Some people use checkout to\n> deploy a tag of the working tree onto a production server. The first\n> example in particular is, I think, a common enough operation that\n> restricting the opening lines of documentation to talking about\n> building further work is misleading.\n\nI agree with you that sightseeing use case where you do not intend\nto make any commit is also important. That is exactly why I said\n\"further work is done on that branch\" not \"to that branch\" in the\nmessage you are responding to.\n"},{"id":"205084","messageId":"050EEC5C75504678BC8A858FD0A55B19@PhilipOakley","threadId":"32366","inReplyTo":"7v1ueol6ut.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":null,"receivedAt":"2012-12-17T22:05:35Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" Sent: Monday, December 17, \n2012 9:13 PM\n> \"Philip Oakley\" writes:\n>\n>> From: \"Junio C Hamano\" Sent: Monday, December 17,\n>>> This is to \"check out the branch\" ;-)\n>>> ...\n>>\n>> From a user perspective it's better to refer to the working directory\n>> first rather than the internal mechanics.\n>>\n>> Prepare to work on , by updating the files in the\n>> working tree and index to the branch's previous content, and\n>> pointing HEAD to it.\n>\n> I agree that the mention of \"pointing HEAD to\" may be better to be\n> rephrased in the user facing terms.\n>\n> Because the primary purpose of \"git checkout \" is to \"check\n> out the branch so that further work is done on that branch\", that\n> aspect of the behaviour should be mentioned first.\n\nThat part is OK, but it is a bit tautological.\n\n> Updating of the\n> working tree files and the index is the implemenation detail of\n> starting to work on that branch.\n\nIt was this part that I felt needed the worker's work-tree mentioned \nfirst.\n\nIt could be argued that workers think they do work on the tree, and that \nthe branch name is an administrative place holder.\n\nWhen the two sentences are back to back it was OK, as you had still \nincluded the key element of my suggestion.\n\n>\n> So your suggestion is going backwards, I'd have to say.\n>\nA misunderstanding of the suggestion perhaps?\n\nPhilip \n"},{"id":"205098","messageId":"CAH5451kpNYqJ99Lepjyq8-KEM1D3zeao1gSx05Q7LWWdE_=8jw@mail.gmail.com","threadId":"32366","inReplyTo":"7vobhsjq6a.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage","fromName":"Andrew Ardill","fromEmail":"andrew.ardill@gmail.com","sentAt":"2012-12-18T01:29:28Z","receivedAt":"2012-12-18T01:29:28Z","isPatch":true,"sender":{"key":"andrew.ardill@gmail.com","avatar":"https://gravatar.com/avatar/da14cb7c091dd44dc6c63a4d3361b149acaf25226dc78eb4131a17b93d9b0993?d=mp&s=160"},"body":"On 18 December 2012 08:59, Junio C Hamano wrote:\n> Andrew Ardill writes:\n>> Even if the primary purpose of \"git checkout \" is to \"check\n>> out the branch so that further work is done on that branch\", I don't\n>> believe that means it has to be stated first. In fact, I would say\n>> that there are enough other use cases that the language should be\n>> slightly more use-case agnostic in the first situation. For example,\n>> someone might switch to another branch or commit simply to see what\n>> state the tree was in at that point.\n>\n> I've been deliberately avoiding the term \"switch\", actually. I\n> agree that it may be familiar to people with prior exposure to\n> subversion, but that is not the primary audience of the manual.\n\nI don't have much experience with svn, so I didn't make that\nconnection. Independent of svn usage, what is wrong with the term\n'switch'?\n\nI would be interested to hear how translators communicate the checkout\nconcept, as I assume the word checkout doesn't exist in many\nlanguages. For me, switching between revisions is a natural way of\nphrasing the action, but perhaps there is a better way of saying the\nsame thing?\n\n>> Some people use checkout to\n>> deploy a tag of the working tree onto a production server. The first\n>> example in particular is, I think, a common enough operation that\n>> restricting the opening lines of documentation to talking about\n>> building further work is misleading.\n>\n> I agree with you that sightseeing use case where you do not intend\n> to make any commit is also important. That is exactly why I said\n> \"further work is done on that branch\" not \"to that branch\" in the\n> message you are responding to.\n\nAh ok, I didn't pick up on that nuance. Your suggestion from earlier\nhas, for example, \"Prepare to work on building new history on\n\" which *is* excluding that use case. Perhaps modifying\nsimilar lines to something like \"Prepare to work with the\nrepository/history/something from \" or maybe just \"Prepare to\nwork with \" would better encapsulate those use cases.\nFollowing lines would expand on what it means to work with a branch or\ncommit, and the technical details of updates to the repositories\ncurrent state.\n\nRegards,\n\nAndrew Ardill\n"},{"id":"205101","messageId":"7vvcc0i0rz.fsf@alter.siamese.dyndns.org","threadId":"32366","inReplyTo":"7vobhsjq6a.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-12-18T01:53:20Z","receivedAt":"2012-12-18T01:53:20Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> I agree with you that sightseeing use case where you do not intend\n> to make any commit is also important. That is exactly why I said\n> \"further work is done on that branch\" not \"to that branch\" in the\n> message you are responding to.\n\nHere is a work-in-progress relative to Chris's 83c9989\n(Documentation/git-checkout.txt: document 70c9ac2 behavior,\n2012-12-17).\n\nEven though \"switch to that specific branch\" may be easy to grasp as\na concept, I do not think \"switch to detached HEAD\" makes much\nsense, so I ended up with \"switch\" for the case, and\n\"detach\" for the \"--detach\" one, at least for now.\n\ndiff --git c/Documentation/git-checkout.txt w/Documentation/git-checkout.txt\nindex db89cf7..dcf1a32 100644\n--- c/Documentation/git-checkout.txt\n+++ w/Documentation/git-checkout.txt\n@@ -21,10 +21,12 @@ or the specified tree. If no paths are given, 'git checkout' will\n also update `HEAD` to set the specified branch as the current\n branch.\n \n-'git checkout' []::\n-\n-\tUpdate the index, working tree, and HEAD to reflect the\n-\tspecified branch.\n+'git checkout' ::\n+\tTo prepare for working on , switch to it by updating\n+\tthe index and the files in the working tree, and by pointing\n+\tHEAD at the branch. Local modifications to the files in the\n+\tworking tree are kept, so that they can be committed to the\n+\t.\n +\n If is not found but there does exist a tracking branch in\n exactly one remote (call it ) with a matching name, treat as\n@@ -33,6 +35,11 @@ equivalent to\n ------------\n $ git checkout -b --track /\n ------------\n++\n+You could omit , in which case the command degenerates to\n+\"check out the current branch\", which is a glorified no-op with a\n+rather expensive side-effects to show only the tracking information,\n+if exists, for the current branch.\n \n 'git checkout' -b|-B []::\n \n@@ -54,12 +61,17 @@ $ git checkout \n that is to say, the branch is not reset/created unless \"git checkout\" is\n successful.\n \n-'git checkout' [--detach] []::\n+'git checkout' --detach []::\n+'git checkout' ::\n \n-\tUpdate the index and working tree to reflect the specified\n-\tcommit and set HEAD to point directly to (see\n-\t\"DETACHED HEAD\" section.) Passing `--detach` forces this\n-\tbehavior even if is a branch.\n+\tPrepare to work on top of , by detaching HEAD at it\n+\t(see \"DETACHED HEAD\" section), and updating the index and the\n+\tfiles in the working tree. Local modifications to the files\n+\tin the working tree are kept, so that the resulting working\n+\ttree will be the state recorded in the commit plus the local\n+\tmodifications.\n++\n+Passing `--detach` forces this behavior even if is a branch.\n \n 'git checkout' [-p|--patch] [] [--] ...::\n \n"},{"id":"205103","messageId":"CAH5451nVVSoJeTkCsuyKfJksg15mwPfcZxym9WCzNK2ENezg-w@mail.gmail.com","threadId":"32366","inReplyTo":"7vvcc0i0rz.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage","fromName":"Andrew Ardill","fromEmail":"andrew.ardill@gmail.com","sentAt":"2012-12-18T02:12:57Z","receivedAt":"2012-12-18T02:12:57Z","isPatch":true,"sender":{"key":"andrew.ardill@gmail.com","avatar":"https://gravatar.com/avatar/da14cb7c091dd44dc6c63a4d3361b149acaf25226dc78eb4131a17b93d9b0993?d=mp&s=160"},"body":"I like these, and I think they are conveying the right amount of\ninformation. There is a slight discrepancy between the and\n versions, where it seems we are assuming that by checking out\na commit you are intending to work 'on top of' it. This could be\navoided by using the term 'with' in both cases. Also, they are in\ndifferent tenses, but I'm not sure which is preferred ('Prepare to' vs\n'To prepare for').\n\nIn the second tense, these opening lines might look like this:\n\n+ To prepare for working with , switch to it by updating\n\n+ To prepare for working with , detach HEAD at it\n+ (see \"DETACHED HEAD\" section), and update the index and the\n+ files in the working tree.\n\n\nRegards,\n\nAndrew Ardill\n"},{"id":"205104","messageId":"CAEUsAPZHsTh77VJxzg9uetGuGbipJ-E3iCc=NU3-KmtoEr4wdg@mail.gmail.com","threadId":"32366","inReplyTo":"50CED5D4.5040705@viscovery.net","subject":"Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage","fromName":"Chris Rorvick","fromEmail":"chris@rorvick.com","sentAt":"2012-12-18T02:55:56Z","receivedAt":"2012-12-18T02:55:56Z","isPatch":true,"sender":{"key":"chris@rorvick.com","avatar":"https://avatars.githubusercontent.com/u/824726?v=4"},"body":"On Mon, Dec 17, 2012 at 2:20 AM, Johannes Sixt wrote:\n>>> +'git checkout' [--detach] []::\n>\n> The title here is better spelled as two lines:\n>\n> 'git checkout' ::\n> 'git checkout' --detach ::\n\nAsciiDoc renders these horizontally separated by a comma when\nformatted as a man page instead of vertically as written (and as\nrendered by the HTML documentation.) I think this makes this\nseparation into two less effective, but at least it doesn't line wrap\non an 80-wide terminal like the previous title did.\n\nChris\n"},{"id":"205105","messageId":"CAEUsAPa1XMeymEXbLu=iy8VTdLO=iPUeVN3QPH+FbQecL8XnsA@mail.gmail.com","threadId":"32366","inReplyTo":"7vvcc0i0rz.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage","fromName":"Chris Rorvick","fromEmail":"chris@rorvick.com","sentAt":"2012-12-18T03:33:09Z","receivedAt":"2012-12-18T03:33:09Z","isPatch":true,"sender":{"key":"chris@rorvick.com","avatar":"https://avatars.githubusercontent.com/u/824726?v=4"},"body":"On Mon, Dec 17, 2012 at 7:53 PM, Junio C Hamano wrote:\n> Here is a work-in-progress relative to Chris's 83c9989\n> (Documentation/git-checkout.txt: document 70c9ac2 behavior,\n> 2012-12-17).\n\nIt sounds pretty good to me.\n\n> @@ -54,12 +61,17 @@ $ git checkout \n> that is to say, the branch is not reset/created unless \"git checkout\" is\n> successful.\n>\n> -'git checkout' [--detach] []::\n> +'git checkout' --detach []::\n> +'git checkout' ::\n>\n> - Update the index and working tree to reflect the specified\n> - commit and set HEAD to point directly to (see\n> - \"DETACHED HEAD\" section.) Passing `--detach` forces this\n> - behavior even if is a branch.\n> + Prepare to work on top of , by detaching HEAD at it\n> + (see \"DETACHED HEAD\" section), and updating the index and the\n> + files in the working tree. Local modifications to the files\n> + in the working tree are kept, so that the resulting working\n> + tree will be the state recorded in the commit plus the local\n> + modifications.\n> ++\n> +Passing `--detach` forces this behavior even if is a branch.\n>\n> 'git checkout' [-p|--patch] [] [--] ...::\n>\n\nI like Johannes' suggestion of using \"\" in the --detach case\ninstead of \"\" as I think it makes the reason for the\nseparation more obvious at a glance. On top of your changes, maybe\nsomething like:\n\n--->8---\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex dcf1a32..4fdf41a 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -61,8 +61,8 @@ $ git checkout \n that is to say, the branch is not reset/created unless \"git checkout\" is\n successful.\n\n-'git checkout' --detach []::\n 'git checkout' ::\n+'git checkout' --detach []::\n\n Prepare to work on top of , by detaching HEAD at it\n (see \"DETACHED HEAD\" section), and updating the index and the\n@@ -71,7 +71,8 @@ successful.\n tree will be the state recorded in the commit plus the local\n modifications.\n +\n-Passing `--detach` forces this behavior even if is a branch.\n+Passing `--detach` forces this behavior in the case of a , or\n+the current branch if one is not specified.\n\n 'git checkout' [-p|--patch] [] [--] ...::\n"},{"id":"205132","messageId":"7vvcbzgvk5.fsf@alter.siamese.dyndns.org","threadId":"32366","inReplyTo":"CAEUsAPa1XMeymEXbLu=iy8VTdLO=iPUeVN3QPH+FbQecL8XnsA@mail.gmail.com","subject":"Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-12-18T16:43:38Z","receivedAt":"2012-12-18T16:43:38Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Chris Rorvick writes:\n\n> I like Johannes' suggestion of using \"\" in the --detach case\n> instead of \"\" as I think it makes the reason for the\n> separation more obvious at a glance.\n\nSounds sensible; even though the option does not require its\nargument to be a branch name, the user does not have a reason to use\nthe option if it is not giving a branch name, either, so it all\nbalances out ;-).\n\n>\n> --->8---\n> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\n> index dcf1a32..4fdf41a 100644\n> --- a/Documentation/git-checkout.txt\n> +++ b/Documentation/git-checkout.txt\n> @@ -61,8 +61,8 @@ $ git checkout \n> that is to say, the branch is not reset/created unless \"git checkout\" is\n> successful.\n>\n> -'git checkout' --detach []::\n> 'git checkout' ::\n> +'git checkout' --detach []::\n>\n> Prepare to work on top of , by detaching HEAD at it\n> (see \"DETACHED HEAD\" section), and updating the index and the\n> @@ -71,7 +71,8 @@ successful.\n> tree will be the state recorded in the commit plus the local\n> modifications.\n> +\n> -Passing `--detach` forces this behavior even if is a branch.\n> +Passing `--detach` forces this behavior in the case of a , or\n> +the current branch if one is not specified.\n>\n> 'git checkout' [-p|--patch] [] [--] ...::\n"}]}