{"thread":{"id":"23943","subject":"[PATCH] Documentation/checkout: clarify description","startedAt":"2010-05-30T08:41:53Z","lastAt":"2010-06-01T07:25:23Z","messageCount":3,"participants":["Jonathan Nieder","Jeff King"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"142557","messageId":"20100530084153.GA5447@progeny.tock","threadId":"23943","inReplyTo":null,"subject":"[PATCH] Documentation/checkout: clarify description","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-05-30T08:41:53Z","receivedAt":"2010-05-30T08:41:53Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"To the first-time reader, it may not be obvious that ‘git checkout’\nhas two modes, nor that if no branch is specified it will read\nfrom the index.\n\nSigned-off-by: Jonathan Nieder <jrnieder@gmail.com>\n---\nThanks to neha_ from IRC for pointing this out.\n\n Documentation/git-checkout.txt |   28 +++++++++++++++++-----------\n 1 files changed, 17 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex 4505eb6..99bd7f2 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -15,26 +15,32 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n+Retrieves files from the index or specified tree and writes them\n+to the working tree.\n \n-When <paths> are not given, this command switches branches by\n-updating the index, working tree, and HEAD to reflect the specified\n-branch.\n+'git checkout' [-b <new branch>] [<branch>]::\n \n+\tWhen <paths> are not given, this command switches branches by\n+\tupdating the index, working tree, and HEAD to reflect the\n+\tspecified branch.\n++\n If `-b` is given, a new branch is created and checked out, as if\n linkgit:git-branch[1] were called; in this case you can\n use the --track or --no-track options, which will be passed to `git\n branch`.  As a convenience, --track without `-b` implies branch\n creation; see the description of --track below.\n \n-When <paths> or --patch are given, this command does *not* switch\n-branches.  It updates the named paths in the working tree from\n-the index file, or from a named <tree-ish> (most often a commit).  In\n-this case, the `-b` and `--track` options are meaningless and giving\n-either of them results in an error. The <tree-ish> argument can be\n-used to specify a specific tree-ish (i.e. commit, tag or tree)\n-to update the index for the given paths before updating the\n-working tree.\n+'git checkout' [--patch] [<tree-ish>] [--] [<pathspec>...]::\n \n+\tWhen <paths> or --patch are given, this command does *not* switch\n+\tbranches.  It updates the named paths in the working tree from\n+\tthe index file, or from a named <tree-ish> (most often a commit).  In\n+\tthis case, the `-b` and `--track` options are meaningless and giving\n+\teither of them results in an error. The <tree-ish> argument can be\n+\tused to specify a specific tree-ish (i.e. commit, tag or tree)\n+\tto update the index for the given paths before updating the\n+\tworking tree.\n++\n The index may contain unmerged entries after a failed merge.  By\n default, if you try to check out such an entry from the index, the\n checkout operation will fail and nothing will be checked out.\n-- \n1.7.1\n"},{"id":"142648","messageId":"20100601061046.GA7360@sigill.intra.peff.net","threadId":"23943","inReplyTo":"20100530084153.GA5447@progeny.tock","subject":"Re: [PATCH] Documentation/checkout: clarify description","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-06-01T06:10:47Z","receivedAt":"2010-06-01T06:10:47Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sun, May 30, 2010 at 03:41:53AM -0500, Jonathan Nieder wrote:\n\n> To the first-time reader, it may not be obvious that ‘git checkout’\n> has two modes, nor that if no branch is specified it will read\n> from the index.\n\nOK, I can see how we might not explain the modes well, but...\n\n> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\n> index 4505eb6..99bd7f2 100644\n> --- a/Documentation/git-checkout.txt\n> +++ b/Documentation/git-checkout.txt\n> @@ -15,26 +15,32 @@ SYNOPSIS\n>  \n>  DESCRIPTION\n>  -----------\n> +Retrieves files from the index or specified tree and writes them\n> +to the working tree.\n>  \n> -When <paths> are not given, this command switches branches by\n> -updating the index, working tree, and HEAD to reflect the specified\n> -branch.\n\nHow is this first paragraph helping? It seems to be describing just one\nmode. You then go on to describe each mode in turn, which makes sense,\nbut this first paragraph just seems out of place. If you're going to say\nanything, you should say \"there are two different modes, one for X and\none for Y. The first mode is...\".\n\n> +'git checkout' [-b <new branch>] [<branch>]::\n>  \n> +\tWhen <paths> are not given, this command switches branches by\n> +\tupdating the index, working tree, and HEAD to reflect the\n> +\tspecified branch.\n\nIn 76cfadf, I split this into\n\n  git checkout [<branch>]\n  git checkout -b <new branch> [<start_point>]\n\nI wonder if we should do the same here (the distinction is that\n<start_point> is treated differently from <branch>, especially with\nrespect to creating a detached HEAD).\n\nAlso, does it make sense to say \"When <paths> are not given\"? The \"this\ncommand\" presumably refers to the one directly above, which has no\n<paths>. Might it be easier to understand if we say \"in this form of the\ncommand\" or something like that? Since we are now listing each form in\nturn, the user can presumably figure out which form they are trying to\nuse.\n\n-Peff\n"},{"id":"142654","messageId":"20100601072523.GB27593@progeny.tock","threadId":"23943","inReplyTo":"20100601061046.GA7360@sigill.intra.peff.net","subject":"Re: [PATCH] Documentation/checkout: clarify description","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-06-01T07:25:23Z","receivedAt":"2010-06-01T07:25:23Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Jeff King wrote:\n> On Sun, May 30, 2010 at 03:41:53AM -0500, Jonathan Nieder wrote:\n\n>> +Retrieves files from the index or specified tree and writes them\n>> +to the working tree.\n[...]\n> How is this first paragraph helping?\n\nIdeally, one should be able to read the first sentence or two of a\nmanual page to tell whether this is the right command to use.\n\nBut in this case, the sentence I added is just misleading.  How about:\n\n  Updates files in the working tree to match the version in the index\n  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\nSurely it is possible to do better:\n\n . Wording is not so great\n\n . Either this page or git-branch.1 would be a better place than\n   the glossary to explain the HEAD reference and its role in git.\n   So there should be some reference here of the form (see the\n   \"CURRENT BRANCH\" section below) or similar.\n\n . The description leaves implicit why copying files from the index,\n   updating the index and work tree to match a commit, switching\n   branches, and getting a quick summary of unregistered changes\n   deserve a single command.\n\n   Yet for some reason it feels natural that they share one.  Is this\n   force of habit from rcs co and its derivatives, or is there some\n   common theme that would be simple to explain?\n\n> In 76cfadf, I split this into\n> \n>   git checkout [<branch>]\n>   git checkout -b <new branch> [<start_point>]\n>\n> I wonder if we should do the same here (the distinction is that\n> <start_point> is treated differently from <branch>, especially with\n> respect to creating a detached HEAD).\n\nReasonable.\n\n> Might it be easier to understand if we say \"in this form of the\n> command\" or something like that? Since we are now listing each form in\n> turn, the user can presumably figure out which form they are trying to\n> use.\n\nGood point, thanks.\n\n-- %< --\nSubject: Documentation/checkout: clarify description\n\ngit checkout can be used to switch branches and to retrieve files from\nthe index or an arbitrary tree.  Split the description into\nsubsections corresponding to each mode to make each use easier to\nunderstand.\n\nHelped-by: Jeff King <peff@peff.net>\nSigned-off-by: Jonathan Nieder <jrnieder@gmail.com>\n---\n Documentation/git-checkout.txt |   50 +++++++++++++++++++++++----------------\n 1 files changed, 29 insertions(+), 21 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex 4505eb6..e337628 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -15,33 +15,41 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-\n-When <paths> are not given, this command switches branches by\n-updating the index, working tree, and HEAD to reflect the specified\n+Updates files in the working tree to match the version in the index\n+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-If `-b` is given, a new branch is created and checked out, as if\n-linkgit:git-branch[1] were called; in this case you can\n-use the --track or --no-track options, which will be passed to `git\n-branch`.  As a convenience, --track without `-b` implies branch\n-creation; see the description of --track below.\n+'git checkout' [<branch>]::\n+'git checkout' -b <new branch> [<start point>]::\n \n-When <paths> or --patch are given, this command does *not* switch\n-branches.  It updates the named paths in the working tree from\n-the index file, or from a named <tree-ish> (most often a commit).  In\n-this case, the `-b` and `--track` options are meaningless and giving\n-either of them results in an error. The <tree-ish> argument can be\n-used to specify a specific tree-ish (i.e. commit, tag or tree)\n-to update the index for the given paths before updating the\n-working tree.\n+\tThis form switches branches by updating the index, working\n+\ttree, and HEAD to reflect the specified branch.\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 \n-The index may contain unmerged entries after a failed merge.  By\n-default, if you try to check out such an entry from the index, the\n+'git checkout' [--patch] [<tree-ish>] [--] <pathspec>...::\n+\n+\tWhen <paths> or `--patch` are given, 'git checkout' *not* switch\n+\tbranches.  It updates the named paths in the working tree from\n+\tthe index file or from a named <tree-ish> (most often a commit).  In\n+\tthis case, the `-b` and `--track` options are meaningless and giving\n+\teither of them results in an error. The <tree-ish> argument can be\n+\tused to specify a specific tree-ish (i.e. commit, tag or tree)\n+\tto update the index for the given paths before updating the\n+\tworking tree.\n++\n+The index may contain unmerged entries because of a previous failed merge.\n+By default, if you try to check out such an entry from the index, the\n checkout operation will fail and nothing will be checked out.\n-Using -f will ignore these unmerged entries.  The contents from a\n+Using `-f` will ignore these unmerged entries.  The contents from a\n specific side of the merge can be checked out of the index by\n-using --ours or --theirs.  With -m, changes made to the working tree\n-file can be discarded to recreate the original conflicted merge result.\n+using `--ours` or `--theirs`.  With `-m`, changes made to the working tree\n+file can be discarded to re-create the original conflicted merge result.\n \n OPTIONS\n -------\n-- \n1.7.1\n"}]}