{"thread":{"id":"34905","subject":"[PATCH] Documentation/git-checkout: Move `--detach` flag in synopsis to correct command","startedAt":"2013-09-11T02:37:54Z","lastAt":"2013-09-11T19:06:41Z","messageCount":3,"participants":["Benjamin Bergman","Junio C Hamano","Jonathan Nieder"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"227403","messageId":"CA+DWcQah8Uy41oZXGhP-i+H7JAU_bOWPVt3i79fDnW==FeTJGw@mail.gmail.com","threadId":"34905","inReplyTo":null,"subject":"[PATCH] Documentation/git-checkout: Move `--detach` flag in synopsis to correct command","fromName":"Benjamin Bergman","fromEmail":"ben@benbergman.ca","sentAt":"2013-09-11T02:37:54Z","receivedAt":"2013-09-11T02:37:54Z","isPatch":true,"sender":{"key":"ben@benbergman.ca","avatar":null},"body":">From a33659535cb0eac92bed42d5e494dbb8f5d9ab20 Mon Sep 17 00:00:00 2001\nFrom: Benjamin Bergman <ben@benbergman.ca>\nDate: Tue, 10 Sep 2013 16:00:29 -0500\nSubject: [PATCH] Documentation/git-checkout: Move `--detach` flag in synopsis\n to correct command\n\nDetailed description of `--detach` states that it is default for\n`<commit>` but needs to be specified for `<branch>`. The old man page\nsynopsis showed the reverse.\n---\n Documentation/git-checkout.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex ca118ac..dee95e8 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -8,8 +8,8 @@ git-checkout - Checkout a branch or paths to the working tree\n SYNOPSIS\n --------\n [verse]\n-'git checkout' [-q] [-f] [-m] [<branch>]\n-'git checkout' [-q] [-f] [-m] [--detach] [<commit>]\n+'git checkout' [-q] [-f] [-m] [--detach] [<branch>]\n+'git checkout' [-q] [-f] [-m] [<commit>]\n 'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]\n 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>]\n[<tree-ish>] [--] <paths>...\n 'git checkout' [-p|--patch] [<tree-ish>] [--] [<paths>...]\n-- \n1.8.3.4\n"},{"id":"227464","messageId":"xmqq1u4vuw4y.fsf@gitster.dls.corp.google.com","threadId":"34905","inReplyTo":"CA+DWcQah8Uy41oZXGhP-i+H7JAU_bOWPVt3i79fDnW==FeTJGw@mail.gmail.com","subject":"Re: [PATCH] Documentation/git-checkout: Move `--detach` flag in synopsis to correct command","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-09-11T17:05:17Z","receivedAt":"2013-09-11T17:05:17Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Benjamin Bergman <ben@benbergman.ca> writes:\n\n> From a33659535cb0eac92bed42d5e494dbb8f5d9ab20 Mon Sep 17 00:00:00 2001\n> From: Benjamin Bergman <ben@benbergman.ca>\n> Date: Tue, 10 Sep 2013 16:00:29 -0500\n> Subject: [PATCH] Documentation/git-checkout: Move `--detach` flag in synopsis\n>  to correct command\n\nThese (except the first one that is a separator in the format-patch output)\ngo to your e-mail headers, not to the body of the message.\n\n>\n> Detailed description of `--detach` states that it is default for\n> `<commit>` but needs to be specified for `<branch>`. The old man page\n> synopsis showed the reverse.\n> ---\n\nPlease sign-off your patch.\n\n> -'git checkout' [-q] [-f] [-m] [<branch>]\n> -'git checkout' [-q] [-f] [-m] [--detach] [<commit>]\n> +'git checkout' [-q] [-f] [-m] [--detach] [<branch>]\n> +'git checkout' [-q] [-f] [-m] [<commit>]\n\nI am actually on the fence on this change.\n\nThe original shows two operations that do different things (one goes\nto a named branch, the other goes to the state in which the HEAD is\ndetached at the named commit).\n\nWith the updated synopsis, even with the first form, if the user\nuses --detach, the end result is like the second one. I personally\nfind the synopsis with the patch a bit more confusing, not less.\n\nCan we update the second form (without touching the one that shows\n\"how to check out a named branch\" at all) in a different way to\nclarify?  E.g.\n\n        'git checkout' [-q] [-f] [-m] [<commit> | --detach <branch>]\n\nmight be one way.  If you want to detach at a named commit, you can\ndirectly give the commit object name; a branch name usually can be\nused as a commit object name, but that use conflicts with the more\nusual \"check out that branch\" usage, so you need to give --detach\nexplicitly if you use a branch name to name that commit you want to\ndetach at.  One drawback this has is that it does not capture that\nyou could say --detach (even though you do not have to) when using a\nform that is _not_ a branch name to name your commit, e.g.\n\n\tgit checkout --detach master^0\n\n... thinks a bit more ...\n\nOr we can split the \"detaching\" usage into two, which is how the\nDESCRIPTION section does.  I.e.\n\n    'git checkout' [-q] [-f] [-m] [<branch>]\n   -'git checkout' [-q] [-f] [-m] --detach [<commit>]\n   +'git checkout' [-q] [-f] [-m] --detach [<branch>]\n   +'git checkout' [-q] [-f] [-m] <commit>\n    'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<st...\n\nThis would tell the reader that:\n\n    - You can give \"--detach\" and no branch name---you would detach\n      at the tip of your current branch;\n\n    - You can give \"--detach\" and a branch name;\n\n    - You can give a commit object name.\n\nWe could also throw in \"[--detach]\" in front of the <commit> to say\nthat it is accepted (even though it is not necessary.\n\n>  'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]\n>  'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>]\n> [<tree-ish>] [--] <paths>...\n\nYour MUA or editor line-wrapped the patch; please do not let them.\n\n>  'git checkout' [-p|--patch] [<tree-ish>] [--] [<paths>...]\n\n\nHow about doing it this way?\n\n-- >8 --\nSubject: checkout: update synopsys and documentation on detaching HEAD\n\nIn the synopsis, the second form to detach HEAD at the named commit\nlabelled the argument as '<commit>'.  While this is technically more\ncorrect, because the feature to detach is not limited to the tip of\na named branch, it was found confusing and did not express the fact\nthat you have to give `--detach` if you are naming the commit you\nwant to detach HEAD at with a branch name.\n\nSeparate this case into two syntactical forms, mimicking the way how\nthe DESCRIPTION section shows this usage.  Also update the text that\nexplains the syntax to name the commit to detach HEAD at to clarify.\n\nSuggested-by: Benjamin Bergman <ben@benbergman.ca>\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n Documentation/git-checkout.txt | 16 ++++++++++------\n 1 file changed, 10 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex ca118ac..01d9b85 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -9,7 +9,8 @@ SYNOPSIS\n --------\n [verse]\n 'git checkout' [-q] [-f] [-m] [<branch>]\n-'git checkout' [-q] [-f] [-m] [--detach] [<commit>]\n+'git checkout' [-q] [-f] [-m] --detach [<branch>]\n+'git checkout' [-q] [-f] [-m] [--detach] <commit>\n 'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]\n 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...\n 'git checkout' [-p|--patch] [<tree-ish>] [--] [<paths>...]\n@@ -62,7 +63,7 @@ that is to say, the branch is not reset/created unless \"git checkout\" is\n successful.\n \n 'git checkout' --detach [<branch>]::\n-'git checkout' <commit>::\n+'git checkout' [--detach] <commit>::\n \n \tPrepare to work on top of <commit>, by detaching HEAD at it\n \t(see \"DETACHED HEAD\" section), and updating the index and the\n@@ -71,10 +72,13 @@ successful.\n \ttree will be the state recorded in the commit plus the local\n \tmodifications.\n +\n-Passing `--detach` forces this behavior in the case of a <branch> (without\n-the option, giving a branch name to the command would check out the branch,\n-instead of detaching HEAD at it), or the current commit,\n-if no <branch> is specified.\n+Even though a branch name can be used to name a commit, you have to\n+explicitly say `git checkout --detach <branch>` when you want to\n+detach HEAD at the tip of the branch (`git checkout <branch>` will\n+check out that branch without detaching HEAD).  Omitting <branch>,\n+i.e. `git checkout --detach` detaches HEAD at the tip of the current\n+branch.  When naming the commit in a form other than just a branch\n+name, e.g. `master^0`, `HEAD~4`, `c2f3bf071e`, you can omit --detach.\n \n 'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...::\n \n"},{"id":"227483","messageId":"20130911190641.GF4326@google.com","threadId":"34905","inReplyTo":"xmqq1u4vuw4y.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] Documentation/git-checkout: Move `--detach` flag in synopsis to correct command","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2013-09-11T19:06:41Z","receivedAt":"2013-09-11T19:06:41Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Hi,\n\nJunio C Hamano wrote:\n\n> --- a/Documentation/git-checkout.txt\n> +++ b/Documentation/git-checkout.txt\n> @@ -9,7 +9,8 @@ SYNOPSIS\n>  --------\n>  [verse]\n>  'git checkout' [-q] [-f] [-m] [<branch>]\n> -'git checkout' [-q] [-f] [-m] [--detach] [<commit>]\n> +'git checkout' [-q] [-f] [-m] --detach [<branch>]\n> +'git checkout' [-q] [-f] [-m] [--detach] <commit>\n>  'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]\n>  'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...\n>  'git checkout' [-p|--patch] [<tree-ish>] [--] [<paths>...]\n> @@ -62,7 +63,7 @@ that is to say, the branch is not reset/created unless \"git checkout\" is\n>  successful.\n>  \n>  'git checkout' --detach [<branch>]::\n> -'git checkout' <commit>::\n> +'git checkout' [--detach] <commit>::\n\nLooks sensible.\n\n[...]\n> @@ -71,10 +72,13 @@ successful.\n>  \ttree will be the state recorded in the commit plus the local\n>  \tmodifications.\n>  +\n> -Passing `--detach` forces this behavior in the case of a <branch> (without\n> -the option, giving a branch name to the command would check out the branch,\n> -instead of detaching HEAD at it), or the current commit,\n> -if no <branch> is specified.\n> +Even though a branch name can be used to name a commit, you have to\n> +explicitly say `git checkout --detach <branch>` when you want to\n> +detach HEAD at the tip of the branch (`git checkout <branch>` will\n> +check out that branch without detaching HEAD).  Omitting <branch>,\n> +i.e. `git checkout --detach` detaches HEAD at the tip of the current\n> +branch.  When naming the commit in a form other than just a branch\n> +name, e.g. `master^0`, `HEAD~4`, `c2f3bf071e`, you can omit --detach.\n\nHm.  I agree that the old explanation is overly convoluted, but I don't\nthink the replacement is clear enough yet.  The \"Even though a branch\nname can be used to name a commit,\" part forced me to pause for too\nlong --- why is this telling me that a branch can be used to name a\ncommit, and in what context?\n\nI think the main problem with the old text is that it tried to say too\nmuch in one sentence.\n\nThe explanation lower down of the --detach option does this rather\nwell:\n\n\t--detach\n\t\tRather than checking out a branch to work on it, check\n\t\tout a commit for inspection and discardable\n\t\texperiments.  This is the default behavior of\n\t\t\"git checkout <commit>\" when <commit> is not a branch\n\t\tname.  See the \"DETACHED HEAD\" section below for\n\t\tdetails.\n\nHow about splitting this into multiple paragraphs, like so?  In the\nsuggestion below I also cleaned up the language a little.\n\n\tgit checkout --detach [<branch>], git checkout [--detach] <commit>\n\t\tPrepare to work on top of <commit>, by detaching [...]\n\n\t\tWhen the <commit> argument is a branch name, the --detach\n\t\toption can be used to detach HEAD at the tip of the\n\t\tbranch ('git checkout <branch>' would check out that\n\t\tbranch without detaching HEAD).\n\n\t\tOmitting <branch> detaches HEAD at the tip of the\n\t\tcurrent branch.\n\nI'd leave out the last sentence about commits other than branch names,\nsince it is already implied by the [--detach] in the syntax.\n\nThanks and hope that helps,\nJonathan\n"}]}