{"thread":{"id":"64030","subject":"[PATCH 0/5] doc: git-checkout: clarify DESCRIPTION section","startedAt":"2025-08-25T19:08:56Z","lastAt":"2025-10-17T15:50:41Z","messageCount":68,"participants":["Julia Evans via GitGitGadget","Junio C Hamano","Julia Evans","D. Ben Knoble","Ben Knoble","Kristoffer Haugsbakk","kristofferhaugsbakk@fastmail.com"],"isPatch":true,"patchVersion":1,"patchTotal":5},"messages":[{"id":"524880","messageId":"pull.1962.git.1756148933.gitgitgadget@gmail.com","threadId":"64030","inReplyTo":null,"subject":"[PATCH 0/5] doc: git-checkout: clarify DESCRIPTION section","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-25T19:08:48Z","receivedAt":"2025-08-25T19:08:56Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"I got feedback from 21 Git users on the current version of the git checkout\nman page to figure out what's confusing about the current text. The goal\nhere is to clarify the parts of the man page they found the most confusing,\nwhile accurately communicating the same information as before.\n\nAbout 50% of the users who gave the feedback said they've been using Git for\n5-10 years and 50% have been using Git for 10+ years.\n\nJulia Evans (5):\n  doc: git-checkout: clarify intro\n  doc: git-checkout: clarify `git checkout <branch>`\n  doc: git-checkout: don't use \"reset\"\n  doc: git-checkout: deduplicate --detach explanation\n  doc: git-checkout: clarify restoring files section\n\n Documentation/git-checkout.adoc | 94 ++++++++++++++++-----------------\n 1 file changed, 47 insertions(+), 47 deletions(-)\n\n\nbase-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1962%2Fjvns%2Fclarify-checkout-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1962/jvns/clarify-checkout-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1962\n-- \ngitgitgadget\n"},{"id":"524881","messageId":"a6125a0128937392af283033e63d2b04776caf2c.1756148933.git.gitgitgadget@gmail.com","threadId":"64030","inReplyTo":"pull.1962.git.1756148933.gitgitgadget@gmail.com","subject":"[PATCH 1/5] doc: git-checkout: clarify intro","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-25T19:08:49Z","receivedAt":"2025-08-25T19:08:56Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\n- Many users do not understand the terms \"index\" or \"pathspec\". Clarify\n  in the intro by using an example, so that users can understand the\n  basic idea without learning the full definition of \"pathspec\".\n- Use the terminology \"Switch\" and \"Restore\" to mirror `git switch`\n  and `git restore`\n- Reference (and clarify) the ARGUMENT DISAMBIGUATION section\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-checkout.adoc | 31 +++++++++++++++++++------------\n 1 file changed, 19 insertions(+), 12 deletions(-)\n\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex 40e02cfd6562..ddda891c0ff7 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -20,10 +20,14 @@ git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]\n \n DESCRIPTION\n -----------\n-Updates files in the working tree to match the version in the index\n-or the specified tree.  If no pathspec was given, `git checkout` will\n-also update `HEAD` to set the specified branch as the current\n-branch.\n+`git checkout` has two main modes:\n+\n+1. **Switch branches**, with `git checkout <branch>`\n+2. **Restore a different version of a file**, for example with `git\n+   checkout <commit> <filename>` or `git checkout <filename>`\n+\n+See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.\n+Here's a description of all of the modes:\n \n `git checkout [<branch>]`::\n \tTo prepare for working on _<branch>_, switch to it by updating\n@@ -511,14 +515,17 @@ $ git log -g -2 HEAD\n ARGUMENT DISAMBIGUATION\n -----------------------\n \n-When there is only one argument given and it is not `--` (e.g. `git\n-checkout abc`), and when the argument is both a valid _<tree-ish>_\n-(e.g. a branch `abc` exists) and a valid _<pathspec>_ (e.g. a file\n-or a directory whose name is \"abc\" exists), Git would usually ask\n-you to disambiguate.  Because checking out a branch is so common an\n-operation, however, `git checkout abc` takes \"abc\" as a _<tree-ish>_\n-in such a situation.  Use `git checkout -- <pathspec>` if you want\n-to checkout these paths out of the index.\n+When you run `git checkout <something>`, Git tries to guess whether\n+`<something>` is intended to be a branch, a commit, or a set of file(s),\n+and then switches branches, switches commits, or restores the files.\n+\n+If there's a conflict, you can use the double dash `--` to distinguish\n+between branches and files:\n+\n+* `git checkout <branch> --` will force Git to treat the parameter as a\n+  branch name or commit\n+* `git checkout -- <pathspec>` will force Git to treat the parameter as\n+  a set of file(s)\n \n EXAMPLES\n --------\n-- \ngitgitgadget\n\n"},{"id":"524882","messageId":"b8873c4529caeddc85879efd122e5a57278352f0.1756148933.git.gitgitgadget@gmail.com","threadId":"64030","inReplyTo":"pull.1962.git.1756148933.gitgitgadget@gmail.com","subject":"[PATCH 2/5] doc: git-checkout: clarify `git checkout <branch>`","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-25T19:08:50Z","receivedAt":"2025-08-25T19:08:57Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\n- \"To prepare for working on _<branch>_...\" is confusing to some users:\n  it makes it sound like these are steps that the user has to do, not\n  steps that Git itself will do. Reword it.\n- Use \"changes\" instead of \"modifications\" (which Git normally does)\n- Mention that `git checkout` will fail if there's a merge conflict\n- The current explanation of `You could omit <branch>`... is confusing\n  to users (what are the \"expensive side effects\"? what's a better way\n  of getting the same info?). Be more direct and mention that `git\n  status` is likely a better option.\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-checkout.adoc | 18 +++++++++---------\n 1 file changed, 9 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex ddda891c0ff7..a3edb95973a2 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -30,11 +30,12 @@ See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.\n Here's a description of all of the modes:\n \n `git checkout [<branch>]`::\n-\tTo prepare for working on _<branch>_, switch to it by updating\n-\tthe index and the files in the working tree, and by pointing\n-\t`HEAD` 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_<branch>_.\n+\tSwitch to _<branch>_. This will update the files in the working tree,\n+\tpoint `HEAD` at the branch, and update the index. Local changes to\n+\tthe files in the working tree are kept, so that they can be committed\n+\tto the _<branch>_. If the local changes conflict with the changes on\n+\t_<branch>_, no changes will be made and the checkout operation will\n+\tfail.\n +\n If _<branch>_ is not found but there does exist a tracking branch in\n exactly one remote (call it _<remote>_) with a matching name and\n@@ -44,10 +45,9 @@ exactly one remote (call it _<remote>_) with a matching name and\n $ git checkout -b <branch> --track <remote>/<branch>\n ------------\n +\n-You could omit _<branch>_, in which case the command degenerates to\n-\"check out the current branch\", which is a glorified no-op with\n-rather expensive side-effects to show only the tracking information,\n-if it exists, for the current branch.\n+Running `git checkout` without specifying a branch will output the\n+tracking information, if it exists, for the current branch, but it's\n+slower than getting the same information from `git status`.\n \n `git checkout (-b|-B) <new-branch> [<start-point>]`::\n \n-- \ngitgitgadget\n\n"},{"id":"524883","messageId":"0a3915264bdc613097580be0e041896116df5452.1756148933.git.gitgitgadget@gmail.com","threadId":"64030","inReplyTo":"pull.1962.git.1756148933.gitgitgadget@gmail.com","subject":"[PATCH 3/5] doc: git-checkout: don't use \"reset\"","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-25T19:08:51Z","receivedAt":"2025-08-25T19:08:58Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nMany Git users don't know what the term \"reset\" means. Resolve this by:\n\n- Expanding it into its definition, in one case\n- Giving a simpler but still accurate explanation (\"the branch will not\n  be created or modified\"), in the other case\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-checkout.adoc | 11 +++++------\n 1 file changed, 5 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex a3edb95973a2..dc9607d9ea39 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -58,18 +58,17 @@ slower than getting the same information from `git status`.\n \t`--track` without `-b` implies branch creation; see the\n \tdescription of `--track` below.\n +\n-If `-B` is given, _<new-branch>_ is created if it doesn't exist; otherwise, it\n-is reset. This is the transactional equivalent of\n+If `-B` is given, _<new-branch>_ is created if it doesn't exist;\n+otherwise `<new-branch>` is forced to point at the commit. This is the\n+transactional equivalent of\n +\n ------------\n $ git branch -f <branch> [<start-point>]\n $ git checkout <branch>\n ------------\n +\n-that is to say, the branch is not reset/created unless \"git checkout\" is\n-successful (e.g., when the branch is in use in another worktree, not\n-just the current branch stays the same, but the branch is not reset to\n-the start-point, either).\n+that is, the branch will not be created or modified unless\n+`git checkout` is successful.\n \n `git checkout --detach [<branch>]`::\n `git checkout [--detach] <commit>`::\n-- \ngitgitgadget\n\n"},{"id":"524884","messageId":"2221a6bfb508205b99bfe086b60e64c7218a2606.1756148933.git.gitgitgadget@gmail.com","threadId":"64030","inReplyTo":"pull.1962.git.1756148933.gitgitgadget@gmail.com","subject":"[PATCH 4/5] doc: git-checkout: deduplicate --detach explanation","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-25T19:08:52Z","receivedAt":"2025-08-25T19:09:00Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nRight now the explanation of `--detach` repeats a lot of the content in\nthe description of `git checkout <branch>`: we can communicate the same\nthing by saying \"This is the same as `git checkout <branch>`, except...\"\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-checkout.adoc | 13 +++----------\n 1 file changed, 3 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex dc9607d9ea39..b343d292b30b 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -73,16 +73,9 @@ that is, the branch will not be created or modified unless\n `git checkout --detach [<branch>]`::\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-\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-When the _<commit>_ argument is a branch name, the `--detach` option can\n-be used to detach `HEAD` at the tip of the branch (`git checkout\n-<branch>` would check out that branch without detaching `HEAD`).\n+\tThe same as `git checkout <branch>`, except that instead of pointing\n+\t`HEAD` at the branch, it points `HEAD` at the commit ID.\n+\tSee the \"DETACHED HEAD\" section below for more.\n +\n Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.\n \n-- \ngitgitgadget\n\n"},{"id":"524885","messageId":"b641874627b3898831c3965616e936bd4ee310df.1756148933.git.gitgitgadget@gmail.com","threadId":"64030","inReplyTo":"pull.1962.git.1756148933.gitgitgadget@gmail.com","subject":"[PATCH 5/5] doc: git-checkout: clarify restoring files section","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-25T19:08:53Z","receivedAt":"2025-08-25T19:09:00Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\n- Use the term \"Restore\" to mirror `git restore`\n- Many Git users do not know what a \"tree-ish\" is. Clarify by using an\n  example of each case, and by saying \"commit or tree\" in the text\n  instead of \"<tree-ish>\"\n- Many Git users do not know what the \"index\" is. Instead say \"stage the\n  file's contents\" where appropriate, since Git often uses \"stage\" as a\n  verb to mean the same thing as \"add to the index\" and it's a more\n  familiar term.\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-checkout.adoc | 21 +++++++++++----------\n 1 file changed, 11 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex b343d292b30b..9f2b86ac5368 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -82,20 +82,21 @@ Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.\n `git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...`::\n `git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]`::\n \n-\tOverwrite the contents of the files that match the pathspec.\n-\tWhen the _<tree-ish>_ (most often a commit) is not given,\n-\toverwrite working tree with the contents in the index.\n-\tWhen the _<tree-ish>_ is given, overwrite both the index and\n-\tthe working tree with the contents at the _<tree-ish>_.\n+\tRestore another version of the file(s) that match the pathspec.\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+If you specify a commit or tree to restore from (for example `git\n+checkout main file.txt`), this will restore the version of the file(s)\n+from that commit or tree. This overwrites the file in the working\n+directory and stages the file's contents.\n++\n+If you do not specify where to restore from (for example `git checkout\n+file.txt`), this will replace the file(s) with the version from the index.\n+If you check out a file with an unresolved merge\n+conflict, the checkout operation will fail and no changes will be made.\n+Using `-f` will ignore the merge conflict.  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 re-create the original conflicted merge result.\n-\n `git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]`::\n \tThis is similar to the previous mode, but lets you use the\n \tinteractive interface to show the \"diff\" output and choose which\n-- \ngitgitgadget\n"},{"id":"524991","messageId":"xmqqqzwxkjje.fsf@gitster.g","threadId":"64030","inReplyTo":"a6125a0128937392af283033e63d2b04776caf2c.1756148933.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 1/5] doc: git-checkout: clarify intro","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-26T18:46:45Z","receivedAt":"2025-08-26T18:46:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> From: Julia Evans <julia@jvns.ca>\n>\n> - Many users do not understand the terms \"index\" or \"pathspec\". Clarify\n>   in the intro by using an example, so that users can understand the\n>   basic idea without learning the full definition of \"pathspec\".\n> - Use the terminology \"Switch\" and \"Restore\" to mirror `git switch`\n>   and `git restore`\n> - Reference (and clarify) the ARGUMENT DISAMBIGUATION section\n\nAvoid bullet points here.  End your sentence with a full stop.\n\n> -Updates files in the working tree to match the version in the index\n> -or the specified tree.  If no pathspec was given, `git checkout` will\n> -also update `HEAD` to set the specified branch as the current\n> -branch.\n> +`git checkout` has two main modes:\n> +\n> +1. **Switch branches**, with `git checkout <branch>`\n> +2. **Restore a different version of a file**, for example with `git\n> +   checkout <commit> <filename>` or `git checkout <filename>`\n> +\n> +See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.\n\nAs promised in the proposed log message, this conveys the same\ninformation much more clearly.\n\n\"A different version of\" neatly sidesteps the need to hint we can\ncheck out paths from a tree or the index.  \"Restore a different\nversion of files\" (or \"files from a different version\") perhaps?\nThe point being you can grab multiple with a single operation, but\nthey all have to come from a single source.\n\nOther than that, very nicely done.\n\n> +Here's a description of all of the modes:\n\nI am not sure if we want/need this line, though.\n\n>  `git checkout [<branch>]`::\n>  \tTo prepare for working on _<branch>_, switch to it by updating\n> @@ -511,14 +515,17 @@ $ git log -g -2 HEAD\n>  ARGUMENT DISAMBIGUATION\n>  -----------------------\n>  \n> -When there is only one argument given and it is not `--` (e.g. `git\n> -checkout abc`), and when the argument is both a valid _<tree-ish>_\n> -(e.g. a branch `abc` exists) and a valid _<pathspec>_ (e.g. a file\n> -or a directory whose name is \"abc\" exists), Git would usually ask\n> -you to disambiguate.  Because checking out a branch is so common an\n> -operation, however, `git checkout abc` takes \"abc\" as a _<tree-ish>_\n> -in such a situation.  Use `git checkout -- <pathspec>` if you want\n> -to checkout these paths out of the index.\n> +When you run `git checkout <something>`, Git tries to guess whether\n> +`<something>` is intended to be a branch, a commit, or a set of file(s),\n> +and then switches branches, switches commits, or restores the files.\n> +\n> +If there's a conflict, you can use the double dash `--` to distinguish\n> +between branches and files:\n\nI do not think you are dealing with a conflict here, rather\nambiguity.  \"You can use double-dash `--` to disambiguate between\nbranches and paths\".\n\n\n> +* `git checkout <branch> --` will force Git to treat the parameter as a\n> +  branch name or commit\n> +* `git checkout -- <pathspec>` will force Git to treat the parameter as\n> +  a set of file(s)\n\nWe do not have to teach the full pathspec syntax here, but I wonder\nif we should do something to avoid leading a new reader into\nthinking they have to list files.  \"...as a set of files and/or\ndirectories\", perhaps?\n\n"},{"id":"524993","messageId":"xmqqms7lkjar.fsf@gitster.g","threadId":"64030","inReplyTo":"xmqqqzwxkjje.fsf@gitster.g","subject":"Re: [PATCH 1/5] doc: git-checkout: clarify intro","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-26T18:51:56Z","receivedAt":"2025-08-26T18:51:59Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n>> -Updates files in the working tree to match the version in the index\n>> -or the specified tree.  If no pathspec was given, `git checkout` will\n>> -also update `HEAD` to set the specified branch as the current\n>> -branch.\n>> +`git checkout` has two main modes:\n\nAnother thing I noticed but forgot to mention.\n\n>> +\n>> +1. **Switch branches**, with `git checkout <branch>`\n\nDoes everybody really understand what it means to \"switch branches\"\nwithout further explanation?\n\nAlso \"<branch>\" -> \"(<branch> | <commit>)\", perhaps, as working on\nthe unnamed branch (aka detached HEAD) behaves very much the same\nway as working on a named branch.\n"},{"id":"525003","messageId":"de40e0ed-ca12-41b0-acd0-3c594078cc14@app.fastmail.com","threadId":"64030","inReplyTo":"xmqqqzwxkjje.fsf@gitster.g","subject":"Re: [PATCH 1/5] doc: git-checkout: clarify intro","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-08-26T20:56:36Z","receivedAt":"2025-08-26T20:56:57Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"Thanks for the comments!\n\n> Avoid bullet points here.  End your sentence with a full stop.\n\nOk, will change.\n\n> \"Restore a different\n> version of files\" (or \"files from a different version\") perhaps?\n> The point being you can grab multiple with a single operation, but\n> they all have to come from a single source.\n\nI like that, will change.\n\n>> +Here's a description of all of the modes:\n>\n> I am not sure if we want/need this line, though.\n\nWill remove.\n\n> I do not think you are dealing with a conflict here, rather\n> ambiguity.  \"You can use double-dash `--` to disambiguate between\n> branches and paths\".\n\nWill change.\n\n>> +* `git checkout <branch> --` will force Git to treat the parameter as a\n>> +  branch name or commit\n>> +* `git checkout -- <pathspec>` will force Git to treat the parameter as\n>> +  a set of file(s)\n>\n> We do not have to teach the full pathspec syntax here, but I wonder\n> if we should do something to avoid leading a new reader into\n> thinking they have to list files.  \"...as a set of files and/or\n> directories\", perhaps?\n\nI like that, will change.\n\n>>> +1. **Switch branches**, with `git checkout <branch>`\n>\n> Does everybody really understand what it means to \"switch branches\"\n> without further explanation?\n\nMy thought was that we explain what \"switch branches\" in\nimmediately afterwards in more depth. (\"git checkout [<branch>]:\nSwitch to <branch>. This will update the files in the working tree...)\n\n> Also \"<branch>\" -> \"(<branch> | <commit>)\", perhaps, as working on\n> the unnamed branch (aka detached HEAD) behaves very much the same\n> way as working on a named branch.\n\nI feel mixed about this one.\n\nOne way to look at it is that `git checkout` has two modes: one\nwhere you update `HEAD` and one where you don't. I think\nfrom a \"git internals\" point of view this makes a lot of sense, but\nmy impression is that most \"regular\" Git users think of \"switching\nto detached HEAD state\" as being a very different operation from\n\"switching branches\", not as basically equivalent except for one\nsmall detail.\n\nAnother way to look at it is that the \"git checkout <branch> | <commit>\"'s\nmain role is to switch branches, and that \"git checkout <commit>\" is\nsort of an edge case and that we can leave its explanation to a few\nlines later on. That's the stance I've taken here, but I'm open to hearing\nother points of view.\n"},{"id":"525004","messageId":"xmqqldn5ix0r.fsf@gitster.g","threadId":"64030","inReplyTo":"b8873c4529caeddc85879efd122e5a57278352f0.1756148933.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 2/5] doc: git-checkout: clarify `git checkout <branch>`","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-26T21:38:28Z","receivedAt":"2025-08-26T21:38:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> From: Julia Evans <julia@jvns.ca>\n>\n> - \"To prepare for working on _<branch>_...\" is confusing to some users:\n>   it makes it sound like these are steps that the user has to do, not\n>   steps that Git itself will do. Reword it.\n> - Use \"changes\" instead of \"modifications\" (which Git normally does)\n> - Mention that `git checkout` will fail if there's a merge conflict\n> - The current explanation of `You could omit <branch>`... is confusing\n>   to users (what are the \"expensive side effects\"? what's a better way\n>   of getting the same info?). Be more direct and mention that `git\n>   status` is likely a better option.\n>\n> Signed-off-by: Julia Evans <julia@jvns.ca>\n> ---\n>  Documentation/git-checkout.adoc | 18 +++++++++---------\n>  1 file changed, 9 insertions(+), 9 deletions(-)\n>\n> diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\n> index ddda891c0ff7..a3edb95973a2 100644\n> --- a/Documentation/git-checkout.adoc\n> +++ b/Documentation/git-checkout.adoc\n> @@ -30,11 +30,12 @@ See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.\n>  Here's a description of all of the modes:\n>  \n>  `git checkout [<branch>]`::\n> -\tTo prepare for working on _<branch>_, switch to it by updating\n> -\tthe index and the files in the working tree, and by pointing\n> -\t`HEAD` 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_<branch>_.\n> +\tSwitch to _<branch>_. This will update the files in the working tree,\n> +\tpoint `HEAD` at the branch, and update the index. Local changes to\n> +\tthe files in the working tree are kept, so that they can be committed\n> +\tto the _<branch>_. If the local changes conflict with the changes on\n> +\t_<branch>_, no changes will be made and the checkout operation will\n> +\tfail.\n\nDo we expect readers to truly understand what is to \"switch to branch\"\nwithout explanation?  IOW, I am undecided if the lost \"To prepare for\nworking on\" is a good thing.\n\nUsually with \"changes on _<branch>_\", people mean quite a different\nthing from what the above paragraph refers to.\n\nImagine that you are on a branch that you forked from 'main' some\ntime ago, built a handful of commits, among which there may be ones\nthat touch file F.  You further have local modification to file F.\nNow you want to switch to another branch.  That branch, since it\nforked from 'main', never touched F.  Your local changes do not\nconflict with \"the changes on branch\" (there is no changes on branch\nto conflict with your work, as F stayed the same).\n\nTo improve, \"with the changes on _<branch>_\" should be phrased more like\n\"with the differences between the current state and that of the\n_<branch>_\" or something.\n\n>  +\n>  If _<branch>_ is not found but there does exist a tracking branch in\n>  exactly one remote (call it _<remote>_) with a matching name and\n> @@ -44,10 +45,9 @@ exactly one remote (call it _<remote>_) with a matching name and\n>  $ git checkout -b <branch> --track <remote>/<branch>\n>  ------------\n>  +\n> -You could omit _<branch>_, in which case the command degenerates to\n> -\"check out the current branch\", which is a glorified no-op with\n> -rather expensive side-effects to show only the tracking information,\n> -if it exists, for the current branch.\n> +Running `git checkout` without specifying a branch will output the\n> +tracking information, if it exists, for the current branch, but it's\n> +slower than getting the same information from `git status`.\n\nI do not think \"glorified no-op\" is a reference to \"status\".  At least,\nwhen I wrote it, I didn't mean it that way to compare this glorified\nno-op with \"git status\" [*].  It is a reference to \"even though you are\ninvoking the 'checkout' command, you are not checking out anything.\"\nThe side effect is to see the tracking information, which is \"rather\nexpensive side-effects\"---compared to doing nothing, anything is\nexpensive ;-).\n\nI strongly suspect that running \"git status\" is much more costly than\n\"git checkout\", simply because the former has to do a lot more than just\npeeking the tracking information; it internally runs diff between HEAD\nand the index, and between the index and the working tree, and it also\nhas to find and list untracked paths.  Both commands compute the\ntracking info by calling the same remote.c::format_tracking_info()\nfunction.\n\nOther than these minor points, the new text seems a definite\nimprovement.\n\n\n[References]\n\n * https://lore.kernel.org/git/7vk3shm5d5.fsf@alter.siamese.dyndns.org/\n   is where the \"glorified no-op\" came from.\n"},{"id":"525006","messageId":"xmqqiki9hfg2.fsf@gitster.g","threadId":"64030","inReplyTo":"b641874627b3898831c3965616e936bd4ee310df.1756148933.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 5/5] doc: git-checkout: clarify restoring files section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-26T22:43:25Z","receivedAt":"2025-08-26T22:43:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\n> index b343d292b30b..9f2b86ac5368 100644\n> --- a/Documentation/git-checkout.adoc\n> +++ b/Documentation/git-checkout.adoc\n> @@ -82,20 +82,21 @@ Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.\n>  `git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...`::\n>  `git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]`::\n>  \n> -\tOverwrite the contents of the files that match the pathspec.\n> -\tWhen the _<tree-ish>_ (most often a commit) is not given,\n> -\toverwrite working tree with the contents in the index.\n> -\tWhen the _<tree-ish>_ is given, overwrite both the index and\n> -\tthe working tree with the contents at the _<tree-ish>_.\n> +\tRestore another version of the file(s) that match the pathspec.\n\nThe same comment about \"files and directories from a different\nversion\" applies here.\n\nAlso, I am not so sure about the claim that the verb \"restore\" is\nbetter understood than \"overwrite\" due to the presence of \"git\nrestore\".  If you are working on, say, an older maintenance track,\nand want to borrow what is in a few files from the development\nbranch, you may say \"git restore --source=develop files...\" go grab\nthem down to your current working tree.  But at least to me,\n\"restore\" has a connotation to get back what you used to have, but\nthe contents in these files you are grabbing had not existed on the\nolder maintenance track you are working on, ever, and \"restore\" had\nalways made me go \"Huh?\".\n\nI am not suggesting to change the command name \"restore\"; I am\nsuggesting the operation that command does using a verb that is\ndifferent from \"restore\" (in an ancient thread, we tried to explain\n\"checkout\" without using \"checkout\" as the primary verb to describe\nwhat it does, it is the same thing).\n\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\n> +If you specify a commit or tree to restore from (for example `git\n> +checkout main file.txt`), this will restore the version of the file(s)\n> +from that commit or tree. This overwrites the file in the working\n> +directory and stages the file's contents.\n\nOK.  I suspect the most common is to \"restore\" from HEAD, and the\n\"Huh?\"ness of using the verb \"restore\" goes away.  It clearly is\ngetting you back to where you were back when your working tree was\nin sync with HEAD.  Perhaps use \"git checkout HEAD file.txt\" for the\nexample?\n\n> +If you do not specify where to restore from (for example `git checkout\n> +file.txt`), this will replace the file(s) with the version from the index.\n\nThat is a very negative way to state it.  It is not \"do not specify\nwhere\".  If you do not give tree, you are actively specifying that\nyou want things from the index.\n\n> +If you check out a file with an unresolved merge\n> +conflict, the checkout operation will fail and no changes will be made.\n\nThis is confusing in a way different from the original.  During a\nconflicted merge, you will see a few stages until they are resolved.\n\n (1) The working tree file has conflict markers and text from\n     multiple variants.  The index has higher-stage cache entry for\n     such a path.\n\n (2) The user edits the working tree file to resolve the conflicts.\n     Once all the conflict markers are removed, some people may say\n     \"the merge conflict has been resolved\".  To Git, the path is\n     still unmerged.\n\n (3) The user tells the index what the resolution is, with commands\n     like \"git add\", \"git rm\", and the like.  The higher-stage cache\n     entries in the index for the path are moved and replaced with a\n     single stage-0 entry.  To Git, the path is now merged.\n\nSo, \"a file with an unresolved merge conflict\" would not mean what\nyou wanted to say for those who consider that dealing with the\nworking tree files is enough to declare victory and consider the\nconflict has been resolved.\n\n> +Using `-f` will ignore the merge conflict.  The contents from a\n\nThis changes the meaning to most people from what the original\nmeant.  If you have a file F with merge conflicts in the earlier\npart but the later part merged cleanly, does \"git checkout -f F\"\nignore the conflicted part and overwrite the rest of the file\nsomehow?\n\nIf you wanted to avoid the term \"unmerged cache entries\", you can\nsay \"unmerged paths\".\n\nTaking all of the above into consideration, perhaps...\n\n    When you are in the middle of a conflicted merge (or\n    cherry-pick, \"stash pop\", etc.) and haven't told Git what the\n    resolution for these conflicted paths are with \"git add\" and\n    friends, using \"git checkout\" to check out such an unmerged path\n    out of the index would fail and the command exits with non-zero\n    exit status.\n\n    When the `-f` option is given, these unmerged paths are left\n    untouched, instead of triggering an error.  For all other\n    (i.e. merged) paths that match the <pathspec>, the working tree\n    files are overwritten by the version recorded in the index.\n\nor something along that line, but with a readability enhancement\nlike you have been doing in your series ;-).\n"},{"id":"525099","messageId":"276630b8-ad98-4ada-aa85-9f136d653d7b@app.fastmail.com","threadId":"64030","inReplyTo":"xmqqldn5ix0r.fsf@gitster.g","subject":"Re: [PATCH 2/5] doc: git-checkout: clarify `git checkout <branch>`","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-08-28T12:11:11Z","receivedAt":"2025-08-28T12:11:32Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"> Do we expect readers to truly understand what is to \"switch to branch\"\n> without explanation?  IOW, I am undecided if the lost \"To prepare for\n> working on\" is a good thing.\n\nI'm not sure what you mean here: \"switch to <branch>\" is as far as I can tell\nthe most widely used term to refer to this operation, in other Git\nresources, in Git's own man pages, and in the error output of the \n`git checkout` command itself:\n(\"Please commit your changes or stash them before you switch branches.\")\nWhich readers do you think would be confused by it?\n\n> Usually with \"changes on _<branch>_\", people mean quite a different\n> thing from what the above paragraph refers to.\n>\n> Imagine that you are on a branch that you forked from 'main' some\n> time ago, built a handful of commits, among which there may be ones\n> that touch file F.  You further have local modification to file F.\n> Now you want to switch to another branch.  That branch, since it\n> forked from 'main', never touched F.  Your local changes do not\n> conflict with \"the changes on branch\" (there is no changes on branch\n> to conflict with your work, as F stayed the same).\n>\n> To improve, \"with the changes on _<branch>_\" should be phrased more like\n> \"with the differences between the current state and that of the\n> _<branch>_\" or something.\n\nThat makes sense. I'll work on a better way to phrase this.\n\n> I do not think \"glorified no-op\" is a reference to \"status\".  At least,\n> when I wrote it, I didn't mean it that way to compare this glorified\n> no-op with \"git status\" [*].  It is a reference to \"even though you are\n> invoking the 'checkout' command, you are not checking out anything.\"\n> The side effect is to see the tracking information, which is \"rather\n> expensive side-effects\"---compared to doing nothing, anything is\n> expensive ;-).\n>\n> I strongly suspect that running \"git status\" is much more costly than\n> \"git checkout\", simply because the former has to do a lot more than just\n> peeking the tracking information; it internally runs diff between HEAD\n> and the index, and between the index and the working tree, and it also\n> has to find and list untracked paths.  Both commands compute the\n> tracking info by calling the same remote.c::format_tracking_info()\n> function.\n\nAh, I thought `git status` was faster because I benchmarked it it on one\nof my repositories and got these results [1]. \n\nNow that I see that that's not what \"expensive side-effects\" was intended\nto mean, will change to something much simpler, like \"Running `git checkout`\nwithout specifying a branch outputs the tracking information for the current\nbranch. It has no other effect. \"\n\n- Julia\n\n[1]\n$ hyperfine 'git status'\nBenchmark 1: git status\n  Time (mean ± σ):       6.6 ms ±   1.2 ms    [User: 3.2 ms, System: 5.1 ms]\n$ hyperfine 'git checkout'\n  Time (mean ± σ):      29.5 ms ±   1.9 ms    [User: 12.6 ms, System: 14.8 ms]\n"},{"id":"525102","messageId":"80fba886-4693-4f31-b64f-438391edc3da@app.fastmail.com","threadId":"64030","inReplyTo":"xmqqiki9hfg2.fsf@gitster.g","subject":"Re: [PATCH 5/5] doc: git-checkout: clarify restoring files section","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-08-28T13:26:54Z","receivedAt":"2025-08-28T13:27:15Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"On Tue, Aug 26, 2025, at 6:43 PM, Junio C Hamano wrote:\n> \"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n>\n>> diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\n>> index b343d292b30b..9f2b86ac5368 100644\n>> --- a/Documentation/git-checkout.adoc\n>> +++ b/Documentation/git-checkout.adoc\n>> @@ -82,20 +82,21 @@ Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.\n>>  `git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...`::\n>>  `git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]`::\n>>  \n>> -\tOverwrite the contents of the files that match the pathspec.\n>> -\tWhen the _<tree-ish>_ (most often a commit) is not given,\n>> -\toverwrite working tree with the contents in the index.\n>> -\tWhen the _<tree-ish>_ is given, overwrite both the index and\n>> -\tthe working tree with the contents at the _<tree-ish>_.\n>> +\tRestore another version of the file(s) that match the pathspec.\n>\n> The same comment about \"files and directories from a different\n> version\" applies here.\n>\n> Also, I am not so sure about the claim that the verb \"restore\" is\n> better understood than \"overwrite\" due to the presence of \"git\n> restore\".  If you are working on, say, an older maintenance track,\n> and want to borrow what is in a few files from the development\n> branch, you may say \"git restore --source=develop files...\" go grab\n> them down to your current working tree.  But at least to me,\n> \"restore\" has a connotation to get back what you used to have, but\n> the contents in these files you are grabbing had not existed on the\n> older maintenance track you are working on, ever, and \"restore\" had\n> always made me go \"Huh?\".\n>\n> I am not suggesting to change the command name \"restore\"; I am\n> suggesting the operation that command does using a verb that is\n> different from \"restore\" (in an ancient thread, we tried to explain\n> \"checkout\" without using \"checkout\" as the primary verb to describe\n> what it does, it is the same thing).\n>\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>\n>> +If you specify a commit or tree to restore from (for example `git\n>> +checkout main file.txt`), this will restore the version of the file(s)\n>> +from that commit or tree. This overwrites the file in the working\n>> +directory and stages the file's contents.\n>\n> OK.  I suspect the most common is to \"restore\" from HEAD, and the\n> \"Huh?\"ness of using the verb \"restore\" goes away.  It clearly is\n> getting you back to where you were back when your working tree was\n> in sync with HEAD.  Perhaps use \"git checkout HEAD file.txt\" for the\n> example?\n>\n>> +If you do not specify where to restore from (for example `git checkout\n>> +file.txt`), this will replace the file(s) with the version from the index.\n>\n> That is a very negative way to state it.  It is not \"do not specify\n> where\".  If you do not give tree, you are actively specifying that\n> you want things from the index.\n>\n>> +If you check out a file with an unresolved merge\n>> +conflict, the checkout operation will fail and no changes will be made.\n>\n> This is confusing in a way different from the original.  During a\n> conflicted merge, you will see a few stages until they are resolved.\n>\n>  (1) The working tree file has conflict markers and text from\n>      multiple variants.  The index has higher-stage cache entry for\n>      such a path.\n>\n>  (2) The user edits the working tree file to resolve the conflicts.\n>      Once all the conflict markers are removed, some people may say\n>      \"the merge conflict has been resolved\".  To Git, the path is\n>      still unmerged.\n>\n>  (3) The user tells the index what the resolution is, with commands\n>      like \"git add\", \"git rm\", and the like.  The higher-stage cache\n>      entries in the index for the path are moved and replaced with a\n>      single stage-0 entry.  To Git, the path is now merged.\n>\n> So, \"a file with an unresolved merge conflict\" would not mean what\n> you wanted to say for those who consider that dealing with the\n> working tree files is enough to declare victory and consider the\n> conflict has been resolved.\n>\n>> +Using `-f` will ignore the merge conflict.  The contents from a\n>\n> This changes the meaning to most people from what the original\n> meant.  If you have a file F with merge conflicts in the earlier\n> part but the later part merged cleanly, does \"git checkout -f F\"\n> ignore the conflicted part and overwrite the rest of the file\n> somehow?\n>\n> If you wanted to avoid the term \"unmerged cache entries\", you can\n> say \"unmerged paths\".\n>\n> Taking all of the above into consideration, perhaps...\n>\n>     When you are in the middle of a conflicted merge (or\n>     cherry-pick, \"stash pop\", etc.) and haven't told Git what the\n>     resolution for these conflicted paths are with \"git add\" and\n>     friends, using \"git checkout\" to check out such an unmerged path\n>     out of the index would fail and the command exits with non-zero\n>     exit status.\n>\n>     When the `-f` option is given, these unmerged paths are left\n>     untouched, instead of triggering an error.  For all other\n>     (i.e. merged) paths that match the <pathspec>, the working tree\n>     files are overwritten by the version recorded in the index.\n>\n> or something along that line, but with a readability enhancement\n> like you have been doing in your series ;-).\n\nThanks, this section of the man page is not easy and this is very\nuseful feedback. Will work on improving all of these points.\n"},{"id":"525109","messageId":"CALnO6CCvD-uoan=-VW+OmfCk5cLgNm=zENAejL9vX2czahMGxg@mail.gmail.com","threadId":"64030","inReplyTo":"a6125a0128937392af283033e63d2b04776caf2c.1756148933.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 1/5] doc: git-checkout: clarify intro","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-08-28T14:00:22Z","receivedAt":"2025-08-28T14:00:38Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Mon, Aug 25, 2025 at 3:09 PM Julia Evans via GitGitGadget\n<gitgitgadget@gmail.com> wrote:\n>\n> From: Julia Evans <julia@jvns.ca>\n>\n> - Many users do not understand the terms \"index\" or \"pathspec\". Clarify\n>   in the intro by using an example, so that users can understand the\n>   basic idea without learning the full definition of \"pathspec\".\n> - Use the terminology \"Switch\" and \"Restore\" to mirror `git switch`\n>   and `git restore`\n> - Reference (and clarify) the ARGUMENT DISAMBIGUATION section\n>\n> Signed-off-by: Julia Evans <julia@jvns.ca>\n> ---\n>  Documentation/git-checkout.adoc | 31 +++++++++++++++++++------------\n>  1 file changed, 19 insertions(+), 12 deletions(-)\n>\n> diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\n> index 40e02cfd6562..ddda891c0ff7 100644\n> --- a/Documentation/git-checkout.adoc\n> +++ b/Documentation/git-checkout.adoc\n> @@ -20,10 +20,14 @@ git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]\n>\n>  DESCRIPTION\n>  -----------\n> -Updates files in the working tree to match the version in the index\n> -or the specified tree.  If no pathspec was given, `git checkout` will\n> -also update `HEAD` to set the specified branch as the current\n> -branch.\n> +`git checkout` has two main modes:\n> +\n> +1. **Switch branches**, with `git checkout <branch>`\n> +2. **Restore a different version of a file**, for example with `git\n> +   checkout <commit> <filename>` or `git checkout <filename>`\n> +\n> +See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.\n> +Here's a description of all of the modes:\n\nThis looks good—I initially scratched my head thinking there were 3\nmodes, but unifying \"update files to match index\" and \"update files to\nmatch specified tree\" is easier to digest in this presentation.\n\n>\n>  `git checkout [<branch>]`::\n>         To prepare for working on _<branch>_, switch to it by updating\n> @@ -511,14 +515,17 @@ $ git log -g -2 HEAD\n>  ARGUMENT DISAMBIGUATION\n>  -----------------------\n>\n> -When there is only one argument given and it is not `--` (e.g. `git\n> -checkout abc`), and when the argument is both a valid _<tree-ish>_\n> -(e.g. a branch `abc` exists) and a valid _<pathspec>_ (e.g. a file\n> -or a directory whose name is \"abc\" exists), Git would usually ask\n> -you to disambiguate.  Because checking out a branch is so common an\n> -operation, however, `git checkout abc` takes \"abc\" as a _<tree-ish>_\n> -in such a situation.  Use `git checkout -- <pathspec>` if you want\n> -to checkout these paths out of the index.\n> +When you run `git checkout <something>`, Git tries to guess whether\n> +`<something>` is intended to be a branch, a commit, or a set of file(s),\n> +and then switches branches, switches commits, or restores the files.\n> +\n> +If there's a conflict, you can use the double dash `--` to distinguish\n> +between branches and files:\n> +\n> +* `git checkout <branch> --` will force Git to treat the parameter as a\n> +  branch name or commit\n> +* `git checkout -- <pathspec>` will force Git to treat the parameter as\n> +  a set of file(s)\n\nI think we've dropped the bit about the default interpretation of \"git\ncheckout <something>\". Maybe\n\n    When you run `git checkout <something>`, Git tries to guess whether\n    `<something>` is intended to be a branch, a commit, or a set of file(s),\n    and then switches branches, switches commits, or restores the files.\n\n    By default, Git interprets `<something>` as a _<tree-ish>_.\n    [explain what choosing a tree-ish means for the user?]\n\n    [Your notes on disambiguation as before]\n\n?\n\n>\n>  EXAMPLES\n>  --------\n> --\n> gitgitgadget\n>\n>\n\n\n-- \nD. Ben Knoble\n"},{"id":"525116","messageId":"xmqq349bxxeu.fsf@gitster.g","threadId":"64030","inReplyTo":"276630b8-ad98-4ada-aa85-9f136d653d7b@app.fastmail.com","subject":"Re: [PATCH 2/5] doc: git-checkout: clarify `git checkout <branch>`","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-28T15:45:29Z","receivedAt":"2025-08-28T15:45:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" <julia@jvns.ca> writes:\n\n>> Do we expect readers to truly understand what is to \"switch to branch\"\n>> without explanation?  IOW, I am undecided if the lost \"To prepare for\n>> working on\" is a good thing.\n>\n> I'm not sure what you mean here: \"switch to <branch>\" is as far as I can tell\n> the most widely used term to refer to this operation, in other Git\n> resources, in Git's own man pages, and in the error output of the \n> `git checkout` command itself:\n\nMy assumption was that you are making this a manual to teach what\n\"switch to branch\" means to folks who do not know, hence my\nquestion.\n\n> (\"Please commit your changes or stash them before you switch branches.\")\n> Which readers do you think would be confused by it?\n\nExactly those who are given that message and want to understand what\nit means.\n"},{"id":"525136","messageId":"006b2c3e-9d73-4781-980c-56f98121b9ed@app.fastmail.com","threadId":"64030","inReplyTo":"xmqq349bxxeu.fsf@gitster.g","subject":"Re: [PATCH 2/5] doc: git-checkout: clarify `git checkout <branch>`","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-08-28T18:24:30Z","receivedAt":"2025-08-28T18:24:55Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"> My assumption was that you are making this a manual to teach what\n> \"switch to branch\" means to folks who do not know, hence my\n> question.\n\nThanks for bringing this up, I think the question of audience is very important.\n\nMy main goal right now is actually to make the Git documentation understandable\nfor existing Git users who have already been using Git for at least a year or\ntwo. From the feedback I'm getting so far, the man pages are very hard\nto understand for those users, and even for many users who have been using Git\nfor 10+ years.\n\nThe reason that I've been thinking of \"existing Git users\" and not\n\"newcomers to Git\" as the primary audience are:\n\na) existing users are likely to be the main users of the man pages (after all,\nbeginners don't _stay_ beginners for very long!)\nb) my impression is that the Git documentation always aims to explain everything\nin a way that's \"completely technically accurate\" (which I think makes sense!),\nand I I think it's often impossible to give a completely technically accurate\nexplanation in a way that a newcomer to Git can completely understand.\n\nThat said, of course I'm not against making things accessible to newcomers :)\nMy usual approach in technical writing is to think of \"a user who's been using\nthis software for a couple of years already\" as the _primary_ audience, but\nalso to try to keep it as accessible to a newcomer as possible.\n\nI think I can figure out how to say something about what it means to \"Switch\nbranches\" that a newcomer to Git might understand, though of course it'll need\nto be quite different than the current explanation (existing users generally\ndon't understand what \"HEAD\" or the \"index\" are, so a newcomer likely won't\nunderstand those terms either).\n"},{"id":"525138","messageId":"CALnO6CDpsgTnC95CzjOL5MuhFNAnYYSQCR-jC_n5JYLEu0BTow@mail.gmail.com","threadId":"64030","inReplyTo":"b641874627b3898831c3965616e936bd4ee310df.1756148933.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 5/5] doc: git-checkout: clarify restoring files section","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-08-28T19:08:02Z","receivedAt":"2025-08-28T19:08:15Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Mon, Aug 25, 2025 at 3:31 PM Julia Evans via GitGitGadget\n<gitgitgadget@gmail.com> wrote:\n>\n> From: Julia Evans <julia@jvns.ca>\n>\n> - Use the term \"Restore\" to mirror `git restore`\n> - Many Git users do not know what a \"tree-ish\" is. Clarify by using an\n>   example of each case, and by saying \"commit or tree\" in the text\n>   instead of \"<tree-ish>\"\n\nWishful thinking (see glossary comments): I wish we could teach them\nabout \"tree-ish\"s here rather than stop using useful shorthands\naltogether. Of course, then we have to wonder where we can use the\nshorthand and where we must do the \"spell it out (give an\nabbreviation)\" dance. Hm.\n\n> diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\n> index b343d292b30b..9f2b86ac5368 100644\n> --- a/Documentation/git-checkout.adoc\n> +++ b/Documentation/git-checkout.adoc\n> @@ -82,20 +82,21 @@ Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.\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> +If you specify a commit or tree to restore from (for example `git\n> +checkout main file.txt`), this will restore the version of the file(s)\n> +from that commit or tree. This overwrites the file in the working\n> +directory and stages the file's contents.\n> ++\n> +If you do not specify where to restore from (for example `git checkout\n> +file.txt`), this will replace the file(s) with the version from the index.\n> +If you check out a file with an unresolved merge\n\nPossibly a missing paragraph break here?\n\n> +conflict, the checkout operation will fail and no changes will be made.\n> +Using `-f` will ignore the merge conflict.  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 re-create the original conflicted merge result.\n> -\n>  `git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]`::\n\nI think I would expect to keep this break, but I might be misreading something.\n\n-- \nD. Ben Knoble\n"},{"id":"525143","messageId":"2efb789d-db2d-4dae-ae81-373bd231c3c6@app.fastmail.com","threadId":"64030","inReplyTo":"CALnO6CDpsgTnC95CzjOL5MuhFNAnYYSQCR-jC_n5JYLEu0BTow@mail.gmail.com","subject":"Re: [PATCH 5/5] doc: git-checkout: clarify restoring files section","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-08-28T19:59:44Z","receivedAt":"2025-08-28T20:00:13Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"> Wishful thinking (see glossary comments): I wish we could teach them\n> about \"tree-ish\"s here rather than stop using useful shorthands\n> altogether. Of course, then we have to wonder where we can use the\n> shorthand and where we must do the \"spell it out (give an\n> abbreviation)\" dance. Hm.\n\nWhat I find hard about documenting cases like this is identifying\nthe use case for providing so much flexibility\n(\"you can pass any tree, not just a commit!), since personally\nI've never passed anything to `git checkout` other than a commit.\n\nI've been trying to think of examples of cases where it's useful\nto pass a tree instead of a commit. I can see that it's possible to run\nsomething like this\n\n$ git checkout HEAD:Documentation/ git-commit.adoc\n\nto restore `file.txt` into a different directory than it was originally.\nThis seems cool in theory but it's hard for me to see why it's useful,\nwhich makes it hard for me to document. What I would tell a friend is\n\"<tree-ish> 99% of the time just means \"commit or something\nwhich resolves to a commit, but Git has made it more general for\na reason I don't understand\", but of course that's not the right\nthing to say in the Git documentation :)\n"},{"id":"525147","messageId":"xmqq7bynuqqc.fsf@gitster.g","threadId":"64030","inReplyTo":"2efb789d-db2d-4dae-ae81-373bd231c3c6@app.fastmail.com","subject":"Re: [PATCH 5/5] doc: git-checkout: clarify restoring files section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-28T20:38:03Z","receivedAt":"2025-08-28T20:38:06Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" <julia@jvns.ca> writes:\n\n> $ git checkout HEAD:Documentation/ git-commit.adoc\n>\n> to restore `file.txt` into a different directory than it was originally.\n\nIt probably is handy when you want to cross a rename boundary to\nbackport a new thing into an old history (or vice versa).  Something\nlike\n\n    $ git checkout v1.0.0\n    $ git checkout v1.7.1:builtin cat-file.c\n\nperhaps.\n\n> What I would tell a friend is\n> \"<tree-ish> 99% of the time just means \"commit or something\n> which resolves to a commit, but Git has made it more general for\n> a reason I don't understand\", but of course that's not the right\n> thing to say in the Git documentation :)\n\nYou are describing commit-ish (which allows an annotated or signed\ntag that points at a commit).\n"},{"id":"525161","messageId":"f440d0e4-0754-49a0-9677-980f60a5dbf5@app.fastmail.com","threadId":"64030","inReplyTo":"CALnO6CCvD-uoan=-VW+OmfCk5cLgNm=zENAejL9vX2czahMGxg@mail.gmail.com","subject":"Re: [PATCH 1/5] doc: git-checkout: clarify intro","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-08-28T22:34:23Z","receivedAt":"2025-08-28T22:34:44Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"> I think we've dropped the bit about the default interpretation of \"git\n> checkout <something>\". Maybe\n>\n>     When you run `git checkout <something>`, Git tries to guess whether\n>     `<something>` is intended to be a branch, a commit, or a set of file(s),\n>     and then switches branches, switches commits, or restores the files.\n>\n>     By default, Git interprets `<something>` as a _<tree-ish>_.\n>     [explain what choosing a tree-ish means for the user?]\n>\n>     [Your notes on disambiguation as before]\n\nThanks, will fix. Though I don't think it's accurate that\nGit will treat <something> as a <tree-ish> in this context, since\n`git checkout <tree>` is not valid. Will find a different wording.\n(I get \"fatal: Cannot switch branch to a non-commit\")\n"},{"id":"525172","messageId":"xmqqa53jqaen.fsf@gitster.g","threadId":"64030","inReplyTo":"f440d0e4-0754-49a0-9677-980f60a5dbf5@app.fastmail.com","subject":"Re: [PATCH 1/5] doc: git-checkout: clarify intro","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-28T23:44:16Z","receivedAt":"2025-08-28T23:44:19Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" <julia@jvns.ca> writes:\n\n>> I think we've dropped the bit about the default interpretation of \"git\n>> checkout <something>\". Maybe\n>>\n>>     When you run `git checkout <something>`, Git tries to guess whether\n>>     `<something>` is intended to be a branch, a commit, or a set of file(s),\n>>     and then switches branches, switches commits, or restores the files.\n>>\n>>     By default, Git interprets `<something>` as a _<tree-ish>_.\n>>     [explain what choosing a tree-ish means for the user?]\n>>\n>>     [Your notes on disambiguation as before]\n>\n> Thanks, will fix. Though I don't think it's accurate that\n> Git will treat <something> as a <tree-ish> in this context, since\n> `git checkout <tree>` is not valid. Will find a different wording.\n> (I get \"fatal: Cannot switch branch to a non-commit\")\n\nTrue.  \"git checkout foo\" is disambiguated by seeing if 'foo' can be\ninterpreted as a commit-ish, and if not, if there is a path 'foo' in\nthe working tree.  Otherwise we'd get an ambiguity error.  A commit-ish\nthat is nameed by giving a branch name and other commit-ish then trigger\na bit different codepaths (the former results in checking out a branch,\nthe latter detached HEAD).\n\n"},{"id":"525189","messageId":"pull.1962.v2.git.1756467934.gitgitgadget@gmail.com","threadId":"64030","inReplyTo":"pull.1962.git.1756148933.gitgitgadget@gmail.com","subject":"[PATCH v2 0/5] doc: git-checkout: clarify DESCRIPTION section","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-29T11:45:29Z","receivedAt":"2025-08-29T11:45:37Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":" * Remove the numbered list from the beginning\n * Split up the git checkout [<tree-ish>] <pathspec> section into two\n   sections, one for git checkout <tree-ish> <pathspec> and one for git\n   checkout <pathspec>, to match the SYNOPSIS and because it seems like a\n   clearer approach. Also completely rewrite them to be more accurate and\n   more clear. Use \"Replace\" instead of \"Restore\".\n * Describe what it means to \"switch branches\" in a way that's more\n   accessible to newcomers, and make \"If the local changes conflict with the\n   changes on ...\" more accurate\n * Improve the ARGUMENT DISAMBIGUATION section\n\nJulia Evans (5):\n  doc: git-checkout: clarify intro\n  doc: git-checkout: clarify `git checkout <branch>`\n  doc: git-checkout: don't use \"reset\"\n  doc: git-checkout: deduplicate --detach explanation\n  doc: git-checkout: clarify restoring files section\n\n Documentation/git-checkout.adoc | 114 +++++++++++++++++---------------\n 1 file changed, 60 insertions(+), 54 deletions(-)\n\n\nbase-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1962%2Fjvns%2Fclarify-checkout-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1962/jvns/clarify-checkout-v2\nPull-Request: https://github.com/gitgitgadget/git/pull/1962\n\nRange-diff vs v1:\n\n 1:  a6125a0128 ! 1:  48e7f23029 doc: git-checkout: clarify intro\n     @@ Documentation/git-checkout.adoc: git checkout (-p|--patch) [<tree-ish>] [--] [<p\n      -or the specified tree.  If no pathspec was given, `git checkout` will\n      -also update `HEAD` to set the specified branch as the current\n      -branch.\n     -+`git checkout` has two main modes:\n     -+\n     -+1. **Switch branches**, with `git checkout <branch>`\n     -+2. **Restore a different version of a file**, for example with `git\n     -+   checkout <commit> <filename>` or `git checkout <filename>`\n     ++`git checkout` has two main modes: it can\n     ++**switch branches**, for example with `git checkout <branch>`, and\n     ++**restore files from a different version**, for example with\n     ++`git checkout <commit> <filename>` or `git checkout <filename>`\n      +\n      +See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.\n     -+Here's a description of all of the modes:\n       \n       `git checkout [<branch>]`::\n       \tTo prepare for working on _<branch>_, switch to it by updating\n     @@ Documentation/git-checkout.adoc: $ git log -g -2 HEAD\n      +`<something>` is intended to be a branch, a commit, or a set of file(s),\n      +and then switches branches, switches commits, or restores the files.\n      +\n     -+If there's a conflict, you can use the double dash `--` to distinguish\n     -+between branches and files:\n     ++If there's any ambiguity, Git will treat `<something>` as a branch or\n     ++commit, but you can use the double dash `--` to force Git to treat the\n     ++parameter as a list of files and/or directories, like this:\n      +\n     -+* `git checkout <branch> --` will force Git to treat the parameter as a\n     -+  branch name or commit\n     -+* `git checkout -- <pathspec>` will force Git to treat the parameter as\n     -+  a set of file(s)\n     ++----------\n     ++git checkout -- file.txt\n     ++----------\n       \n       EXAMPLES\n       --------\n 2:  b8873c4529 ! 2:  23a738981a doc: git-checkout: clarify `git checkout <branch>`\n     @@ Commit message\n          Signed-off-by: Julia Evans <julia@jvns.ca>\n      \n       ## Documentation/git-checkout.adoc ##\n     -@@ Documentation/git-checkout.adoc: See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.\n     - Here's a description of all of the modes:\n     +@@ Documentation/git-checkout.adoc: DESCRIPTION\n     + See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.\n       \n       `git checkout [<branch>]`::\n      -\tTo prepare for working on _<branch>_, switch to it by updating\n     @@ Documentation/git-checkout.adoc: See ARGUMENT DISAMBIGUATION below for how Git d\n      -\t`HEAD` 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_<branch>_.\n     -+\tSwitch to _<branch>_. This will update the files in the working tree,\n     -+\tpoint `HEAD` at the branch, and update the index. Local changes to\n     ++\tSwitch to _<branch>_. This sets the current branch to <branch> and\n     ++\tupdates the files in your working directory. Local changes to\n      +\tthe files in the working tree are kept, so that they can be committed\n     -+\tto the _<branch>_. If the local changes conflict with the changes on\n     -+\t_<branch>_, no changes will be made and the checkout operation will\n     -+\tfail.\n     ++\tto the _<branch>_. If the local changes can't be cleanly merged into\n     ++\tthe _<branch>_, no changes will be made and the checkout operation will fail.\n       +\n       If _<branch>_ is not found but there does exist a tracking branch in\n       exactly one remote (call it _<remote>_) with a matching name and\n     @@ Documentation/git-checkout.adoc: exactly one remote (call it _<remote>_) with a\n      -\"check out the current branch\", which is a glorified no-op with\n      -rather expensive side-effects to show only the tracking information,\n      -if it exists, for the current branch.\n     -+Running `git checkout` without specifying a branch will output the\n     -+tracking information, if it exists, for the current branch, but it's\n     -+slower than getting the same information from `git status`.\n     ++Running `git checkout` without specifying a branch has no effect except\n     ++to print out the tracking information for the current branch.\n       \n       `git checkout (-b|-B) <new-branch> [<start-point>]`::\n       \n 3:  0a3915264b ! 3:  360051d2a6 doc: git-checkout: don't use \"reset\"\n     @@ Commit message\n          Signed-off-by: Julia Evans <julia@jvns.ca>\n      \n       ## Documentation/git-checkout.adoc ##\n     -@@ Documentation/git-checkout.adoc: slower than getting the same information from `git status`.\n     +@@ Documentation/git-checkout.adoc: to print out the tracking information for the current branch.\n       \t`--track` without `-b` implies branch creation; see the\n       \tdescription of `--track` below.\n       +\n 4:  2221a6bfb5 = 4:  6f3e485c33 doc: git-checkout: deduplicate --detach explanation\n 5:  b641874627 ! 5:  9c0119e70d doc: git-checkout: clarify restoring files section\n     @@ Metadata\n       ## Commit message ##\n          doc: git-checkout: clarify restoring files section\n      \n     -    - Use the term \"Restore\" to mirror `git restore`\n     +    - Split up the forms `git checkout file.txt` and\n     +      `git checkout main file.txt` to match what's given in the SYNOPSIS\n     +    - Remove `-f` from the SYNOPSIS for the second form, since according to\n     +      this man page it is not relevant in that context\n          - Many Git users do not know what a \"tree-ish\" is. Clarify by using an\n            example of each case, and by saying \"commit or tree\" in the text\n            instead of \"<tree-ish>\"\n     @@ Commit message\n            file's contents\" where appropriate, since Git often uses \"stage\" as a\n            verb to mean the same thing as \"add to the index\" and it's a more\n            familiar term.\n     +    - Use \"Discard unstaged changes\" instead of \"checking out paths from\n     +      the index\" where relevant\n      \n          Signed-off-by: Julia Evans <julia@jvns.ca>\n      \n       ## Documentation/git-checkout.adoc ##\n     -@@ Documentation/git-checkout.adoc: Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.\n     - `git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...`::\n     - `git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]`::\n     +@@ Documentation/git-checkout.adoc: git checkout [-q] [-f] [-m] [<branch>]\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] <tree-ish> [--] <pathspec>...\n     +-git checkout [-f] <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]\n     ++git checkout <tree-ish> [--] <pathspec>...\n     ++git checkout <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]\n     + git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...\n     + git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]\n     + git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]\n     +@@ Documentation/git-checkout.adoc: that is, the branch will not be created or modified unless\n     + +\n     + Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.\n     + \n     +-`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...`::\n     +-`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]`::\n     ++`git checkout <tree-ish> [--] <pathspec>...`::\n     ++`git checkout <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]`::\n       \n      -\tOverwrite the contents of the files that match the pathspec.\n      -\tWhen the _<tree-ish>_ (most often a commit) is not given,\n      -\toverwrite working tree with the contents in the index.\n      -\tWhen the _<tree-ish>_ is given, overwrite both the index and\n      -\tthe working tree with the contents at the _<tree-ish>_.\n     -+\tRestore another version of the file(s) that match the pathspec.\n     ++\tReplace the specified files and/or directories with the version from\n     ++\tthe given commit or 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     -+If you specify a commit or tree to restore from (for example `git\n     -+checkout main file.txt`), this will restore the version of the file(s)\n     -+from that commit or tree. This overwrites the file in the working\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 re-create the original conflicted merge result.\n     ++For example, `git checkout main file.txt` will restore the version\n     ++of `file.txt` from `main`. This overwrites the file in the working\n      +directory and stages the file's contents.\n     + \n     ++`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] <pathspec>...`::\n     ++`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]`::\n     ++\n     ++\tReplace the specified files and/or directories with the latest\n     ++\tcommitted or staged version.\n     +++\n     ++This overwrites the file(s) you specify with either the staged version\n     ++or the version from the current commit if there is no staged version.\n     ++For example, if you've been editing `file.txt` and you want to discard\n     ++your changes to it, you can run `git checkout file.txt` to replace it\n     ++with the latest committed version.\n      ++\n     -+If you do not specify where to restore from (for example `git checkout\n     -+file.txt`), this will replace the file(s) with the version from the index.\n     -+If you check out a file with an unresolved merge\n     -+conflict, the checkout operation will fail and no changes will be made.\n     -+Using `-f` will ignore the merge conflict.  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 re-create the original conflicted merge result.\n     --\n     ++This will fail if the file has a merge conflict and you haven't yet run\n     ++`git add file.txt` (or something equivalent) to mark it as resolved.\n     ++You can use `-f` to ignore the unmerged files instead of failing, use\n     ++`--ours` or `--theirs` to replace them with the version from a specific\n     ++side of the merge, or use `-m` to replace them with the original\n     ++conflicted merge result.\n       `git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]`::\n     - \tThis is similar to the previous mode, but lets you use the\n     +-\tThis is similar to the previous mode, but lets you use the\n     ++\tThis is similar to the previous two modes, but lets you use the\n       \tinteractive interface to show the \"diff\" output and choose which\n     + \thunks to use in the result.  See below for the description of\n     + \t`--patch` option.\n\n-- \ngitgitgadget\n"},{"id":"525190","messageId":"48e7f230294e131007032ef8850456a5c0493ef9.1756467934.git.gitgitgadget@gmail.com","threadId":"64030","inReplyTo":"pull.1962.v2.git.1756467934.gitgitgadget@gmail.com","subject":"[PATCH v2 1/5] doc: git-checkout: clarify intro","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-29T11:45:30Z","receivedAt":"2025-08-29T11:45:38Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\n- Many users do not understand the terms \"index\" or \"pathspec\". Clarify\n  in the intro by using an example, so that users can understand the\n  basic idea without learning the full definition of \"pathspec\".\n- Use the terminology \"Switch\" and \"Restore\" to mirror `git switch`\n  and `git restore`\n- Reference (and clarify) the ARGUMENT DISAMBIGUATION section\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-checkout.adoc | 29 +++++++++++++++++------------\n 1 file changed, 17 insertions(+), 12 deletions(-)\n\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex 40e02cfd65..c86941ad53 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -20,10 +20,12 @@ git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]\n \n DESCRIPTION\n -----------\n-Updates files in the working tree to match the version in the index\n-or the specified tree.  If no pathspec was given, `git checkout` will\n-also update `HEAD` to set the specified branch as the current\n-branch.\n+`git checkout` has two main modes: it can\n+**switch branches**, for example with `git checkout <branch>`, and\n+**restore files from a different version**, for example with\n+`git checkout <commit> <filename>` or `git checkout <filename>`\n+\n+See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.\n \n `git checkout [<branch>]`::\n \tTo prepare for working on _<branch>_, switch to it by updating\n@@ -511,14 +513,17 @@ $ git log -g -2 HEAD\n ARGUMENT DISAMBIGUATION\n -----------------------\n \n-When there is only one argument given and it is not `--` (e.g. `git\n-checkout abc`), and when the argument is both a valid _<tree-ish>_\n-(e.g. a branch `abc` exists) and a valid _<pathspec>_ (e.g. a file\n-or a directory whose name is \"abc\" exists), Git would usually ask\n-you to disambiguate.  Because checking out a branch is so common an\n-operation, however, `git checkout abc` takes \"abc\" as a _<tree-ish>_\n-in such a situation.  Use `git checkout -- <pathspec>` if you want\n-to checkout these paths out of the index.\n+When you run `git checkout <something>`, Git tries to guess whether\n+`<something>` is intended to be a branch, a commit, or a set of file(s),\n+and then switches branches, switches commits, or restores the files.\n+\n+If there's any ambiguity, Git will treat `<something>` as a branch or\n+commit, but you can use the double dash `--` to force Git to treat the\n+parameter as a list of files and/or directories, like this:\n+\n+----------\n+git checkout -- file.txt\n+----------\n \n EXAMPLES\n --------\n-- \ngitgitgadget\n\n"},{"id":"525191","messageId":"23a738981abd2073c70bbb5dd36eea050065e643.1756467934.git.gitgitgadget@gmail.com","threadId":"64030","inReplyTo":"pull.1962.v2.git.1756467934.gitgitgadget@gmail.com","subject":"[PATCH v2 2/5] doc: git-checkout: clarify `git checkout <branch>`","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-29T11:45:31Z","receivedAt":"2025-08-29T11:45:39Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\n- \"To prepare for working on _<branch>_...\" is confusing to some users:\n  it makes it sound like these are steps that the user has to do, not\n  steps that Git itself will do. Reword it.\n- Use \"changes\" instead of \"modifications\" (which Git normally does)\n- Mention that `git checkout` will fail if there's a merge conflict\n- The current explanation of `You could omit <branch>`... is confusing\n  to users (what are the \"expensive side effects\"? what's a better way\n  of getting the same info?). Be more direct and mention that `git\n  status` is likely a better option.\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-checkout.adoc | 16 +++++++---------\n 1 file changed, 7 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex c86941ad53..4de3ac6680 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -28,11 +28,11 @@ DESCRIPTION\n See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.\n \n `git checkout [<branch>]`::\n-\tTo prepare for working on _<branch>_, switch to it by updating\n-\tthe index and the files in the working tree, and by pointing\n-\t`HEAD` 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_<branch>_.\n+\tSwitch to _<branch>_. This sets the current branch to <branch> and\n+\tupdates the files in your working directory. Local changes to\n+\tthe files in the working tree are kept, so that they can be committed\n+\tto the _<branch>_. If the local changes can't be cleanly merged into\n+\tthe _<branch>_, no changes will be made and the checkout operation will fail.\n +\n If _<branch>_ is not found but there does exist a tracking branch in\n exactly one remote (call it _<remote>_) with a matching name and\n@@ -42,10 +42,8 @@ exactly one remote (call it _<remote>_) with a matching name and\n $ git checkout -b <branch> --track <remote>/<branch>\n ------------\n +\n-You could omit _<branch>_, in which case the command degenerates to\n-\"check out the current branch\", which is a glorified no-op with\n-rather expensive side-effects to show only the tracking information,\n-if it exists, for the current branch.\n+Running `git checkout` without specifying a branch has no effect except\n+to print out the tracking information for the current branch.\n \n `git checkout (-b|-B) <new-branch> [<start-point>]`::\n \n-- \ngitgitgadget\n\n"},{"id":"525192","messageId":"360051d2a656727ca42d489de81ffec9b23a6386.1756467934.git.gitgitgadget@gmail.com","threadId":"64030","inReplyTo":"pull.1962.v2.git.1756467934.gitgitgadget@gmail.com","subject":"[PATCH v2 3/5] doc: git-checkout: don't use \"reset\"","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-29T11:45:32Z","receivedAt":"2025-08-29T11:45:41Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nMany Git users don't know what the term \"reset\" means. Resolve this by:\n\n- Expanding it into its definition, in one case\n- Giving a simpler but still accurate explanation (\"the branch will not\n  be created or modified\"), in the other case\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-checkout.adoc | 11 +++++------\n 1 file changed, 5 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex 4de3ac6680..e4614674f0 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -54,18 +54,17 @@ to print out the tracking information for the current branch.\n \t`--track` without `-b` implies branch creation; see the\n \tdescription of `--track` below.\n +\n-If `-B` is given, _<new-branch>_ is created if it doesn't exist; otherwise, it\n-is reset. This is the transactional equivalent of\n+If `-B` is given, _<new-branch>_ is created if it doesn't exist;\n+otherwise `<new-branch>` is forced to point at the commit. This is the\n+transactional equivalent of\n +\n ------------\n $ git branch -f <branch> [<start-point>]\n $ git checkout <branch>\n ------------\n +\n-that is to say, the branch is not reset/created unless \"git checkout\" is\n-successful (e.g., when the branch is in use in another worktree, not\n-just the current branch stays the same, but the branch is not reset to\n-the start-point, either).\n+that is, the branch will not be created or modified unless\n+`git checkout` is successful.\n \n `git checkout --detach [<branch>]`::\n `git checkout [--detach] <commit>`::\n-- \ngitgitgadget\n\n"},{"id":"525193","messageId":"6f3e485c3379fba4668fbdf4dde4eec959f6836c.1756467934.git.gitgitgadget@gmail.com","threadId":"64030","inReplyTo":"pull.1962.v2.git.1756467934.gitgitgadget@gmail.com","subject":"[PATCH v2 4/5] doc: git-checkout: deduplicate --detach explanation","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-29T11:45:33Z","receivedAt":"2025-08-29T11:45:42Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nRight now the explanation of `--detach` repeats a lot of the content in\nthe description of `git checkout <branch>`: we can communicate the same\nthing by saying \"This is the same as `git checkout <branch>`, except...\"\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-checkout.adoc | 13 +++----------\n 1 file changed, 3 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex e4614674f0..4d522a5f75 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -69,16 +69,9 @@ that is, the branch will not be created or modified unless\n `git checkout --detach [<branch>]`::\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-\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-When the _<commit>_ argument is a branch name, the `--detach` option can\n-be used to detach `HEAD` at the tip of the branch (`git checkout\n-<branch>` would check out that branch without detaching `HEAD`).\n+\tThe same as `git checkout <branch>`, except that instead of pointing\n+\t`HEAD` at the branch, it points `HEAD` at the commit ID.\n+\tSee the \"DETACHED HEAD\" section below for more.\n +\n Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.\n \n-- \ngitgitgadget\n\n"},{"id":"525194","messageId":"9c0119e70d6bdb49a8b46ae74e12c4827a7a9173.1756467934.git.gitgitgadget@gmail.com","threadId":"64030","inReplyTo":"pull.1962.v2.git.1756467934.gitgitgadget@gmail.com","subject":"[PATCH v2 5/5] doc: git-checkout: clarify restoring files section","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-29T11:45:34Z","receivedAt":"2025-08-29T11:45:43Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\n- Split up the forms `git checkout file.txt` and\n  `git checkout main file.txt` to match what's given in the SYNOPSIS\n- Remove `-f` from the SYNOPSIS for the second form, since according to\n  this man page it is not relevant in that context\n- Many Git users do not know what a \"tree-ish\" is. Clarify by using an\n  example of each case, and by saying \"commit or tree\" in the text\n  instead of \"<tree-ish>\"\n- Many Git users do not know what the \"index\" is. Instead say \"stage the\n  file's contents\" where appropriate, since Git often uses \"stage\" as a\n  verb to mean the same thing as \"add to the index\" and it's a more\n  familiar term.\n- Use \"Discard unstaged changes\" instead of \"checking out paths from\n  the index\" where relevant\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-checkout.adoc | 45 ++++++++++++++++++++-------------\n 1 file changed, 28 insertions(+), 17 deletions(-)\n\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex 4d522a5f75..dababe452a 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -12,8 +12,8 @@ git checkout [-q] [-f] [-m] [<branch>]\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] <tree-ish> [--] <pathspec>...\n-git checkout [-f] <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]\n+git checkout <tree-ish> [--] <pathspec>...\n+git checkout <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]\n git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...\n git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]\n git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]\n@@ -75,25 +75,36 @@ that is, the branch will not be created or modified unless\n +\n Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.\n \n-`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...`::\n-`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]`::\n+`git checkout <tree-ish> [--] <pathspec>...`::\n+`git checkout <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]`::\n \n-\tOverwrite the contents of the files that match the pathspec.\n-\tWhen the _<tree-ish>_ (most often a commit) is not given,\n-\toverwrite working tree with the contents in the index.\n-\tWhen the _<tree-ish>_ is given, overwrite both the index and\n-\tthe working tree with the contents at the _<tree-ish>_.\n+\tReplace the specified files and/or directories with the version from\n+\tthe given commit or 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-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 re-create the original conflicted merge result.\n+For example, `git checkout main file.txt` will restore the version\n+of `file.txt` from `main`. This overwrites the file in the working\n+directory and stages the file's contents.\n \n+`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] <pathspec>...`::\n+`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]`::\n+\n+\tReplace the specified files and/or directories with the latest\n+\tcommitted or staged version.\n++\n+This overwrites the file(s) you specify with either the staged version\n+or the version from the current commit if there is no staged version.\n+For example, if you've been editing `file.txt` and you want to discard\n+your changes to it, you can run `git checkout file.txt` to replace it\n+with the latest committed version.\n++\n+This will fail if the file has a merge conflict and you haven't yet run\n+`git add file.txt` (or something equivalent) to mark it as resolved.\n+You can use `-f` to ignore the unmerged files instead of failing, use\n+`--ours` or `--theirs` to replace them with the version from a specific\n+side of the merge, or use `-m` to replace them with the original\n+conflicted merge result.\n `git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]`::\n-\tThis is similar to the previous mode, but lets you use the\n+\tThis is similar to the previous two modes, but lets you use the\n \tinteractive interface to show the \"diff\" output and choose which\n \thunks to use in the result.  See below for the description of\n \t`--patch` option.\n-- \ngitgitgadget\n"},{"id":"525204","messageId":"CALnO6CBvsWZe77ireTxBoPBuHem1J3Qrn9H6GZvA-w59ytAqVw@mail.gmail.com","threadId":"64030","inReplyTo":"xmqqa53jqaen.fsf@gitster.g","subject":"Re: [PATCH 1/5] doc: git-checkout: clarify intro","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-08-29T13:39:28Z","receivedAt":"2025-08-29T13:39:41Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Thu, Aug 28, 2025 at 7:44 PM Junio C Hamano <gitster@pobox.com> wrote:\n>\n> \"Julia Evans\" <julia@jvns.ca> writes:\n>\n> >> I think we've dropped the bit about the default interpretation of \"git\n> >> checkout <something>\". Maybe\n> >>\n> >>     When you run `git checkout <something>`, Git tries to guess whether\n> >>     `<something>` is intended to be a branch, a commit, or a set of file(s),\n> >>     and then switches branches, switches commits, or restores the files.\n> >>\n> >>     By default, Git interprets `<something>` as a _<tree-ish>_.\n> >>     [explain what choosing a tree-ish means for the user?]\n> >>\n> >>     [Your notes on disambiguation as before]\n> >\n> > Thanks, will fix. Though I don't think it's accurate that\n> > Git will treat <something> as a <tree-ish> in this context, since\n> > `git checkout <tree>` is not valid. Will find a different wording.\n> > (I get \"fatal: Cannot switch branch to a non-commit\")\n\nInteresting. A docs bug! :) AFAICT it comes from 19e5656345\n(checkout.txt: document a common case that ignores ambiguation rules,\n2016-09-07). I was a novice then and don't know the behavior from that\nperiod, nor did I bother to find out whether \"tree-ish\" matched the\nbehavior at the time and has changed or was simply wrong from the\nstart. Good catch.\n\n> True.  \"git checkout foo\" is disambiguated by seeing if 'foo' can be\n> interpreted as a commit-ish, and if not, if there is a path 'foo' in\n> the working tree.  Otherwise we'd get an ambiguity error.  A commit-ish\n> that is nameed by giving a branch name and other commit-ish then trigger\n> a bit different codepaths (the former results in checking out a branch,\n> the latter detached HEAD).\n\nYep, makes sense.\n\n-- \nD. Ben Knoble\n"},{"id":"525205","messageId":"CALnO6CDJ72-vDYuf_9LzQ-U+Rc_em77WNO2nqNgQ-Cy=T=g3Kg@mail.gmail.com","threadId":"64030","inReplyTo":"2efb789d-db2d-4dae-ae81-373bd231c3c6@app.fastmail.com","subject":"Re: [PATCH 5/5] doc: git-checkout: clarify restoring files section","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-08-29T13:48:19Z","receivedAt":"2025-08-29T13:48:32Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Thu, Aug 28, 2025 at 4:00 PM Julia Evans <julia@jvns.ca> wrote:\n>\n> > Wishful thinking (see glossary comments): I wish we could teach them\n> > about \"tree-ish\"s here rather than stop using useful shorthands\n> > altogether. Of course, then we have to wonder where we can use the\n> > shorthand and where we must do the \"spell it out (give an\n> > abbreviation)\" dance. Hm.\n>\n> What I find hard about documenting cases like this is identifying\n> the use case for providing so much flexibility\n> (\"you can pass any tree, not just a commit!), since personally\n> I've never passed anything to `git checkout` other than a commit.\n\nThis makes sense, and: I think some of how I learned more Git was to\nread the manuals, look up things I wasn't familiar with, and then play\nwith them :) So in a sense my wishful thinking is about sign-posting\n\"here's this other nook to explore if you're curious\" (knowing that\n~70% or or more simply won't be).\n\n> I've been trying to think of examples of cases where it's useful\n> to pass a tree instead of a commit. I can see that it's possible to run\n> something like this\n>\n> $ git checkout HEAD:Documentation/ git-commit.adoc\n>\n> to restore `file.txt` into a different directory than it was originally.\n> This seems cool in theory but it's hard for me to see why it's useful,\n> which makes it hard for me to document. What I would tell a friend is\n> \"<tree-ish> 99% of the time just means \"commit or something\n> which resolves to a commit, but Git has made it more general for\n> a reason I don't understand\", but of course that's not the right\n> thing to say in the Git documentation :)\n\nI would say that it's more general in part because it can be: the data\nmodel allows it without any extra effort (not a jab at the\nprogramming, which was probably not easy!). But I'm in a tangent now\nand the latest version is probably fine by me. I just don't want to\nlose the signposts for explorers.\n\n-- \nD. Ben Knoble\n"},{"id":"525215","messageId":"xmqq1poup1am.fsf@gitster.g","threadId":"64030","inReplyTo":"48e7f230294e131007032ef8850456a5c0493ef9.1756467934.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 1/5] doc: git-checkout: clarify intro","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-29T15:58:41Z","receivedAt":"2025-08-29T15:58:44Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> From: Julia Evans <julia@jvns.ca>\n>\n> - Many users do not understand the terms \"index\" or \"pathspec\". Clarify\n>   in the intro by using an example, so that users can understand the\n>   basic idea without learning the full definition of \"pathspec\".\n> - Use the terminology \"Switch\" and \"Restore\" to mirror `git switch`\n>   and `git restore`\n> - Reference (and clarify) the ARGUMENT DISAMBIGUATION section\n>\n> Signed-off-by: Julia Evans <julia@jvns.ca>\n> ---\n\nYou seem to have forgotten to update the proposed log message ...\n\nhttps://lore.kernel.org/git/de40e0ed-ca12-41b0-acd0-3c594078cc14@app.fastmail.com/\n\n... to avoid making it just an enumeration of \"these random things\nwere done in this patch\" (and instead tell a coherent story).\n\nThe same comment applies to many of your patches in this and other\ntopics (I won't repeat for brevity, though, on my review on them).\n\n>  Documentation/git-checkout.adoc | 29 +++++++++++++++++------------\n>  1 file changed, 17 insertions(+), 12 deletions(-)\n>\n> diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\n> index 40e02cfd65..c86941ad53 100644\n> --- a/Documentation/git-checkout.adoc\n> +++ b/Documentation/git-checkout.adoc\n> @@ -20,10 +20,12 @@ git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]\n>  \n>  DESCRIPTION\n>  -----------\n> -Updates files in the working tree to match the version in the index\n> -or the specified tree.  If no pathspec was given, `git checkout` will\n> -also update `HEAD` to set the specified branch as the current\n> -branch.\n> +`git checkout` has two main modes: it can\n> +**switch branches**, for example with `git checkout <branch>`, and\n> +**restore files from a different version**, for example with\n> +`git checkout <commit> <filename>` or `git checkout <filename>`\n> +\n> +See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.\n>  \n>  `git checkout [<branch>]`::\n>  \tTo prepare for working on _<branch>_, switch to it by updating\n> @@ -511,14 +513,17 @@ $ git log -g -2 HEAD\n>  ARGUMENT DISAMBIGUATION\n>  -----------------------\n>  \n> -When there is only one argument given and it is not `--` (e.g. `git\n> -checkout abc`), and when the argument is both a valid _<tree-ish>_\n> -(e.g. a branch `abc` exists) and a valid _<pathspec>_ (e.g. a file\n> -or a directory whose name is \"abc\" exists), Git would usually ask\n> -you to disambiguate.  Because checking out a branch is so common an\n> -operation, however, `git checkout abc` takes \"abc\" as a _<tree-ish>_\n> -in such a situation.  Use `git checkout -- <pathspec>` if you want\n> -to checkout these paths out of the index.\n> +When you run `git checkout <something>`, Git tries to guess whether\n> +`<something>` is intended to be a branch, a commit, or a set of file(s),\n> +and then switches branches, switches commits, or restores the files.\n\n\"Switches branches\" I can understand.  You were on your old branch\n(your HEAD usually is pointing at some branch), and you move to your\nnew branch by making it your \"current\" branch.\n\nI do not understand \"switches commits\".  When you move to a commit\n(i.e. your HEAD can point directly at a commit without referring to\nany branch), are you switching one commit with another?  I do not\nthink users would view it that way.\n\nPhrasing it with \"switch to\" may make it easier to handle.  Then\nyour previous state would not matter as much.\n\n    ... and then switch to the named branch or the named commit, or\n    restores the files in the working tree (i.e. overwrites them\n    from different versions).\n\nperhaps.\n\n> +If there's any ambiguity, Git will treat `<something>` as a branch or\n> +commit, but you can use the double dash `--` to force Git to treat the\n> +parameter as a list of files and/or directories, like this:\n> +\n> +----------\n> +git checkout -- file.txt\n> +----------\n\nGood.\n\n>  \n>  EXAMPLES\n>  --------\n"},{"id":"525217","messageId":"xmqqv7m6nmhz.fsf@gitster.g","threadId":"64030","inReplyTo":"23a738981abd2073c70bbb5dd36eea050065e643.1756467934.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 2/5] doc: git-checkout: clarify `git checkout <branch>`","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-29T16:03:36Z","receivedAt":"2025-08-29T16:03:38Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n>  `git checkout [<branch>]`::\n> -\tTo prepare for working on _<branch>_, switch to it by updating\n> -\tthe index and the files in the working tree, and by pointing\n> -\t`HEAD` 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_<branch>_.\n> +\tSwitch to _<branch>_. This sets the current branch to <branch> and\n> +\tupdates the files in your working directory. Local changes to\n> +\tthe files in the working tree are kept, so that they can be committed\n> +\tto the _<branch>_. If the local changes can't be cleanly merged into\n> +\tthe _<branch>_, no changes will be made and the checkout operation will fail.\n\nThe condition to stop you is a bit stronger than that.\n\nBy default, we would not even attempt to \"merge into the branch\" at\nall.  If your previous HEAD and the branch you are switching to are\ndifferent at a path you have local modifications in, then no changes\nwill be made and the checkout will fail.  With \"-m\", we try to merge\nand this merge can leave conflicts for you to sort out.\n\n> @@ -42,10 +42,8 @@ exactly one remote (call it _<remote>_) with a matching name and\n>  $ git checkout -b <branch> --track <remote>/<branch>\n>  ------------\n>  +\n> -You could omit _<branch>_, in which case the command degenerates to\n> -\"check out the current branch\", which is a glorified no-op with\n> -rather expensive side-effects to show only the tracking information,\n> -if it exists, for the current branch.\n> +Running `git checkout` without specifying a branch has no effect except\n> +to print out the tracking information for the current branch.\n\nThis is much better than the crappy original I wrote years ago.\nThanks.\n"},{"id":"525218","messageId":"xmqqh5xqnlmo.fsf@gitster.g","threadId":"64030","inReplyTo":"360051d2a656727ca42d489de81ffec9b23a6386.1756467934.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 3/5] doc: git-checkout: don't use \"reset\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-29T16:22:23Z","receivedAt":"2025-08-29T16:22:26Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> From: Julia Evans <julia@jvns.ca>\n>\n> Many Git users don't know what the term \"reset\" means. Resolve this by:\n\nEven though it is the name of one of the most often used commands?\nAnd yet a separate step in this series made the claim that everybody\nknows what \"switch\" means because it is the name of another command?\n\nI think the source of the problem is not that they \"don't know what\nthe term means\" at all.  Isn't the real problem that the use of the\nverb in the original sentence you are correcting in this patch is\nvague and does not say what the branch is reset *to*?\n\n> - Expanding it into its definition, in one case\n\n    The description says \"-B <branch>\" resets the branch if it\n    exists, but does not say what it resets to.  Rephrase to clarify\n    that it is made to point at the specified commit.\n\nor something?\n\n> - Giving a simpler but still accurate explanation (\"the branch will not\n>   be created or modified\"), in the other case\n\nBy the way this kind of use of bulleted list in a proposed log\nmessage I do not mind all that much.  What I reacted to was a list\nwithout the introducing text (in the case of this patch, \"resolve\nthis by doing these things:\").\n>\n> Signed-off-by: Julia Evans <julia@jvns.ca>\n> ---\n>  Documentation/git-checkout.adoc | 11 +++++------\n>  1 file changed, 5 insertions(+), 6 deletions(-)\n>\n> diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\n> index 4de3ac6680..e4614674f0 100644\n> --- a/Documentation/git-checkout.adoc\n> +++ b/Documentation/git-checkout.adoc\n> @@ -54,18 +54,17 @@ to print out the tracking information for the current branch.\n>  \t`--track` without `-b` implies branch creation; see the\n>  \tdescription of `--track` below.\n>  +\n> -If `-B` is given, _<new-branch>_ is created if it doesn't exist; otherwise, it\n> -is reset. This is the transactional equivalent of\n> +If `-B` is given, _<new-branch>_ is created if it doesn't exist;\n> +otherwise `<new-branch>` is forced to point at the commit. ...\n\nGood.\n\n> ... This is the\n> +transactional equivalent of\n>  +\n>  ------------\n>  $ git branch -f <branch> [<start-point>]\n>  $ git checkout <branch>\n>  ------------\n>  +\n> -that is to say, the branch is not reset/created unless \"git checkout\" is\n> -successful (e.g., when the branch is in use in another worktree, not\n> -just the current branch stays the same, but the branch is not reset to\n> -the start-point, either).\n> +that is, the branch will not be created or modified unless\n> +`git checkout` is successful.\n>  \n>  `git checkout --detach [<branch>]`::\n>  `git checkout [--detach] <commit>`::\n\nThis is in response to \"transactional equivalent\".  I've always felt\nthat there is no need to say \"transactional\" in this at all.  IOW, I\nwouldn't have minded if we rewrote this more heavily.\n\nWhen you have to clarify with things like \"that is\", \"what this\nmeans is\", etc., after some text, I've often found that the result\nbecomes crispier and more clear if we removed fuzzy text that needed\nsuch clarification and rewrite the sentence using elements form only\nthe clarifying text.\n\n    If `-B` is given, _<new-branch>_ is created if it doesn't exist,\n    otherwise, it is made to point at the given commit.  And the\n    branch is made the current branch.\n    +\n    Creation of the new branch or reseting of the existing branch to\n    point at the commit happens only if the resulting branch can be\n    successfully checked out.  Oterwise branch creation is not done\n    and the exiting branch is left as-is.\n\nor something?  I dunno.\n\n"},{"id":"525243","messageId":"xmqqiki5n8r0.fsf@gitster.g","threadId":"64030","inReplyTo":"CALnO6CCvD-uoan=-VW+OmfCk5cLgNm=zENAejL9vX2czahMGxg@mail.gmail.com","subject":"Re: [PATCH 1/5] doc: git-checkout: clarify intro","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-29T21:00:35Z","receivedAt":"2025-08-29T21:00:38Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"D. Ben Knoble\" <ben.knoble@gmail.com> writes:\n\n>> +1. **Switch branches**, with `git checkout <branch>`\n>> +2. **Restore a different version of a file**, for example with `git\n>> +   checkout <commit> <filename>` or `git checkout <filename>`\n>> +\n>> +See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.\n>> +Here's a description of all of the modes:\n>\n> This looks good—I initially scratched my head thinking there were 3\n> modes, but unifying \"update files to match index\" and \"update files to\n> match specified tree\" is easier to digest in this presentation.\n\nYup.  And on the other side, unifying \"prepare to extend the history\nof a branch\" and \"prepare to create a new history starting at a\ncommit\" (aka detached HEAD) into one is equally good.\n\nBut I am wondering what is the most common perception of the second\nmode.  I've always thought that the action was to \"grab things out\nof the index or out of a tree-ish and overwrite the working tree\nfiles\", and it takes me an extra effort to read, think, understand\nand finally realize that \"update working tree files to match either\nthe index or a tree-ish\" is equivalent to it.\n\nAnyway, thanks for a review.\n"},{"id":"525280","messageId":"9d708558-df36-4bdd-a914-522228b27215@app.fastmail.com","threadId":"64030","inReplyTo":"xmqqh5xqnlmo.fsf@gitster.g","subject":"Re: [PATCH v2 3/5] doc: git-checkout: don't use \"reset\"","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-09-01T14:28:44Z","receivedAt":"2025-09-01T14:29:44Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"> I think the source of the problem is not that they \"don't know what\n> the term means\" at all.  Isn't the real problem that the use of the\n> verb in the original sentence you are correcting in this patch is\n> vague and does not say what the branch is reset *to*?\n\nI agree this is a reasonable approach here, will try that.\n\n>> Many Git users don't know what the term \"reset\" means. Resolve this by:\n>\n> Even though it is the name of one of the most often used commands?\n> And yet a separate step in this series made the claim that everybody\n> knows what \"switch\" means because it is the name of another command?\n\nI'm surprised to hear you say that \"reset\" is one of the most often\nused Git commands -- what I frequently hear from Git users is that they\nuse `git reset` only in \"emergencies\" where something has gone wrong\nand that they're afraid of using it.\n\nI'm curious about whether there are any datasets about which Git\ncommands are the most frequently used, or if it would be worth me\ntrying to build one.\n\n>> ... This is the\n>> +transactional equivalent of\n>>  +\n>>  ------------\n>>  $ git branch -f <branch> [<start-point>]\n>>  $ git checkout <branch>\n>>  ------------\n>>  +\n>> -that is to say, the branch is not reset/created unless \"git checkout\" is\n>> -successful (e.g., when the branch is in use in another worktree, not\n>> -just the current branch stays the same, but the branch is not reset to\n>> -the start-point, either).\n>> +that is, the branch will not be created or modified unless\n>> +`git checkout` is successful.\n>>  \n>>  `git checkout --detach [<branch>]`::\n>>  `git checkout [--detach] <commit>`::\n>\n> This is in response to \"transactional equivalent\".  I've always felt\n> that there is no need to say \"transactional\" in this at all.  IOW, I\n> wouldn't have minded if we rewrote this more heavily.\n\n\"Transactional equivalent\" was bothering me too and I like the\nidea of rewriting it, will give it a shot.\n"},{"id":"525346","messageId":"xmqqv7m0ltsf.fsf@gitster.g","threadId":"64030","inReplyTo":"9d708558-df36-4bdd-a914-522228b27215@app.fastmail.com","subject":"Re: [PATCH v2 3/5] doc: git-checkout: don't use \"reset\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-09-02T16:10:24Z","receivedAt":"2025-09-02T16:10:27Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" <julia@jvns.ca> writes:\n\n> I'm surprised to hear you say that \"reset\" is one of the most often\n> used Git commands -- what I frequently hear from Git users is that they\n> use `git reset` only in \"emergencies\" where something has gone wrong\n> and that they're afraid of using it.\n\nFor the list of commands that have been historically considered\n\"common\":\n\n    $ git -h\n\nis meant to serve a good guide.  We may want to cull/update some\nentries (like, \"backfill\" which should not be more prominent than\n\"maintenance\", for example), but I think it is not far off or way\ntoo stale (for one thing, it no longer lists checkout but gives two\nseparate commands, restore and switch, which are no longer marked as\nexperimental).\n\n>>>  `git checkout --detach [<branch>]`::\n>>>  `git checkout [--detach] <commit>`::\n>>\n>> This is in response to \"transactional equivalent\".  I've always felt\n>> that there is no need to say \"transactional\" in this at all.  IOW, I\n>> wouldn't have minded if we rewrote this more heavily.\n>\n> \"Transactional equivalent\" was bothering me too and I like the\n> idea of rewriting it, will give it a shot.\n\nThanks.\n"},{"id":"525356","messageId":"a9351a8a-09eb-4fc7-92d2-fff5e504dbcc@app.fastmail.com","threadId":"64030","inReplyTo":"xmqq1poup1am.fsf@gitster.g","subject":"Re: [PATCH v2 1/5] doc: git-checkout: clarify intro","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-09-02T17:14:22Z","receivedAt":"2025-09-02T17:14:44Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"> You seem to have forgotten to update the proposed log message ...\n>\n> https://lore.kernel.org/git/de40e0ed-ca12-41b0-acd0-3c594078cc14@app.fastmail.com/\n>\n> ... to avoid making it just an enumeration of \"these random things\n> were done in this patch\" (and instead tell a coherent story).\n\nThanks for the reminder, will work on that. I just realized today that I can\nuse `lazygit` to make it much faster to edit my log messages :)\n\n> I do not understand \"switches commits\".  When you move to a commit\n> (i.e. your HEAD can point directly at a commit without referring to\n> any branch), are you switching one commit with another?  I do not\n> think users would view it that way.\n>\n> Phrasing it with \"switch to\" may make it easier to handle.  Then\n> your previous state would not matter as much.\n\nAgreed that \"switches commits\" is weird, will use \"switches to\".\n"},{"id":"525357","messageId":"2b00569b-bdc9-43e1-8a59-540d13c41a7a@app.fastmail.com","threadId":"64030","inReplyTo":"xmqqv7m6nmhz.fsf@gitster.g","subject":"Re: [PATCH v2 2/5] doc: git-checkout: clarify `git checkout <branch>`","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-09-02T17:16:52Z","receivedAt":"2025-09-02T17:17:13Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"> The condition to stop you is a bit stronger than that.\n>\n> By default, we would not even attempt to \"merge into the branch\" at\n> all.  If your previous HEAD and the branch you are switching to are\n> different at a path you have local modifications in, then no changes\n> will be made and the checkout will fail.  With \"-m\", we try to merge\n> and this merge can leave conflicts for you to sort out.\n\nThanks, I wasn't sure based on the existing text what\n\"modifications are kept\" meant exactly, and I've always been slightly\nhazy about this behaviour. Will fix.\n"},{"id":"525440","messageId":"pull.1962.v3.git.1756918202.gitgitgadget@gmail.com","threadId":"64030","inReplyTo":"pull.1962.v2.git.1756467934.gitgitgadget@gmail.com","subject":"[PATCH v3 0/6] doc: git-checkout: clarify DESCRIPTION section","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-09-03T16:49:56Z","receivedAt":"2025-09-03T16:50:05Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":" * Improve the storytelling in the commit messages\n * Take a different approach to the git checkout -b description (keep reset\n   in -B, but simplify the description of -B a lot)\n * Make the description of git checkout [<branch>] more accurate.\n * Try a different approach to git checkout file.txt (\"Discard any unstaged\n   changes...\")\n\nJulia Evans (6):\n  doc: git-checkout: clarify intro\n  doc: git-checkout: clarify `git checkout <branch>`\n  doc: git-checkout: clarify `-b` and `-B`\n  doc: git-checkout: deduplicate --detach explanation\n  doc: git-checkout: split up restoring files section\n  doc: git-checkout: clarify restoring files section\n\n Documentation/git-checkout.adoc | 147 ++++++++++++++++----------------\n 1 file changed, 72 insertions(+), 75 deletions(-)\n\n\nbase-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1962%2Fjvns%2Fclarify-checkout-v3\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1962/jvns/clarify-checkout-v3\nPull-Request: https://github.com/gitgitgadget/git/pull/1962\n\nRange-diff vs v2:\n\n 1:  48e7f23029 ! 1:  1975384dd0 doc: git-checkout: clarify intro\n     @@ Metadata\n       ## Commit message ##\n          doc: git-checkout: clarify intro\n      \n     -    - Many users do not understand the terms \"index\" or \"pathspec\". Clarify\n     -      in the intro by using an example, so that users can understand the\n     -      basic idea without learning the full definition of \"pathspec\".\n     -    - Use the terminology \"Switch\" and \"Restore\" to mirror `git switch`\n     -      and `git restore`\n     -    - Reference (and clarify) the ARGUMENT DISAMBIGUATION section\n     +    - Reduce use of jargon (\"index\", \"pathspec\", \"tree\") by using an\n     +      example, and by mirroring the \"switch\" and \"restore\" language from the\n     +      first line of the man page.\n     +    - Reference and clarify the ARGUMENT DISAMBIGUATION section, as well\n     +      as fixing a small error (in \"`git checkout abc`, `abc` is a commit,\n     +      not a `_<tree-ish>_`)\n      \n          Signed-off-by: Julia Evans <julia@jvns.ca>\n      \n     @@ Documentation/git-checkout.adoc: $ git log -g -2 HEAD\n      -to checkout these paths out of the index.\n      +When you run `git checkout <something>`, Git tries to guess whether\n      +`<something>` is intended to be a branch, a commit, or a set of file(s),\n     -+and then switches branches, switches commits, or restores the files.\n     ++and then either switches to that branch or commit or restores the\n     ++specified files.\n      +\n      +If there's any ambiguity, Git will treat `<something>` as a branch or\n      +commit, but you can use the double dash `--` to force Git to treat the\n 2:  23a738981a ! 2:  940cd17e7e doc: git-checkout: clarify `git checkout <branch>`\n     @@ Metadata\n       ## Commit message ##\n          doc: git-checkout: clarify `git checkout <branch>`\n      \n     -    - \"To prepare for working on _<branch>_...\" is confusing to some users:\n     -      it makes it sound like these are steps that the user has to do, not\n     -      steps that Git itself will do. Reword it.\n     -    - Use \"changes\" instead of \"modifications\" (which Git normally does)\n     -    - Mention that `git checkout` will fail if there's a merge conflict\n     -    - The current explanation of `You could omit <branch>`... is confusing\n     -      to users (what are the \"expensive side effects\"? what's a better way\n     -      of getting the same info?). Be more direct and mention that `git\n     -      status` is likely a better option.\n     +    - Reduce use of jargon (\"index\", \"HEAD\")\n     +    - Clarify that only identical files will be left unchanged, and that\n     +      `git checkout` will fail rather than overwrite an unchanged file\n     +    - Explain what `git checkout` with no arguments does in a more direct\n     +      way\n      \n          Signed-off-by: Julia Evans <julia@jvns.ca>\n      \n     @@ Documentation/git-checkout.adoc: DESCRIPTION\n      -\t`HEAD` 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_<branch>_.\n     -+\tSwitch to _<branch>_. This sets the current branch to <branch> and\n     -+\tupdates the files in your working directory. Local changes to\n     -+\tthe files in the working tree are kept, so that they can be committed\n     -+\tto the _<branch>_. If the local changes can't be cleanly merged into\n     -+\tthe _<branch>_, no changes will be made and the checkout operation will fail.\n     ++\tSwitch to _<branch>_. This sets the current branch to _<branch>_ and\n     ++\tupdates the files in your working directory. Files which are\n     ++\tidentical in _<branch>_ and your current commit are left unchanged\n     ++\tso that you can keep your uncommitted changes to those files.\n     ++\tThis will not overwrite uncommitted changes to a file: instead it\n     ++\twill fail without making any changes.\n       +\n       If _<branch>_ is not found but there does exist a tracking branch in\n       exactly one remote (call it _<remote>_) with a matching name and\n 3:  360051d2a6 ! 3:  043fec7e66 doc: git-checkout: don't use \"reset\"\n     @@ Metadata\n      Author: Julia Evans <julia@jvns.ca>\n      \n       ## Commit message ##\n     -    doc: git-checkout: don't use \"reset\"\n     +    doc: git-checkout: clarify `-b` and `-B`\n      \n     -    Many Git users don't know what the term \"reset\" means. Resolve this by:\n     -\n     -    - Expanding it into its definition, in one case\n     -    - Giving a simpler but still accurate explanation (\"the branch will not\n     -      be created or modified\"), in the other case\n     +    - Remove some unnecessary detail about `--track` (users can refer\n     +      to the OPTIONS section instead)\n     +    - Explain what the start point defaults to\n     +    - Describe `-B` much more tersely as \"the same as `-b`, except ..\",\n     +      since potential users of `-B` are almost certainly already very\n     +      familiar with `-b`. Move all of the other contents of `-B` to `-b`,\n     +      updating the example so that it's appropriate for `-b`\n      \n          Signed-off-by: Julia Evans <julia@jvns.ca>\n      \n       ## Documentation/git-checkout.adoc ##\n     -@@ Documentation/git-checkout.adoc: to print out the tracking information for the current branch.\n     - \t`--track` without `-b` implies branch creation; see the\n     - \tdescription of `--track` below.\n     - +\n     +@@ Documentation/git-checkout.adoc: $ git checkout -b <branch> --track <remote>/<branch>\n     + Running `git checkout` without specifying a branch has no effect except\n     + to print out the tracking information for the current branch.\n     + \n     +-`git checkout (-b|-B) <new-branch> [<start-point>]`::\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, _<new-branch>_ is created if it doesn't exist; otherwise, it\n      -is reset. This is the transactional equivalent of\n     -+If `-B` is given, _<new-branch>_ is created if it doesn't exist;\n     -+otherwise `<new-branch>` is forced to point at the commit. This is the\n     -+transactional equivalent of\n     - +\n     - ------------\n     - $ git branch -f <branch> [<start-point>]\n     - $ git checkout <branch>\n     - ------------\n     +-+\n     +-------------\n     +-$ git branch -f <branch> [<start-point>]\n     +-$ git checkout <branch>\n     +-------------\n     ++`git checkout -b <new-branch> [<start-point>]`::\n     ++\n     ++\tCreate a new branch named _<new-branch>_, start it at _<start-point>_\n     ++\t(defaults to the current commit), and check out the new branch.\n     ++\tYou can use the `--track` or `--no-track` options to set the branch's\n     ++\tupstream tracking information.\n       +\n      -that is to say, the branch is not reset/created unless \"git checkout\" is\n      -successful (e.g., when the branch is in use in another worktree, not\n      -just the current branch stays the same, but the branch is not reset to\n      -the start-point, either).\n     -+that is, the branch will not be created or modified unless\n     -+`git checkout` is successful.\n     ++This fails without making any changes if there's an error checking out\n     ++_<new-branch>_, for example if checking out the `<start-point>`\n     ++commit would overwrite your uncommitted changes.\n     ++\n     ++`git checkout -B <branch> [<start-point>]`::\n     ++\n     ++\tThe same as `-b`, except that if the branch already exists it\n     ++\tresets `_<branch>_` to the start point instead of creating it.\n       \n       `git checkout --detach [<branch>]`::\n       `git checkout [--detach] <commit>`::\n     +@@ Documentation/git-checkout.adoc: of it\").\n     + \tsee linkgit:git-branch[1] for details.\n     + \n     + `-B <new-branch>`::\n     +-\tCreates the branch _<new-branch>_, start it at _<start-point>_;\n     +-\tif it already exists, then reset it to _<start-point>_. And then\n     +-\tcheck the resulting branch out.  This is equivalent to running\n     +-\t`git branch` with `-f` followed by `git checkout` of that branch;\n     +-\tsee linkgit:git-branch[1] for details.\n     ++\tThe same as `-b`, except that if the branch already exists it\n     ++\tresets `_<branch>_` to the start point instead of creating it.\n     + \n     + `-t`::\n     + `--track[=(direct|inherit)]`::\n     + \tWhen creating a new branch, set up \"upstream\" configuration. See\n     +-\t`--track` in linkgit:git-branch[1] for details.\n     ++\t`--track` in linkgit:git-branch[1] for details. As a convenience,\n     ++\t--track without -b implies branch creation.\n     + +\n     + If no `-b` option is given, the name of the new branch will be\n     + derived from the remote-tracking branch, by looking at the local part of\n 4:  6f3e485c33 ! 4:  6ce31b6278 doc: git-checkout: deduplicate --detach explanation\n     @@ Metadata\n       ## Commit message ##\n          doc: git-checkout: deduplicate --detach explanation\n      \n     -    Right now the explanation of `--detach` repeats a lot of the content in\n     -    the description of `git checkout <branch>`: we can communicate the same\n     -    thing by saying \"This is the same as `git checkout <branch>`, except...\"\n     +    Say that `git checkout --detach` is almost the same as `git checkout`\n     +    instead of duplicating the content of the `git checkout` section, since\n     +    many users will already be familiar with what `git checkout` does.\n      \n          Signed-off-by: Julia Evans <julia@jvns.ca>\n      \n       ## Documentation/git-checkout.adoc ##\n     -@@ Documentation/git-checkout.adoc: that is, the branch will not be created or modified unless\n     +@@ Documentation/git-checkout.adoc: commit would overwrite your uncommitted changes.\n       `git checkout --detach [<branch>]`::\n       `git checkout [--detach] <commit>`::\n       \n 5:  9c0119e70d ! 5:  24793f9a45 doc: git-checkout: clarify restoring files section\n     @@ Metadata\n      Author: Julia Evans <julia@jvns.ca>\n      \n       ## Commit message ##\n     -    doc: git-checkout: clarify restoring files section\n     +    doc: git-checkout: split up restoring files section\n      \n     -    - Split up the forms `git checkout file.txt` and\n     -      `git checkout main file.txt` to match what's given in the SYNOPSIS\n     -    - Remove `-f` from the SYNOPSIS for the second form, since according to\n     -      this man page it is not relevant in that context\n     -    - Many Git users do not know what a \"tree-ish\" is. Clarify by using an\n     -      example of each case, and by saying \"commit or tree\" in the text\n     -      instead of \"<tree-ish>\"\n     -    - Many Git users do not know what the \"index\" is. Instead say \"stage the\n     -      file's contents\" where appropriate, since Git often uses \"stage\" as a\n     -      verb to mean the same thing as \"add to the index\" and it's a more\n     -      familiar term.\n     -    - Use \"Discard unstaged changes\" instead of \"checking out paths from\n     -      the index\" where relevant\n     +    Will make it easier to explain the two versions clearly in the following\n     +    commit. As a bonus, now the structure of the DESCRIPTION\n     +    matches the SYNOPSIS.\n     +\n     +    Also remove `-f` from `git checkout <tree-ish> <pathspec>` since it's\n     +    not relevant in that context.\n      \n          Signed-off-by: Julia Evans <julia@jvns.ca>\n      \n     @@ Documentation/git-checkout.adoc: git checkout [-q] [-f] [-m] [<branch>]\n       git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...\n       git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]\n       git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]\n     -@@ Documentation/git-checkout.adoc: that is, the branch will not be created or modified unless\n     +@@ Documentation/git-checkout.adoc: commit would overwrite your uncommitted changes.\n       +\n       Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.\n       \n     @@ Documentation/git-checkout.adoc: that is, the branch will not be created or modi\n      -\toverwrite working tree with the contents in the index.\n      -\tWhen the _<tree-ish>_ is given, overwrite both the index and\n      -\tthe working tree with the contents at the _<tree-ish>_.\n     -+\tReplace the specified files and/or directories with the version from\n     -+\tthe given commit or 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     --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 re-create the original conflicted merge result.\n     -+For example, `git checkout main file.txt` will restore the version\n     -+of `file.txt` from `main`. This overwrites the file in the working\n     -+directory and stages the file's contents.\n     - \n     -+`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] <pathspec>...`::\n     ++\tOverwrite both the index and the working tree with the\n     ++\tcontents at the _<tree-ish>_ for the files that match the pathspec.\n     ++\n     ++`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...`::\n      +`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]`::\n      +\n     -+\tReplace the specified files and/or directories with the latest\n     -+\tcommitted or staged version.\n     -++\n     -+This overwrites the file(s) you specify with either the staged version\n     -+or the version from the current commit if there is no staged version.\n     -+For example, if you've been editing `file.txt` and you want to discard\n     -+your changes to it, you can run `git checkout file.txt` to replace it\n     -+with the latest committed version.\n     -++\n     -+This will fail if the file has a merge conflict and you haven't yet run\n     -+`git add file.txt` (or something equivalent) to mark it as resolved.\n     -+You can use `-f` to ignore the unmerged files instead of failing, use\n     -+`--ours` or `--theirs` to replace them with the version from a specific\n     -+side of the merge, or use `-m` to replace them with the original\n     -+conflicted merge result.\n     ++\tOverwrite working tree with the contents in the index for the files\n     ++\tthat match the pathspec.\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     +@@ Documentation/git-checkout.adoc: 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       `git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]`::\n      -\tThis is similar to the previous mode, but lets you use the\n      +\tThis is similar to the previous two modes, but lets you use the\n -:  ---------- > 6:  90fe48cfe3 doc: git-checkout: clarify restoring files section\n\n-- \ngitgitgadget\n"},{"id":"525441","messageId":"1975384dd04c376fcdf74c9f4217b81aec64e8cf.1756918202.git.gitgitgadget@gmail.com","threadId":"64030","inReplyTo":"pull.1962.v3.git.1756918202.gitgitgadget@gmail.com","subject":"[PATCH v3 1/6] doc: git-checkout: clarify intro","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-09-03T16:49:57Z","receivedAt":"2025-09-03T16:50:07Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\n- Reduce use of jargon (\"index\", \"pathspec\", \"tree\") by using an\n  example, and by mirroring the \"switch\" and \"restore\" language from the\n  first line of the man page.\n- Reference and clarify the ARGUMENT DISAMBIGUATION section, as well\n  as fixing a small error (in \"`git checkout abc`, `abc` is a commit,\n  not a `_<tree-ish>_`)\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-checkout.adoc | 30 ++++++++++++++++++------------\n 1 file changed, 18 insertions(+), 12 deletions(-)\n\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex 40e02cfd65..218d3dd13d 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -20,10 +20,12 @@ git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]\n \n DESCRIPTION\n -----------\n-Updates files in the working tree to match the version in the index\n-or the specified tree.  If no pathspec was given, `git checkout` will\n-also update `HEAD` to set the specified branch as the current\n-branch.\n+`git checkout` has two main modes: it can\n+**switch branches**, for example with `git checkout <branch>`, and\n+**restore files from a different version**, for example with\n+`git checkout <commit> <filename>` or `git checkout <filename>`\n+\n+See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.\n \n `git checkout [<branch>]`::\n \tTo prepare for working on _<branch>_, switch to it by updating\n@@ -511,14 +513,18 @@ $ git log -g -2 HEAD\n ARGUMENT DISAMBIGUATION\n -----------------------\n \n-When there is only one argument given and it is not `--` (e.g. `git\n-checkout abc`), and when the argument is both a valid _<tree-ish>_\n-(e.g. a branch `abc` exists) and a valid _<pathspec>_ (e.g. a file\n-or a directory whose name is \"abc\" exists), Git would usually ask\n-you to disambiguate.  Because checking out a branch is so common an\n-operation, however, `git checkout abc` takes \"abc\" as a _<tree-ish>_\n-in such a situation.  Use `git checkout -- <pathspec>` if you want\n-to checkout these paths out of the index.\n+When you run `git checkout <something>`, Git tries to guess whether\n+`<something>` is intended to be a branch, a commit, or a set of file(s),\n+and then either switches to that branch or commit or restores the\n+specified files.\n+\n+If there's any ambiguity, Git will treat `<something>` as a branch or\n+commit, but you can use the double dash `--` to force Git to treat the\n+parameter as a list of files and/or directories, like this:\n+\n+----------\n+git checkout -- file.txt\n+----------\n \n EXAMPLES\n --------\n-- \ngitgitgadget\n\n"},{"id":"525442","messageId":"940cd17e7e15684c0ca8c7b2994835f63e1fd02a.1756918202.git.gitgitgadget@gmail.com","threadId":"64030","inReplyTo":"pull.1962.v3.git.1756918202.gitgitgadget@gmail.com","subject":"[PATCH v3 2/6] doc: git-checkout: clarify `git checkout <branch>`","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-09-03T16:49:58Z","receivedAt":"2025-09-03T16:50:08Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\n- Reduce use of jargon (\"index\", \"HEAD\")\n- Clarify that only identical files will be left unchanged, and that\n  `git checkout` will fail rather than overwrite an unchanged file\n- Explain what `git checkout` with no arguments does in a more direct\n  way\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-checkout.adoc | 17 ++++++++---------\n 1 file changed, 8 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex 218d3dd13d..50923ff118 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -28,11 +28,12 @@ DESCRIPTION\n See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.\n \n `git checkout [<branch>]`::\n-\tTo prepare for working on _<branch>_, switch to it by updating\n-\tthe index and the files in the working tree, and by pointing\n-\t`HEAD` 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_<branch>_.\n+\tSwitch to _<branch>_. This sets the current branch to _<branch>_ and\n+\tupdates the files in your working directory. Files which are\n+\tidentical in _<branch>_ and your current commit are left unchanged\n+\tso that you can keep your uncommitted changes to those files.\n+\tThis will not overwrite uncommitted changes to a file: instead it\n+\twill fail without making any changes.\n +\n If _<branch>_ is not found but there does exist a tracking branch in\n exactly one remote (call it _<remote>_) with a matching name and\n@@ -42,10 +43,8 @@ exactly one remote (call it _<remote>_) with a matching name and\n $ git checkout -b <branch> --track <remote>/<branch>\n ------------\n +\n-You could omit _<branch>_, in which case the command degenerates to\n-\"check out the current branch\", which is a glorified no-op with\n-rather expensive side-effects to show only the tracking information,\n-if it exists, for the current branch.\n+Running `git checkout` without specifying a branch has no effect except\n+to print out the tracking information for the current branch.\n \n `git checkout (-b|-B) <new-branch> [<start-point>]`::\n \n-- \ngitgitgadget\n\n"},{"id":"525443","messageId":"043fec7e66dc57427f441b020f9eb7862ba93fc1.1756918202.git.gitgitgadget@gmail.com","threadId":"64030","inReplyTo":"pull.1962.v3.git.1756918202.gitgitgadget@gmail.com","subject":"[PATCH v3 3/6] doc: git-checkout: clarify `-b` and `-B`","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-09-03T16:49:59Z","receivedAt":"2025-09-03T16:50:09Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\n- Remove some unnecessary detail about `--track` (users can refer\n  to the OPTIONS section instead)\n- Explain what the start point defaults to\n- Describe `-B` much more tersely as \"the same as `-b`, except ..\",\n  since potential users of `-B` are almost certainly already very\n  familiar with `-b`. Move all of the other contents of `-B` to `-b`,\n  updating the example so that it's appropriate for `-b`\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-checkout.adoc | 44 ++++++++++++++-------------------\n 1 file changed, 18 insertions(+), 26 deletions(-)\n\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex 50923ff118..a2777fb5b0 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -46,27 +46,21 @@ $ git checkout -b <branch> --track <remote>/<branch>\n Running `git checkout` without specifying a branch has no effect except\n to print out the tracking information for the current branch.\n \n-`git checkout (-b|-B) <new-branch> [<start-point>]`::\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, _<new-branch>_ is created if it doesn't exist; otherwise, it\n-is reset. This is the transactional equivalent of\n-+\n-------------\n-$ git branch -f <branch> [<start-point>]\n-$ git checkout <branch>\n-------------\n+`git checkout -b <new-branch> [<start-point>]`::\n+\n+\tCreate a new branch named _<new-branch>_, start it at _<start-point>_\n+\t(defaults to the current commit), and check out the new branch.\n+\tYou can use the `--track` or `--no-track` options to set the branch's\n+\tupstream tracking information.\n +\n-that is to say, the branch is not reset/created unless \"git checkout\" is\n-successful (e.g., when the branch is in use in another worktree, not\n-just the current branch stays the same, but the branch is not reset to\n-the start-point, either).\n+This fails without making any changes if there's an error checking out\n+_<new-branch>_, for example if checking out the `<start-point>`\n+commit would overwrite your uncommitted changes.\n+\n+`git checkout -B <branch> [<start-point>]`::\n+\n+\tThe same as `-b`, except that if the branch already exists it\n+\tresets `_<branch>_` to the start point instead of creating it.\n \n `git checkout --detach [<branch>]`::\n `git checkout [--detach] <commit>`::\n@@ -156,16 +150,14 @@ of it\").\n \tsee linkgit:git-branch[1] for details.\n \n `-B <new-branch>`::\n-\tCreates the branch _<new-branch>_, start it at _<start-point>_;\n-\tif it already exists, then reset it to _<start-point>_. And then\n-\tcheck the resulting branch out.  This is equivalent to running\n-\t`git branch` with `-f` followed by `git checkout` of that branch;\n-\tsee linkgit:git-branch[1] for details.\n+\tThe same as `-b`, except that if the branch already exists it\n+\tresets `_<branch>_` to the start point instead of creating it.\n \n `-t`::\n `--track[=(direct|inherit)]`::\n \tWhen creating a new branch, set up \"upstream\" configuration. See\n-\t`--track` in linkgit:git-branch[1] for details.\n+\t`--track` in linkgit:git-branch[1] for details. As a convenience,\n+\t--track without -b implies branch creation.\n +\n If no `-b` option is given, the name of the new branch will be\n derived from the remote-tracking branch, by looking at the local part of\n-- \ngitgitgadget\n\n"},{"id":"525444","messageId":"6ce31b62787694610138e052f3d4fcf6ebbcfddd.1756918202.git.gitgitgadget@gmail.com","threadId":"64030","inReplyTo":"pull.1962.v3.git.1756918202.gitgitgadget@gmail.com","subject":"[PATCH v3 4/6] doc: git-checkout: deduplicate --detach explanation","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-09-03T16:50:00Z","receivedAt":"2025-09-03T16:50:10Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nSay that `git checkout --detach` is almost the same as `git checkout`\ninstead of duplicating the content of the `git checkout` section, since\nmany users will already be familiar with what `git checkout` does.\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-checkout.adoc | 13 +++----------\n 1 file changed, 3 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex a2777fb5b0..d35fd32ce8 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -65,16 +65,9 @@ commit would overwrite your uncommitted changes.\n `git checkout --detach [<branch>]`::\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-\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-When the _<commit>_ argument is a branch name, the `--detach` option can\n-be used to detach `HEAD` at the tip of the branch (`git checkout\n-<branch>` would check out that branch without detaching `HEAD`).\n+\tThe same as `git checkout <branch>`, except that instead of pointing\n+\t`HEAD` at the branch, it points `HEAD` at the commit ID.\n+\tSee the \"DETACHED HEAD\" section below for more.\n +\n Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.\n \n-- \ngitgitgadget\n\n"},{"id":"525445","messageId":"24793f9a451a1b906952256bc2f67c395a02f66b.1756918202.git.gitgitgadget@gmail.com","threadId":"64030","inReplyTo":"pull.1962.v3.git.1756918202.gitgitgadget@gmail.com","subject":"[PATCH v3 5/6] doc: git-checkout: split up restoring files section","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-09-03T16:50:01Z","receivedAt":"2025-09-03T16:50:11Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nWill make it easier to explain the two versions clearly in the following\ncommit. As a bonus, now the structure of the DESCRIPTION\nmatches the SYNOPSIS.\n\nAlso remove `-f` from `git checkout <tree-ish> <pathspec>` since it's\nnot relevant in that context.\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-checkout.adoc | 23 +++++++++++++----------\n 1 file changed, 13 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex d35fd32ce8..b361ff011a 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -12,8 +12,8 @@ git checkout [-q] [-f] [-m] [<branch>]\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] <tree-ish> [--] <pathspec>...\n-git checkout [-f] <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]\n+git checkout <tree-ish> [--] <pathspec>...\n+git checkout <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]\n git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...\n git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]\n git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]\n@@ -71,14 +71,17 @@ commit would overwrite your uncommitted changes.\n +\n Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.\n \n-`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...`::\n-`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]`::\n+`git checkout <tree-ish> [--] <pathspec>...`::\n+`git checkout <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]`::\n \n-\tOverwrite the contents of the files that match the pathspec.\n-\tWhen the _<tree-ish>_ (most often a commit) is not given,\n-\toverwrite working tree with the contents in the index.\n-\tWhen the _<tree-ish>_ is given, overwrite both the index and\n-\tthe working tree with the contents at the _<tree-ish>_.\n+\tOverwrite both the index and the working tree with the\n+\tcontents at the _<tree-ish>_ for the files that match the pathspec.\n+\n+`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...`::\n+`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]`::\n+\n+\tOverwrite working tree with the contents in the index for the files\n+\tthat match the pathspec.\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@@ -89,7 +92,7 @@ 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 `git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]`::\n-\tThis is similar to the previous mode, but lets you use the\n+\tThis is similar to the previous two modes, but lets you use the\n \tinteractive interface to show the \"diff\" output and choose which\n \thunks to use in the result.  See below for the description of\n \t`--patch` option.\n-- \ngitgitgadget\n\n"},{"id":"525446","messageId":"90fe48cfe37852b9e245aa0f7b45383f9b879199.1756918202.git.gitgitgadget@gmail.com","threadId":"64030","inReplyTo":"pull.1962.v3.git.1756918202.gitgitgadget@gmail.com","subject":"[PATCH v3 6/6] doc: git-checkout: clarify restoring files section","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-09-03T16:50:02Z","receivedAt":"2025-09-03T16:50:13Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\n- Reword to avoid jargon (\"tree-ish\", \"index\") where possible.\n  Use \"commit or tree\" and \"stage\" (as a verb) instead where appropriate\n- Add examples\n- Use a simpler sentence structure to describe options for handling\n  unmerged entries: \"use -f to.., use --ours to..., or use -m to..\"\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-checkout.adoc | 28 ++++++++++++++++------------\n 1 file changed, 16 insertions(+), 12 deletions(-)\n\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex b361ff011a..ae19565f4f 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -74,23 +74,27 @@ Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.\n `git checkout <tree-ish> [--] <pathspec>...`::\n `git checkout <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]`::\n \n-\tOverwrite both the index and the working tree with the\n-\tcontents at the _<tree-ish>_ for the files that match the pathspec.\n+\tReplace the specified files and/or directories with the version from\n+\tthe given commit or tree and stage the files' contents.\n++\n+For example, `git checkout main file.txt` will replace `file.txt`\n+with the version from `main`.\n \n `git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...`::\n `git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]`::\n \n-\tOverwrite working tree with the contents in the index for the files\n-\tthat match the pathspec.\n+\tDiscard any unstaged changes to the specified files and/or directories.\n+\tThis works by copying the file from the index to your working directory.\n+\tFor example, `git checkout file.txt` will replace `file.txt` with either\n+\tthe staged version of `file.txt` (if there is one) or the version from the\n+\tcurrent commit.\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-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 re-create the original conflicted merge result.\n-\n+This will fail if the file has a merge conflict and you haven't yet run\n+`git add file.txt` (or something equivalent) to mark it as resolved.\n+You can use `-f` to ignore the unmerged files instead of failing, use\n+`--ours` or `--theirs` to replace them with the version from a specific\n+side of the merge, or use `-m` to replace them with the original\n+conflicted merge result.\n `git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]`::\n \tThis is similar to the previous two modes, but lets you use the\n \tinteractive interface to show the \"diff\" output and choose which\n-- \ngitgitgadget\n"},{"id":"525461","messageId":"xmqqikhzdz0k.fsf@gitster.g","threadId":"64030","inReplyTo":"pull.1962.v3.git.1756918202.gitgitgadget@gmail.com","subject":"Re: [PATCH v3 0/6] doc: git-checkout: clarify DESCRIPTION section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-09-03T21:09:15Z","receivedAt":"2025-09-03T21:09:17Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n>  * Improve the storytelling in the commit messages\n>  * Take a different approach to the git checkout -b description (keep reset\n>    in -B, but simplify the description of -B a lot)\n>  * Make the description of git checkout [<branch>] more accurate.\n>  * Try a different approach to git checkout file.txt (\"Discard any unstaged\n>    changes...\")\n\nNot just you repeat having bulleted list in your proposed log\nmessages (which I already said something about, remember?), now you\nhave them in your cover letter, too?  You must be so fond of\nbulletted list X-<.\n\n>      @@ Documentation/git-checkout.adoc: $ git log -g -2 HEAD\n>       -to checkout these paths out of the index.\n>       +When you run `git checkout <something>`, Git tries to guess whether\n>       +`<something>` is intended to be a branch, a commit, or a set of file(s),\n>      -+and then switches branches, switches commits, or restores the files.\n>      ++and then either switches to that branch or commit or restores the\n>      ++specified files.\n\nMuch better.\n\n>      ++\tSwitch to _<branch>_. This sets the current branch to _<branch>_ and\n>      ++\tupdates the files in your working directory. Files which are\n>      ++\tidentical in _<branch>_ and your current commit are left unchanged\n>      ++\tso that you can keep your uncommitted changes to those files.\n\nHere \"left unchanged\" is technically correct, but somehow it gives\nme a (n incorrect) connotation that they are not modified since\nHEAD, which is not what you wanted to say at all.  I recall that we\nonce explained this not as \"left unchanged\", but as \"changes follow\nyou\", and I found the explanation easier to absorb.\n\nI cannot come up with a good way to remove duplicates in the\nfollowing desciption, but what we want the reader to understand are\ntwofold:\n\n * For paths that are not identical between HEAD and the _<branch>_\n   you are switching to, you MUST NOT have a local change.  After\n   you switch to _<branch>_, these paths in the working tree match\n   that of the _<branch_>.  This is to avoid losing your local\n   changes.\n\n * For paths that are identical between HEAD and the _<branch>_ you\n   are switching to, you may have local modifications, and they\n   follow you to the switched-to _<branch>_.\n\n>      ++`git checkout -b <new-branch> [<start-point>]`::\n>      ++\n>      ++\tCreate a new branch named _<new-branch>_, start it at _<start-point>_\n>      ++\t(defaults to the current commit), and check out the new branch.\n>      ++\tYou can use the `--track` or `--no-track` options to set the branch's\n>      ++\tupstream tracking information.\n>        +\n>      ++This fails without making any changes if there's an error checking out\n>      ++_<new-branch>_, for example if checking out the `<start-point>`\n>      ++commit would overwrite your uncommitted changes.\n\nOK.  Do people understand \"making a(ny) changes\" refers to creation\nof the new branch, I have to wonder, but if so, the above is much\nmuch nicer than the original text.\n\n    This fails without doing anything and without creating a new\n    branch, if checking out the <start-point> has to overwrite your\n    uncommitted changes.\n\nmight be slightly better?  I dunno.\n"},{"id":"525463","messageId":"07e52117-96da-4443-8974-08a22516ed75@app.fastmail.com","threadId":"64030","inReplyTo":"xmqqikhzdz0k.fsf@gitster.g","subject":"Re: [PATCH v3 0/6] doc: git-checkout: clarify DESCRIPTION section","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-09-03T21:28:27Z","receivedAt":"2025-09-03T21:28:48Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"> Not just you repeat having bulleted list in your proposed log\n> messages (which I already said something about, remember?), now you\n> have them in your cover letter, too?  You must be so fond of\n> bulletted list X-<.\n\nIt's true, I do really love bulleted lists. I see now that I misunderstood\nyour previous comment about this: I'll avoid using bulleted lists in\ncommit messages and emails in the future.\n\n>>      ++\tSwitch to _<branch>_. This sets the current branch to _<branch>_ and\n>>      ++\tupdates the files in your working directory. Files which are\n>>      ++\tidentical in _<branch>_ and your current commit are left unchanged\n>>      ++\tso that you can keep your uncommitted changes to those files.\n>\n> Here \"left unchanged\" is technically correct, but somehow it gives\n> me a (n incorrect) connotation that they are not modified since\n> HEAD, which is not what you wanted to say at all.  I recall that we\n> once explained this not as \"left unchanged\", but as \"changes follow\n> you\", and I found the explanation easier to absorb.\n\nI like the idea of \"changes follow you\". Will work on making this clearer.\n\n> OK.  Do people understand \"making a(ny) changes\" refers to creation\n> of the new branch, I have to wonder, but if so, the above is much\n> much nicer than the original text.\n>\n>     This fails without doing anything and without creating a new\n>     branch, if checking out the <start-point> has to overwrite your\n>     uncommitted changes.\n>\n> might be slightly better?  I dunno.\n\nMakes sense. I'll be more explicit.\n"},{"id":"525464","messageId":"xmqqecsndy23.fsf@gitster.g","threadId":"64030","inReplyTo":"90fe48cfe37852b9e245aa0f7b45383f9b879199.1756918202.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v3 6/6] doc: git-checkout: clarify restoring files section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-09-03T21:29:56Z","receivedAt":"2025-09-03T21:29:58Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> -\tOverwrite both the index and the working tree with the\n> -\tcontents at the _<tree-ish>_ for the files that match the pathspec.\n> +\tReplace the specified files and/or directories with the version from\n> +\tthe given commit or tree and stage the files' contents.\n\nHmph.  I agree that there is no reason to stress that you are not\nrequired to use a commit here (hence not much point in saying\ntree-ish).  I do not think avoiding \"index\" (which is not even a\njargon; it is the official name of the thing) is necessarily a good\nidea, given that ...\n\n> +For example, `git checkout main file.txt` will replace `file.txt`\n> +with the version from `main`.\n>  \n>  `git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...`::\n>  `git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]`::\n>  \n> -\tOverwrite working tree with the contents in the index for the files\n> -\tthat match the pathspec.\n> +\tDiscard any unstaged changes to the specified files and/or directories.\n> +\tThis works by copying the file from the index to your working directory.\n> +\tFor example, `git checkout file.txt` will replace `file.txt` with either\n> +\tthe staged version of `file.txt` (if there is one) or the version from the\n> +\tcurrent commit.\n\n... we'd have to say \"from the index to your working tree files\"\nhere.  In contrast, the earlier one is \"from the commit to the index\nand to your working tree files\", and explaining it as such may make\nthe similarity & differences stand out more clearly.\n\nAlso, I personally find it easier to follow if you did\n\"directories. This works by copying\" -> \"directories, by copying\".\nIt comes from the same \"think again when you find that you are\nsaying 'it means that' and such\" principle.\n\n> +This will fail if the file has a merge conflict and you haven't yet run\n> +`git add file.txt` (or something equivalent) to mark it as resolved.\n> +You can use `-f` to ignore the unmerged files instead of failing, use\n> +`--ours` or `--theirs` to replace them with the version from a specific\n> +side of the merge, or use `-m` to replace them with the original\n> +conflicted merge result.\n\nOK.\n"},{"id":"525475","messageId":"CALnO6CDEbXx_e2Wr_r2jR-ZbcxwsELF_tu2pWE3mgfm+5FYY=w@mail.gmail.com","threadId":"64030","inReplyTo":"xmqqiki5n8r0.fsf@gitster.g","subject":"Re: [PATCH 1/5] doc: git-checkout: clarify intro","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-09-03T23:48:45Z","receivedAt":"2025-09-03T23:48:57Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Fri, Aug 29, 2025 at 5:00 PM Junio C Hamano <gitster@pobox.com> wrote:\n>\n> \"D. Ben Knoble\" <ben.knoble@gmail.com> writes:\n>\n> >> +1. **Switch branches**, with `git checkout <branch>`\n> >> +2. **Restore a different version of a file**, for example with `git\n> >> +   checkout <commit> <filename>` or `git checkout <filename>`\n> >> +\n> >> +See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.\n> >> +Here's a description of all of the modes:\n> >\n> > This looks good—I initially scratched my head thinking there were 3\n> > modes, but unifying \"update files to match index\" and \"update files to\n> > match specified tree\" is easier to digest in this presentation.\n>\n> Yup.  And on the other side, unifying \"prepare to extend the history\n> of a branch\" and \"prepare to create a new history starting at a\n> commit\" (aka detached HEAD) into one is equally good.\n>\n> But I am wondering what is the most common perception of the second\n> mode.  I've always thought that the action was to \"grab things out\n> of the index or out of a tree-ish and overwrite the working tree\n> files\", and it takes me an extra effort to read, think, understand\n> and finally realize that \"update working tree files to match either\n> the index or a tree-ish\" is equivalent to it.\n\nI'd say your first version matches my concept of that mode, but it's\nheavy on the operation (do this, do that) vs the declaration (desired\nend state). Of course the second version still has the verb \"update,\"\nbut we emphasize less \"how\" to update and more the results of said\nupdate?\n\n> Anyway, thanks for a review.\n\n:)\n\n-- \nD. Ben Knoble\n"},{"id":"526068","messageId":"pull.1962.v4.git.1757531669.gitgitgadget@gmail.com","threadId":"64030","inReplyTo":"pull.1962.v3.git.1756918202.gitgitgadget@gmail.com","subject":"[PATCH v4 0/7] doc: git-checkout: clarify DESCRIPTION section","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-09-10T19:14:22Z","receivedAt":"2025-09-10T19:14:32Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"I got feedback from 22 existing Git users on the existing git checkout man\npage, using this tool: https://text-feedback.wizardzines.com/git-checkout.\nFrom a short survey they filled out, about 90% of the users who gave the\nfeedback have 5+ years of experience using Git.\n\nThis series goes through the DESCRIPTION section from beginning to end,\naddressing points that users found confusing in each variant of git\ncheckout. The goal is to clarify while communicating the same information.\n\nChanges in v2:\n\n * Remove the numbered list from the beginning, from Junio's review\n * Describe what it means to \"switch branches\" in a way that's hopefully\n   more accessible to newcomers, from Junio's review\n * Improve the ARGUMENT DISAMBIGUATION section, from Junio and Ben's reviews\n   (\"conflict\" => \"ambiguity\", explain correctly what the default is)\n * The explanation of git checkout [<tree-ish>] <pathspec> had a lot of\n   issues, from Junio's review. Resolve this by splitting up the git\n   checkout [] section into two sections. Use \"Replace\" instead of\n   \"Restore\".\n\nChanges in v3:\n\n * Fix incorrect description of when git checkout <branch>, from Junio's\n   review\n * Take a different approach to the git checkout -b description (keep reset\n   in -B, but simplify the description of -B a lot to remove the\n   \"transactional equivalent..\" paragraph), from Junio's review\n * Say \"switch to the commit\" instead of \"switches commits\", from Junio's\n   review\n * Try a different approach to git checkout file.txt (\"Discard any unstaged\n   changes...\")\n\nChanges in v4:\n\n * Rewrite all the commit messages to try to take a more Problem / Solution\n   approach, from Junio's review and thanks to help from @nasamuffin in\n   Discord. Also change the cover letter format to match the style in\n   https://lore.kernel.org/git/CAOLa=ZStgwBN0fMK3YxoqeR+1i772f621supva3Kvr7YPq4g8g@mail.gmail.com/T/#m8c99a3144cbdfb445e04f8f83a79364bfe8d797d\n   , which hopefully matches the norms of this mailing list better.\n * Try a different approach to the \"left unchanged...\", from Junio's review\n * Bring back \"index\" (with a few hints about what the word might mean),\n   from Junio's review.\n * Bring back the numbered list at the beginning from v1, since I think I\n   misunderstood a comment about lists, and that the original was clearer\n * Fix an issue I noticed in -B (\"instead of failing\", not \"instead of\n   creating it\")\n * Add a comma after branch or commit, to try to make it clear what \"either\"\n   refers to in that sentence\n * Replace \"will fail without making any changes\" throughout with just \"will\n   fail\". I think the default assumption is that Git will fail operations in\n   a clean way, and that cases where it does not fail cleanly are the\n   exceptions that the documentation should flag.\n\nJulia Evans (7):\n  doc: git-checkout: clarify intro sentence\n  doc: git-checkout: clarify ARGUMENT DISAMBIGUATION\n  doc: git-checkout: clarify `git checkout <branch>`\n  doc: git-checkout: clarify `-b` and `-B`\n  doc: git-checkout: deduplicate --detach explanation\n  doc: git-checkout: split up restoring files section\n  doc: git-checkout: clarify restoring files section\n\n Documentation/git-checkout.adoc | 151 ++++++++++++++++----------------\n 1 file changed, 76 insertions(+), 75 deletions(-)\n\n\nbase-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1962%2Fjvns%2Fclarify-checkout-v4\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1962/jvns/clarify-checkout-v4\nPull-Request: https://github.com/gitgitgadget/git/pull/1962\n\nRange-diff vs v3:\n\n -:  ---------- > 1:  4b52ffd497 doc: git-checkout: clarify intro sentence\n 1:  1975384dd0 ! 2:  08f0a5efab doc: git-checkout: clarify intro\n     @@ Metadata\n      Author: Julia Evans <julia@jvns.ca>\n      \n       ## Commit message ##\n     -    doc: git-checkout: clarify intro\n     +    doc: git-checkout: clarify ARGUMENT DISAMBIGUATION\n      \n     -    - Reduce use of jargon (\"index\", \"pathspec\", \"tree\") by using an\n     -      example, and by mirroring the \"switch\" and \"restore\" language from the\n     -      first line of the man page.\n     -    - Reference and clarify the ARGUMENT DISAMBIGUATION section, as well\n     -      as fixing a small error (in \"`git checkout abc`, `abc` is a commit,\n     -      not a `_<tree-ish>_`)\n     +    There's no need to use the terms \"pathspec\" or \"tree-ish\" in the\n     +    ARGUMENT DISAMBIGUATION section, which are terms that (from user\n     +    feedback on this page) many users do not understand.\n     +\n     +    \"tree-ish\" is actually not accurate here: `git checkout` in this case\n     +    takes a commit-ish, not a tree-ish. So we can say \"branch or commit\"\n     +    instead of \"tree-ish\" which is both more accurate and uses more familiar\n     +    terms.\n     +\n     +    And now that the intro to the man pages mentions that `git checkout` has\n     +    \"two main modes\", it makes sense to refer to this disambiguation section\n     +    to understand how Git decides which one to use when there's an overlap\n     +    in syntax.\n      \n          Signed-off-by: Julia Evans <julia@jvns.ca>\n      \n       ## Documentation/git-checkout.adoc ##\n     -@@ Documentation/git-checkout.adoc: git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]\n     +@@ Documentation/git-checkout.adoc: DESCRIPTION\n     + 2. **Restore a different version of a file**, for example with\n     +    `git checkout <commit> <filename>` or `git checkout <filename>`\n       \n     - DESCRIPTION\n     - -----------\n     --Updates files in the working tree to match the version in the index\n     --or the specified tree.  If no pathspec was given, `git checkout` will\n     --also update `HEAD` to set the specified branch as the current\n     --branch.\n     -+`git checkout` has two main modes: it can\n     -+**switch branches**, for example with `git checkout <branch>`, and\n     -+**restore files from a different version**, for example with\n     -+`git checkout <commit> <filename>` or `git checkout <filename>`\n     -+\n      +See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.\n     - \n     ++\n       `git checkout [<branch>]`::\n       \tTo prepare for working on _<branch>_, switch to it by updating\n     + \tthe index and the files in the working tree, and by pointing\n      @@ Documentation/git-checkout.adoc: $ git log -g -2 HEAD\n       ARGUMENT DISAMBIGUATION\n       -----------------------\n     @@ Documentation/git-checkout.adoc: $ git log -g -2 HEAD\n      -to checkout these paths out of the index.\n      +When you run `git checkout <something>`, Git tries to guess whether\n      +`<something>` is intended to be a branch, a commit, or a set of file(s),\n     -+and then either switches to that branch or commit or restores the\n     ++and then either switches to that branch or commit, or restores the\n      +specified files.\n      +\n      +If there's any ambiguity, Git will treat `<something>` as a branch or\n 2:  940cd17e7e ! 3:  551e56dea6 doc: git-checkout: clarify `git checkout <branch>`\n     @@ Metadata\n       ## Commit message ##\n          doc: git-checkout: clarify `git checkout <branch>`\n      \n     -    - Reduce use of jargon (\"index\", \"HEAD\")\n     -    - Clarify that only identical files will be left unchanged, and that\n     -      `git checkout` will fail rather than overwrite an unchanged file\n     -    - Explain what `git checkout` with no arguments does in a more direct\n     -      way\n     +    From user feedback: several users commented that \"Local modifications\n     +    to the files in the working tree are kept, so that they can be committed\n     +    to the <branch>.\" didn't seem accurate to them, since\n     +    `git checkout <branch>` will often fail.\n     +\n     +    One user also thought that \"... and by pointing HEAD at the branch\"\n     +    was something that _they_ had to do somehow (\"How do I point HEAD at\n     +    a branch?\") rather than a description of what the `git checkout`\n     +    operation is doing for them.\n     +\n     +    Explain when `git checkout <branch>` will fail and clarify that\n     +    \"pointing HEAD at the branch\" is part of what the command does.\n     +\n     +    6 users commented that the \"You could omit <branch>...\" section is\n     +    extremely confusing. Explain this in a much more direct way.\n      \n          Signed-off-by: Julia Evans <julia@jvns.ca>\n      \n     @@ Documentation/git-checkout.adoc: DESCRIPTION\n      -\tworking tree are kept, so that they can be committed to the\n      -\t_<branch>_.\n      +\tSwitch to _<branch>_. This sets the current branch to _<branch>_ and\n     -+\tupdates the files in your working directory. Files which are\n     -+\tidentical in _<branch>_ and your current commit are left unchanged\n     -+\tso that you can keep your uncommitted changes to those files.\n     -+\tThis will not overwrite uncommitted changes to a file: instead it\n     -+\twill fail without making any changes.\n     ++\tupdates the files in your working directory. The checkout will fail\n     ++\tif there are uncommitted changes to any files where _<branch>_ and\n     ++\tyour current commit have different content. Uncommitted changes will\n     ++\totherwise be kept.\n       +\n       If _<branch>_ is not found but there does exist a tracking branch in\n       exactly one remote (call it _<remote>_) with a matching name and\n 3:  043fec7e66 ! 4:  e636475cba doc: git-checkout: clarify `-b` and `-B`\n     @@ Metadata\n       ## Commit message ##\n          doc: git-checkout: clarify `-b` and `-B`\n      \n     -    - Remove some unnecessary detail about `--track` (users can refer\n     -      to the OPTIONS section instead)\n     -    - Explain what the start point defaults to\n     -    - Describe `-B` much more tersely as \"the same as `-b`, except ..\",\n     -      since potential users of `-B` are almost certainly already very\n     -      familiar with `-b`. Move all of the other contents of `-B` to `-b`,\n     -      updating the example so that it's appropriate for `-b`\n     +    From user feedback: several users reported having trouble understanding\n     +    the difference between `-b` and `-B` (\"I think it's because my brain\n     +    expects it to contrast with `-b`, but instead it starts off explaining\n     +    how they're the same\").\n     +\n     +    Also, in `-B`, 2 users can't tell what the branch is reset *to*.\n     +\n     +    Simplify the sentence structure in the explanations of `-b` and `-B` and\n     +    add a little extra information (what `<start-point>` is, what the branch\n     +    is reset to).\n     +\n     +    Splitting up `-b` and `-B` into separate items helps simplify the\n     +    sentence structure since there's less \"In this case...\".\n     +\n     +    Replace the long \"the branch is not reset/created unless \"git checkout\"\n     +    is successful...\" with just \"will fail\", since we should generally\n     +    assume that Git will fail operations in a clean way and not leave\n     +    operations half-finished, and that cases where it does not fail cleanly\n     +    are the exceptions that the documentation should flag.\n      \n          Signed-off-by: Julia Evans <julia@jvns.ca>\n      \n     @@ Documentation/git-checkout.adoc: $ git checkout -b <branch> --track <remote>/<br\n      -successful (e.g., when the branch is in use in another worktree, not\n      -just the current branch stays the same, but the branch is not reset to\n      -the start-point, either).\n     -+This fails without making any changes if there's an error checking out\n     -+_<new-branch>_, for example if checking out the `<start-point>`\n     -+commit would overwrite your uncommitted changes.\n     ++This will fail if there's an error checking out _<new-branch>_, for\n     ++example if checking out the `<start-point>` commit would overwrite your\n     ++uncommitted changes.\n      +\n      +`git checkout -B <branch> [<start-point>]`::\n      +\n      +\tThe same as `-b`, except that if the branch already exists it\n     -+\tresets `_<branch>_` to the start point instead of creating it.\n     ++\tresets `_<branch>_` to the start point instead of failing.\n       \n       `git checkout --detach [<branch>]`::\n       `git checkout [--detach] <commit>`::\n     @@ Documentation/git-checkout.adoc: of it\").\n      -\t`git branch` with `-f` followed by `git checkout` of that branch;\n      -\tsee linkgit:git-branch[1] for details.\n      +\tThe same as `-b`, except that if the branch already exists it\n     -+\tresets `_<branch>_` to the start point instead of creating it.\n     ++\tresets `_<branch>_` to the start point instead of failing.\n       \n       `-t`::\n       `--track[=(direct|inherit)]`::\n 4:  6ce31b6278 ! 5:  e7d9641125 doc: git-checkout: deduplicate --detach explanation\n     @@ Metadata\n       ## Commit message ##\n          doc: git-checkout: deduplicate --detach explanation\n      \n     -    Say that `git checkout --detach` is almost the same as `git checkout`\n     -    instead of duplicating the content of the `git checkout` section, since\n     -    many users will already be familiar with what `git checkout` does.\n     +    From user feedback: several users say they don't understand the use case\n     +    for `--detach`. It's probably not realistic to explain the use case for\n     +    detached HEAD state here, but we can improve the situation.\n     +\n     +    Explain how `git checkout --detach` is different from\n     +    `git checkout <branch>` instead of copying over the description from\n     +    `git checkout <branch>`, since `git checkout <branch>` will be a\n     +    familiar command to many readers.\n      \n          Signed-off-by: Julia Evans <julia@jvns.ca>\n      \n       ## Documentation/git-checkout.adoc ##\n     -@@ Documentation/git-checkout.adoc: commit would overwrite your uncommitted changes.\n     +@@ Documentation/git-checkout.adoc: uncommitted changes.\n       `git checkout --detach [<branch>]`::\n       `git checkout [--detach] <commit>`::\n       \n 5:  24793f9a45 ! 6:  7b1e2f265b doc: git-checkout: split up restoring files section\n     @@ Metadata\n       ## Commit message ##\n          doc: git-checkout: split up restoring files section\n      \n     -    Will make it easier to explain the two versions clearly in the following\n     -    commit. As a bonus, now the structure of the DESCRIPTION\n     -    matches the SYNOPSIS.\n     +    From user feedback: one user mentioned that \"When the <tree-ish> (most\n     +    often a commit) is not given\" is confusing since it starts with a\n     +    negative.\n      \n     -    Also remove `-f` from `git checkout <tree-ish> <pathspec>` since it's\n     -    not relevant in that context.\n     +    Restructuring so that `git checkout main file.txt` and\n     +    `git checkout file.txt` are separate items will help us simplify the\n     +    sentence structure a lot.\n     +\n     +    As a bonus, it appears that `-f` actually only applies to one of those\n     +    forms, so we can include fewer options, and now the structure of the\n     +    DESCRIPTION matches the SYNOPSIS.\n      \n          Signed-off-by: Julia Evans <julia@jvns.ca>\n      \n     @@ Documentation/git-checkout.adoc: git checkout [-q] [-f] [-m] [<branch>]\n       git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...\n       git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]\n       git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]\n     -@@ Documentation/git-checkout.adoc: commit would overwrite your uncommitted changes.\n     +@@ Documentation/git-checkout.adoc: uncommitted changes.\n       +\n       Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.\n       \n 6:  90fe48cfe3 ! 7:  db603b1e5f doc: git-checkout: clarify restoring files section\n     @@ Metadata\n       ## Commit message ##\n          doc: git-checkout: clarify restoring files section\n      \n     -    - Reword to avoid jargon (\"tree-ish\", \"index\") where possible.\n     -      Use \"commit or tree\" and \"stage\" (as a verb) instead where appropriate\n     -    - Add examples\n     -    - Use a simpler sentence structure to describe options for handling\n     -      unmerged entries: \"use -f to.., use --ours to..., or use -m to..\"\n     +    From user feedback on this section: 3 users don't know what \"tree-ish\"\n     +    means and 3 users don't know what \"pathspec\" means. One user also says\n     +    that the section is very confusing and that they don't understand what\n     +    the \"index\" is.\n     +\n     +    From conversations on Mastodon, several users said that their impression\n     +    is that \"the index\" means the same thing as \"HEAD\". It would be good to\n     +    give those users (and other users who do not know what \"index\" means) a\n     +    hint as to its meaning.\n     +\n     +    Make this section more accessible to users who don't know what the terms\n     +    \"pathspec\", \"tree-ish\", and \"index\" mean by using more familiar language,\n     +    adding examples, and using simpler sentence structures.\n      \n          Signed-off-by: Julia Evans <julia@jvns.ca>\n      \n     @@ Documentation/git-checkout.adoc: Omitting _<branch>_ detaches `HEAD` at the tip\n      -\tOverwrite both the index and the working tree with the\n      -\tcontents at the _<tree-ish>_ for the files that match the pathspec.\n      +\tReplace the specified files and/or directories with the version from\n     -+\tthe given commit or tree and stage the files' contents.\n     ++\tthe given commit or tree and add them to the index\n     ++\t(also known as \"staging area\").\n      ++\n      +For example, `git checkout main file.txt` will replace `file.txt`\n      +with the version from `main`.\n     @@ Documentation/git-checkout.adoc: Omitting _<branch>_ detaches `HEAD` at the tip\n       \n      -\tOverwrite working tree with the contents in the index for the files\n      -\tthat match the pathspec.\n     -+\tDiscard any unstaged changes to the specified files and/or directories.\n     -+\tThis works by copying the file from the index to your working directory.\n     -+\tFor example, `git checkout file.txt` will replace `file.txt` with either\n     -+\tthe staged version of `file.txt` (if there is one) or the version from the\n     -+\tcurrent commit.\n     ++\tReplace the specified files and/or directories with the version from\n     ++\tthe index.\n     +++\n     ++For example, if you check out a commit, edit `file.txt`, and then\n     ++decide those changes were a mistake, `git checkout file.txt` will\n     ++discard any unstaged changes to `file.txt`.\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     @@ Documentation/git-checkout.adoc: Omitting _<branch>_ detaches `HEAD` at the tip\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 re-create the original conflicted merge result.\n     --\n      +This will fail if the file has a merge conflict and you haven't yet run\n      +`git add file.txt` (or something equivalent) to mark it as resolved.\n      +You can use `-f` to ignore the unmerged files instead of failing, use\n      +`--ours` or `--theirs` to replace them with the version from a specific\n      +side of the merge, or use `-m` to replace them with the original\n      +conflicted merge result.\n     + \n       `git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]`::\n       \tThis is similar to the previous two modes, but lets you use the\n     - \tinteractive interface to show the \"diff\" output and choose which\n\n-- \ngitgitgadget\n"},{"id":"526069","messageId":"4b52ffd4970d8a33065cc8dcd915623acf716b5a.1757531669.git.gitgitgadget@gmail.com","threadId":"64030","inReplyTo":"pull.1962.v4.git.1757531669.gitgitgadget@gmail.com","subject":"[PATCH v4 1/7] doc: git-checkout: clarify intro sentence","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-09-10T19:14:23Z","receivedAt":"2025-09-10T19:14:33Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nFrom user feedback: in the first paragraph, 5 users reported not\nunderstanding the terms \"pathspec\" and 1 user reported not understanding\nthe term \"HEAD\". Of the users who said they didn't know what \"pathspec\"\nmeans, 3 said they couldn't understand what the paragraph was trying to\ncommunicate as a result.\n\nOne user also commented that \"If no pathspec was given...\" makes\n`git checkout <branch>` sounds like a special edge case, instead of\nbeing one of the most common ways to use this core Git command.\n\nIt looks like the goal of this paragraph is to communicate that `git\ncheckout` has two different modes: one where you switch branches and one\nwhere you just update your working directory files/index. So say that\ndirectly, and use more familiar language (including examples) to say it.\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-checkout.adoc | 10 ++++++----\n 1 file changed, 6 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex 40e02cfd65..9733c73450 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -20,10 +20,12 @@ git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]\n \n DESCRIPTION\n -----------\n-Updates files in the working tree to match the version in the index\n-or the specified tree.  If no pathspec was given, `git checkout` will\n-also update `HEAD` to set the specified branch as the current\n-branch.\n+\n+`git checkout` has two main modes:\n+\n+1. **Switch branches**, with `git checkout <branch>`\n+2. **Restore a different version of a file**, for example with\n+   `git checkout <commit> <filename>` or `git checkout <filename>`\n \n `git checkout [<branch>]`::\n \tTo prepare for working on _<branch>_, switch to it by updating\n-- \ngitgitgadget\n\n"},{"id":"526070","messageId":"08f0a5efab9d5dd57e1a49d00664e9453b6413f5.1757531669.git.gitgitgadget@gmail.com","threadId":"64030","inReplyTo":"pull.1962.v4.git.1757531669.gitgitgadget@gmail.com","subject":"[PATCH v4 2/7] doc: git-checkout: clarify ARGUMENT DISAMBIGUATION","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-09-10T19:14:24Z","receivedAt":"2025-09-10T19:14:34Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nThere's no need to use the terms \"pathspec\" or \"tree-ish\" in the\nARGUMENT DISAMBIGUATION section, which are terms that (from user\nfeedback on this page) many users do not understand.\n\n\"tree-ish\" is actually not accurate here: `git checkout` in this case\ntakes a commit-ish, not a tree-ish. So we can say \"branch or commit\"\ninstead of \"tree-ish\" which is both more accurate and uses more familiar\nterms.\n\nAnd now that the intro to the man pages mentions that `git checkout` has\n\"two main modes\", it makes sense to refer to this disambiguation section\nto understand how Git decides which one to use when there's an overlap\nin syntax.\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-checkout.adoc | 22 ++++++++++++++--------\n 1 file changed, 14 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex 9733c73450..d6f4044a09 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -27,6 +27,8 @@ DESCRIPTION\n 2. **Restore a different version of a file**, for example with\n    `git checkout <commit> <filename>` or `git checkout <filename>`\n \n+See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.\n+\n `git checkout [<branch>]`::\n \tTo prepare for working on _<branch>_, switch to it by updating\n \tthe index and the files in the working tree, and by pointing\n@@ -513,14 +515,18 @@ $ git log -g -2 HEAD\n ARGUMENT DISAMBIGUATION\n -----------------------\n \n-When there is only one argument given and it is not `--` (e.g. `git\n-checkout abc`), and when the argument is both a valid _<tree-ish>_\n-(e.g. a branch `abc` exists) and a valid _<pathspec>_ (e.g. a file\n-or a directory whose name is \"abc\" exists), Git would usually ask\n-you to disambiguate.  Because checking out a branch is so common an\n-operation, however, `git checkout abc` takes \"abc\" as a _<tree-ish>_\n-in such a situation.  Use `git checkout -- <pathspec>` if you want\n-to checkout these paths out of the index.\n+When you run `git checkout <something>`, Git tries to guess whether\n+`<something>` is intended to be a branch, a commit, or a set of file(s),\n+and then either switches to that branch or commit, or restores the\n+specified files.\n+\n+If there's any ambiguity, Git will treat `<something>` as a branch or\n+commit, but you can use the double dash `--` to force Git to treat the\n+parameter as a list of files and/or directories, like this:\n+\n+----------\n+git checkout -- file.txt\n+----------\n \n EXAMPLES\n --------\n-- \ngitgitgadget\n\n"},{"id":"526071","messageId":"551e56dea6c5a6381f5f2e9fd81882f8104ef233.1757531669.git.gitgitgadget@gmail.com","threadId":"64030","inReplyTo":"pull.1962.v4.git.1757531669.gitgitgadget@gmail.com","subject":"[PATCH v4 3/7] doc: git-checkout: clarify `git checkout <branch>`","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-09-10T19:14:25Z","receivedAt":"2025-09-10T19:14:36Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nFrom user feedback: several users commented that \"Local modifications\nto the files in the working tree are kept, so that they can be committed\nto the <branch>.\" didn't seem accurate to them, since\n`git checkout <branch>` will often fail.\n\nOne user also thought that \"... and by pointing HEAD at the branch\"\nwas something that _they_ had to do somehow (\"How do I point HEAD at\na branch?\") rather than a description of what the `git checkout`\noperation is doing for them.\n\nExplain when `git checkout <branch>` will fail and clarify that\n\"pointing HEAD at the branch\" is part of what the command does.\n\n6 users commented that the \"You could omit <branch>...\" section is\nextremely confusing. Explain this in a much more direct way.\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-checkout.adoc | 16 +++++++---------\n 1 file changed, 7 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex d6f4044a09..0db32b098e 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -30,11 +30,11 @@ DESCRIPTION\n See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.\n \n `git checkout [<branch>]`::\n-\tTo prepare for working on _<branch>_, switch to it by updating\n-\tthe index and the files in the working tree, and by pointing\n-\t`HEAD` 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_<branch>_.\n+\tSwitch to _<branch>_. This sets the current branch to _<branch>_ and\n+\tupdates the files in your working directory. The checkout will fail\n+\tif there are uncommitted changes to any files where _<branch>_ and\n+\tyour current commit have different content. Uncommitted changes will\n+\totherwise be kept.\n +\n If _<branch>_ is not found but there does exist a tracking branch in\n exactly one remote (call it _<remote>_) with a matching name and\n@@ -44,10 +44,8 @@ exactly one remote (call it _<remote>_) with a matching name and\n $ git checkout -b <branch> --track <remote>/<branch>\n ------------\n +\n-You could omit _<branch>_, in which case the command degenerates to\n-\"check out the current branch\", which is a glorified no-op with\n-rather expensive side-effects to show only the tracking information,\n-if it exists, for the current branch.\n+Running `git checkout` without specifying a branch has no effect except\n+to print out the tracking information for the current branch.\n \n `git checkout (-b|-B) <new-branch> [<start-point>]`::\n \n-- \ngitgitgadget\n\n"},{"id":"526072","messageId":"e636475cba2246ea98e461579a25b41b0ef4e99d.1757531669.git.gitgitgadget@gmail.com","threadId":"64030","inReplyTo":"pull.1962.v4.git.1757531669.gitgitgadget@gmail.com","subject":"[PATCH v4 4/7] doc: git-checkout: clarify `-b` and `-B`","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-09-10T19:14:26Z","receivedAt":"2025-09-10T19:14:37Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nFrom user feedback: several users reported having trouble understanding\nthe difference between `-b` and `-B` (\"I think it's because my brain\nexpects it to contrast with `-b`, but instead it starts off explaining\nhow they're the same\").\n\nAlso, in `-B`, 2 users can't tell what the branch is reset *to*.\n\nSimplify the sentence structure in the explanations of `-b` and `-B` and\nadd a little extra information (what `<start-point>` is, what the branch\nis reset to).\n\nSplitting up `-b` and `-B` into separate items helps simplify the\nsentence structure since there's less \"In this case...\".\n\nReplace the long \"the branch is not reset/created unless \"git checkout\"\nis successful...\" with just \"will fail\", since we should generally\nassume that Git will fail operations in a clean way and not leave\noperations half-finished, and that cases where it does not fail cleanly\nare the exceptions that the documentation should flag.\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-checkout.adoc | 44 ++++++++++++++-------------------\n 1 file changed, 18 insertions(+), 26 deletions(-)\n\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex 0db32b098e..7ae2ae9483 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -47,27 +47,21 @@ $ git checkout -b <branch> --track <remote>/<branch>\n Running `git checkout` without specifying a branch has no effect except\n to print out the tracking information for the current branch.\n \n-`git checkout (-b|-B) <new-branch> [<start-point>]`::\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, _<new-branch>_ is created if it doesn't exist; otherwise, it\n-is reset. This is the transactional equivalent of\n-+\n-------------\n-$ git branch -f <branch> [<start-point>]\n-$ git checkout <branch>\n-------------\n+`git checkout -b <new-branch> [<start-point>]`::\n+\n+\tCreate a new branch named _<new-branch>_, start it at _<start-point>_\n+\t(defaults to the current commit), and check out the new branch.\n+\tYou can use the `--track` or `--no-track` options to set the branch's\n+\tupstream tracking information.\n +\n-that is to say, the branch is not reset/created unless \"git checkout\" is\n-successful (e.g., when the branch is in use in another worktree, not\n-just the current branch stays the same, but the branch is not reset to\n-the start-point, either).\n+This will fail if there's an error checking out _<new-branch>_, for\n+example if checking out the `<start-point>` commit would overwrite your\n+uncommitted changes.\n+\n+`git checkout -B <branch> [<start-point>]`::\n+\n+\tThe same as `-b`, except that if the branch already exists it\n+\tresets `_<branch>_` to the start point instead of failing.\n \n `git checkout --detach [<branch>]`::\n `git checkout [--detach] <commit>`::\n@@ -157,16 +151,14 @@ of it\").\n \tsee linkgit:git-branch[1] for details.\n \n `-B <new-branch>`::\n-\tCreates the branch _<new-branch>_, start it at _<start-point>_;\n-\tif it already exists, then reset it to _<start-point>_. And then\n-\tcheck the resulting branch out.  This is equivalent to running\n-\t`git branch` with `-f` followed by `git checkout` of that branch;\n-\tsee linkgit:git-branch[1] for details.\n+\tThe same as `-b`, except that if the branch already exists it\n+\tresets `_<branch>_` to the start point instead of failing.\n \n `-t`::\n `--track[=(direct|inherit)]`::\n \tWhen creating a new branch, set up \"upstream\" configuration. See\n-\t`--track` in linkgit:git-branch[1] for details.\n+\t`--track` in linkgit:git-branch[1] for details. As a convenience,\n+\t--track without -b implies branch creation.\n +\n If no `-b` option is given, the name of the new branch will be\n derived from the remote-tracking branch, by looking at the local part of\n-- \ngitgitgadget\n\n"},{"id":"526073","messageId":"e7d9641125c78924aa7eb8d0534d361d760ea534.1757531669.git.gitgitgadget@gmail.com","threadId":"64030","inReplyTo":"pull.1962.v4.git.1757531669.gitgitgadget@gmail.com","subject":"[PATCH v4 5/7] doc: git-checkout: deduplicate --detach explanation","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-09-10T19:14:27Z","receivedAt":"2025-09-10T19:14:39Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nFrom user feedback: several users say they don't understand the use case\nfor `--detach`. It's probably not realistic to explain the use case for\ndetached HEAD state here, but we can improve the situation.\n\nExplain how `git checkout --detach` is different from\n`git checkout <branch>` instead of copying over the description from\n`git checkout <branch>`, since `git checkout <branch>` will be a\nfamiliar command to many readers.\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-checkout.adoc | 13 +++----------\n 1 file changed, 3 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex 7ae2ae9483..dd3cbb210d 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -66,16 +66,9 @@ uncommitted changes.\n `git checkout --detach [<branch>]`::\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-\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-When the _<commit>_ argument is a branch name, the `--detach` option can\n-be used to detach `HEAD` at the tip of the branch (`git checkout\n-<branch>` would check out that branch without detaching `HEAD`).\n+\tThe same as `git checkout <branch>`, except that instead of pointing\n+\t`HEAD` at the branch, it points `HEAD` at the commit ID.\n+\tSee the \"DETACHED HEAD\" section below for more.\n +\n Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.\n \n-- \ngitgitgadget\n\n"},{"id":"526074","messageId":"7b1e2f265baaa70483c8319793f167f7c91f3930.1757531669.git.gitgitgadget@gmail.com","threadId":"64030","inReplyTo":"pull.1962.v4.git.1757531669.gitgitgadget@gmail.com","subject":"[PATCH v4 6/7] doc: git-checkout: split up restoring files section","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-09-10T19:14:28Z","receivedAt":"2025-09-10T19:14:40Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nFrom user feedback: one user mentioned that \"When the <tree-ish> (most\noften a commit) is not given\" is confusing since it starts with a\nnegative.\n\nRestructuring so that `git checkout main file.txt` and\n`git checkout file.txt` are separate items will help us simplify the\nsentence structure a lot.\n\nAs a bonus, it appears that `-f` actually only applies to one of those\nforms, so we can include fewer options, and now the structure of the\nDESCRIPTION matches the SYNOPSIS.\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-checkout.adoc | 23 +++++++++++++----------\n 1 file changed, 13 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex dd3cbb210d..1e19e13a0e 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -12,8 +12,8 @@ git checkout [-q] [-f] [-m] [<branch>]\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] <tree-ish> [--] <pathspec>...\n-git checkout [-f] <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]\n+git checkout <tree-ish> [--] <pathspec>...\n+git checkout <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]\n git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...\n git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]\n git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]\n@@ -72,14 +72,17 @@ uncommitted changes.\n +\n Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.\n \n-`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...`::\n-`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]`::\n+`git checkout <tree-ish> [--] <pathspec>...`::\n+`git checkout <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]`::\n \n-\tOverwrite the contents of the files that match the pathspec.\n-\tWhen the _<tree-ish>_ (most often a commit) is not given,\n-\toverwrite working tree with the contents in the index.\n-\tWhen the _<tree-ish>_ is given, overwrite both the index and\n-\tthe working tree with the contents at the _<tree-ish>_.\n+\tOverwrite both the index and the working tree with the\n+\tcontents at the _<tree-ish>_ for the files that match the pathspec.\n+\n+`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...`::\n+`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]`::\n+\n+\tOverwrite working tree with the contents in the index for the files\n+\tthat match the pathspec.\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@@ -90,7 +93,7 @@ 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 `git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]`::\n-\tThis is similar to the previous mode, but lets you use the\n+\tThis is similar to the previous two modes, but lets you use the\n \tinteractive interface to show the \"diff\" output and choose which\n \thunks to use in the result.  See below for the description of\n \t`--patch` option.\n-- \ngitgitgadget\n\n"},{"id":"526075","messageId":"db603b1e5f833556430150f31fde0a24214c680f.1757531669.git.gitgitgadget@gmail.com","threadId":"64030","inReplyTo":"pull.1962.v4.git.1757531669.gitgitgadget@gmail.com","subject":"[PATCH v4 7/7] doc: git-checkout: clarify restoring files section","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-09-10T19:14:29Z","receivedAt":"2025-09-10T19:14:42Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nFrom user feedback on this section: 3 users don't know what \"tree-ish\"\nmeans and 3 users don't know what \"pathspec\" means. One user also says\nthat the section is very confusing and that they don't understand what\nthe \"index\" is.\n\nFrom conversations on Mastodon, several users said that their impression\nis that \"the index\" means the same thing as \"HEAD\". It would be good to\ngive those users (and other users who do not know what \"index\" means) a\nhint as to its meaning.\n\nMake this section more accessible to users who don't know what the terms\n\"pathspec\", \"tree-ish\", and \"index\" mean by using more familiar language,\nadding examples, and using simpler sentence structures.\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-checkout.adoc | 29 ++++++++++++++++++-----------\n 1 file changed, 18 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex 1e19e13a0e..d8e8bcf549 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -75,22 +75,29 @@ Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.\n `git checkout <tree-ish> [--] <pathspec>...`::\n `git checkout <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]`::\n \n-\tOverwrite both the index and the working tree with the\n-\tcontents at the _<tree-ish>_ for the files that match the pathspec.\n+\tReplace the specified files and/or directories with the version from\n+\tthe given commit or tree and add them to the index\n+\t(also known as \"staging area\").\n++\n+For example, `git checkout main file.txt` will replace `file.txt`\n+with the version from `main`.\n \n `git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...`::\n `git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]`::\n \n-\tOverwrite working tree with the contents in the index for the files\n-\tthat match the pathspec.\n+\tReplace the specified files and/or directories with the version from\n+\tthe index.\n++\n+For example, if you check out a commit, edit `file.txt`, and then\n+decide those changes were a mistake, `git checkout file.txt` will\n+discard any unstaged changes to `file.txt`.\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-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 re-create the original conflicted merge result.\n+This will fail if the file has a merge conflict and you haven't yet run\n+`git add file.txt` (or something equivalent) to mark it as resolved.\n+You can use `-f` to ignore the unmerged files instead of failing, use\n+`--ours` or `--theirs` to replace them with the version from a specific\n+side of the merge, or use `-m` to replace them with the original\n+conflicted merge result.\n \n `git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]`::\n \tThis is similar to the previous two modes, but lets you use the\n-- \ngitgitgadget\n"},{"id":"526120","messageId":"1629C205-700F-4A8A-84BE-302D172416F8@gmail.com","threadId":"64030","inReplyTo":"pull.1962.v4.git.1757531669.gitgitgadget@gmail.com","subject":"Re: [PATCH v4 0/7] doc: git-checkout: clarify DESCRIPTION section","fromName":"Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-09-11T13:01:20Z","receivedAt":"2025-09-11T13:01:33Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"\n> Le 10 sept. 2025 à 15:14, Julia Evans via GitGitGadget <gitgitgadget@gmail.com> a écrit :\n> \n> I got feedback from 22 existing Git users on the existing git checkout man\n> page, using this tool: https://text-feedback.wizardzines.com/git-checkout.\n> From a short survey they filled out, about 90% of the users who gave the\n> feedback have 5+ years of experience using Git.\n> \n> This series goes through the DESCRIPTION section from beginning to end,\n> addressing points that users found confusing in each variant of git\n> checkout. The goal is to clarify while communicating the same information.\n> \n> Changes in v2:\n> \n> * Remove the numbered list from the beginning, from Junio's review\n> * Describe what it means to \"switch branches\" in a way that's hopefully\n>   more accessible to newcomers, from Junio's review\n> * Improve the ARGUMENT DISAMBIGUATION section, from Junio and Ben's reviews\n>   (\"conflict\" => \"ambiguity\", explain correctly what the default is)\n> * The explanation of git checkout [<tree-ish>] <pathspec> had a lot of\n>   issues, from Junio's review. Resolve this by splitting up the git\n>   checkout [] section into two sections. Use \"Replace\" instead of\n>   \"Restore\".\n> \n> Changes in v3:\n> \n> * Fix incorrect description of when git checkout <branch>, from Junio's\n>   review\n> * Take a different approach to the git checkout -b description (keep reset\n>   in -B, but simplify the description of -B a lot to remove the\n>   \"transactional equivalent..\" paragraph), from Junio's review\n> * Say \"switch to the commit\" instead of \"switches commits\", from Junio's\n>   review\n> * Try a different approach to git checkout file.txt (\"Discard any unstaged\n>   changes...\")\n> \n> Changes in v4:\n> \n> * Rewrite all the commit messages to try to take a more Problem / Solution\n>   approach, from Junio's review and thanks to help from @nasamuffin in\n>   Discord. Also change the cover letter format to match the style in\n>   https://lore.kernel.org/git/CAOLa=ZStgwBN0fMK3YxoqeR+1i772f621supva3Kvr7YPq4g8g@mail.gmail.com/T/#m8c99a3144cbdfb445e04f8f83a79364bfe8d797d\n>   , which hopefully matches the norms of this mailing list better.\n\nThis was pleasant reading to me. Not sure how it felt for you to write? Or if the convention was just not spelled out enough to get you where you wanted to be? :)\n\n> * Try a different approach to the \"left unchanged...\", from Junio's review\n> * Bring back \"index\" (with a few hints about what the word might mean),\n>   from Junio's review.\n> * Bring back the numbered list at the beginning from v1, since I think I\n>   misunderstood a comment about lists, and that the original was clearer\n> * Fix an issue I noticed in -B (\"instead of failing\", not \"instead of\n>   creating it\")\n> * Add a comma after branch or commit, to try to make it clear what \"either\"\n>   refers to in that sentence\n> * Replace \"will fail without making any changes\" throughout with just \"will\n>   fail\". I think the default assumption is that Git will fail operations in\n>   a clean way, and that cases where it does not fail cleanly are the\n>   exceptions that the documentation should flag.\n> \n> Julia Evans (7):\n>  doc: git-checkout: clarify intro sentence\n>  doc: git-checkout: clarify ARGUMENT DISAMBIGUATION\n>  doc: git-checkout: clarify `git checkout <branch>`\n>  doc: git-checkout: clarify `-b` and `-B`\n>  doc: git-checkout: deduplicate --detach explanation\n>  doc: git-checkout: split up restoring files section\n>  doc: git-checkout: clarify restoring files section\n> \n> Documentation/git-checkout.adoc | 151 ++++++++++++++++----------------\n> 1 file changed, 76 insertions(+), 75 deletions(-)\n> \n> \n> base-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0\n> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1962%2Fjvns%2Fclarify-checkout-v4\n> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1962/jvns/clarify-checkout-v4\n> Pull-Request: https://github.com/gitgitgadget/git/pull/1962\n> \n> Range-diff vs v3:\n\nRange-diff looks good to me!\n\n> \n> -:  ---------- > 1:  4b52ffd497 doc: git-checkout: clarify intro sentence\n> 1:  1975384dd0 ! 2:  08f0a5efab doc: git-checkout: clarify intro\n>     @@ Metadata\n>      Author: Julia Evans <julia@jvns.ca>\n> \n>       ## Commit message ##\n>     -    doc: git-checkout: clarify intro\n>     +    doc: git-checkout: clarify ARGUMENT DISAMBIGUATION\n> \n>     -    - Reduce use of jargon (\"index\", \"pathspec\", \"tree\") by using an\n>     -      example, and by mirroring the \"switch\" and \"restore\" language from the\n>     -      first line of the man page.\n>     -    - Reference and clarify the ARGUMENT DISAMBIGUATION section, as well\n>     -      as fixing a small error (in \"`git checkout abc`, `abc` is a commit,\n>     -      not a `_<tree-ish>_`)\n>     +    There's no need to use the terms \"pathspec\" or \"tree-ish\" in the\n>     +    ARGUMENT DISAMBIGUATION section, which are terms that (from user\n>     +    feedback on this page) many users do not understand.\n>     +\n>     +    \"tree-ish\" is actually not accurate here: `git checkout` in this case\n>     +    takes a commit-ish, not a tree-ish. So we can say \"branch or commit\"\n>     +    instead of \"tree-ish\" which is both more accurate and uses more familiar\n>     +    terms.\n>     +\n>     +    And now that the intro to the man pages mentions that `git checkout` has\n>     +    \"two main modes\", it makes sense to refer to this disambiguation section\n>     +    to understand how Git decides which one to use when there's an overlap\n>     +    in syntax.\n> \n>          Signed-off-by: Julia Evans <julia@jvns.ca>\n> \n>       ## Documentation/git-checkout.adoc ##\n>     -@@ Documentation/git-checkout.adoc: git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]\n>     +@@ Documentation/git-checkout.adoc: DESCRIPTION\n>     + 2. **Restore a different version of a file**, for example with\n>     +    `git checkout <commit> <filename>` or `git checkout <filename>`\n> \n>     - DESCRIPTION\n>     - -----------\n>     --Updates files in the working tree to match the version in the index\n>     --or the specified tree.  If no pathspec was given, `git checkout` will\n>     --also update `HEAD` to set the specified branch as the current\n>     --branch.\n>     -+`git checkout` has two main modes: it can\n>     -+**switch branches**, for example with `git checkout <branch>`, and\n>     -+**restore files from a different version**, for example with\n>     -+`git checkout <commit> <filename>` or `git checkout <filename>`\n>     -+\n>      +See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.\n>     -\n>     ++\n>       `git checkout [<branch>]`::\n>           To prepare for working on _<branch>_, switch to it by updating\n>     +    the index and the files in the working tree, and by pointing\n>      @@ Documentation/git-checkout.adoc: $ git log -g -2 HEAD\n>       ARGUMENT DISAMBIGUATION\n>       -----------------------\n>     @@ Documentation/git-checkout.adoc: $ git log -g -2 HEAD\n>      -to checkout these paths out of the index.\n>      +When you run `git checkout <something>`, Git tries to guess whether\n>      +`<something>` is intended to be a branch, a commit, or a set of file(s),\n>     -+and then either switches to that branch or commit or restores the\n>     ++and then either switches to that branch or commit, or restores the\n>      +specified files.\n>      +\n>      +If there's any ambiguity, Git will treat `<something>` as a branch or\n\n> 6:  90fe48cfe3 ! 7:  db603b1e5f doc: git-checkout: clarify restoring files section\n>     @@ Metadata\n>       ## Commit message ##\n>          doc: git-checkout: clarify restoring files section\n> \n>     -    - Reword to avoid jargon (\"tree-ish\", \"index\") where possible.\n>     -      Use \"commit or tree\" and \"stage\" (as a verb) instead where appropriate\n>     -    - Add examples\n>     -    - Use a simpler sentence structure to describe options for handling\n>     -      unmerged entries: \"use -f to.., use --ours to..., or use -m to..\"\n>     +    From user feedback on this section: 3 users don't know what \"tree-ish\"\n>     +    means and 3 users don't know what \"pathspec\" means. One user also says\n>     +    that the section is very confusing and that they don't understand what\n>     +    the \"index\" is.\n>     +\n>     +    From conversations on Mastodon, several users said that their impression\n>     +    is that \"the index\" means the same thing as \"HEAD\". It would be good to\n>     +    give those users (and other users who do not know what \"index\" means) a\n>     +    hint as to its meaning.\n>     +\n>     +    Make this section more accessible to users who don't know what the terms\n>     +    \"pathspec\", \"tree-ish\", and \"index\" mean by using more familiar language,\n>     +    adding examples, and using simpler sentence structures.\n\nWithout re-examining the individual patches, I see that 2/7 and 7/7 (possibly also new 1/7) lost pointers to pathspecs. I think I mentioned this previously: I hope we can find some way to direct folks towards the glossary entries that describe them. I would consider pathspecs a power-user feature, and they create lots of useful affordances. So it is fair to more gently introduce newcomers, but I would also still like to make sure it clear when commands accept pathspec “magic” :)\n\nOTOH, I’ll take a look at the docs after this series lands and see if it feels like something is missing. It may be just fine to have pathspecs in the synopses and add a sentence somewhere after the gentle introduction “For more ways to specify paths, see…”"},{"id":"526191","messageId":"236a79f4-e9a2-4335-bbff-79ae0cc67e9b@app.fastmail.com","threadId":"64030","inReplyTo":"1629C205-700F-4A8A-84BE-302D172416F8@gmail.com","subject":"Re: [PATCH v4 0/7] doc: git-checkout: clarify DESCRIPTION section","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-09-12T14:05:13Z","receivedAt":"2025-09-12T14:05:35Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":">> * Rewrite all the commit messages to try to take a more Problem / Solution\n>>   approach, from Junio's review and thanks to help from @nasamuffin in\n>>   Discord. Also change the cover letter format to match the style in\n>>   https://lore.kernel.org/git/CAOLa=ZStgwBN0fMK3YxoqeR+1i772f621supva3Kvr7YPq4g8g@mail.gmail.com/T/#m8c99a3144cbdfb445e04f8f83a79364bfe8d797d\n>>   , which hopefully matches the norms of this mailing list better.\n>\n> This was pleasant reading to me. Not sure how it felt for you to write? \n> Or if the convention was just not spelled out enough to get you where \n> you wanted to be? :)\n\nThis one took a few hours because I had to backfill all of the \"Changes in v2...\",\n\"Changes in v3...\" but I think future ones will be faster to write.\n\nRe the convention not being spelled out: in the \"my first contribution\" guide, it says:\n\n> Edit your cover letter again. Now is a good time to mention what's different\n> between your last version and now, if it's something significant. You do not\n> need the exact same body in your second cover letter; focus on explaining to\n> reviewers the changes you've made that may not be as visible.\n\nThe key elements that I was missing from this were:\n\n1. it's actually probably good to keep some (most?) of the body from your original\n  cover letter, so that folks don't have to go back to remember what this is about\n2. It's useful to flag which review comments you addressed and which you didn't,\n  and why, not just what the changes you made are\n\n(I might have gotten those 2 points wrong though!)\n\n>>     +    Make this section more accessible to users who don't know what the terms\n>>     +    \"pathspec\", \"tree-ish\", and \"index\" mean by using more familiar language,\n>>     +    adding examples, and using simpler sentence structures.\n>\n> Without re-examining the individual patches, I see that 2/7 and 7/7 \n> (possibly also new 1/7) lost pointers to pathspecs. I think I mentioned \n> this previously: I hope we can find some way to direct folks towards \n> the glossary entries that describe them. I would consider pathspecs a \n> power-user feature, and they create lots of useful affordances. So it \n> is fair to more gently introduce newcomers, but I would also still like \n> to make sure it clear when commands accept pathspec “magic” :)\n>\n> OTOH, I’ll take a look at the docs after this series lands and see if \n> it feels like something is missing. It may be just fine to have \n> pathspecs in the synopses and add a sentence somewhere after the gentle \n> introduction “For more ways to specify paths, see…”\n\nSorry for not mentioning that. My idea was to just leave <pathspec> in the\nsynopsis, and then folks can look it up in the glossary if they're curious.\n\nIn the web documentation (https://git-scm.com/docs/git-checkout), the word\n\"pathspec\" is underlined, and hovering over it will show the definition, which\nI think will help with discoverability. Of course in the terminal version of the\nman pages it's harder to build in affordances like that.\n\nDo you think that the concept of a \"pathspec\" is especially useful/powerful\nin the case of `git checkout`? If we're thinking more globally, i wonder if we\ncould find a Git command where more complex pathspecs are especiallly\nuseful and then include some examples of using a complex pathspec there.\n\nIf we include a compelling example and then a \"see X for more about...\" (here or\nsomewhere else) I think it would be much more likely to motivate users to follow\nthe breadcrumbs to learn more.\n"},{"id":"526194","messageId":"35faaf30-6326-4784-80ff-723c20ed6b13@app.fastmail.com","threadId":"64030","inReplyTo":"236a79f4-e9a2-4335-bbff-79ae0cc67e9b@app.fastmail.com","subject":"Re: [PATCH v4 0/7] doc: git-checkout: clarify DESCRIPTION section","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-09-12T14:26:36Z","receivedAt":"2025-09-12T14:26:57Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Fri, Sep 12, 2025, at 16:05, Julia Evans wrote:\n>> OTOH, I’ll take a look at the docs after this series lands and see if\n>> it feels like something is missing. It may be just fine to have\n>> pathspecs in the synopses and add a sentence somewhere after the gentle\n>> introduction “For more ways to specify paths, see…”\n>\n> Sorry for not mentioning that. My idea was to just leave <pathspec> in the\n> synopsis, and then folks can look it up in the glossary if they're curious.\n>\n> In the web documentation (https://git-scm.com/docs/git-checkout), the word\n> \"pathspec\" is underlined, and hovering over it will show the definition, which\n> I think will help with discoverability. Of course in the terminal version of the\n> man pages it's harder to build in affordances like that.\n>\n> Do you think that the concept of a \"pathspec\" is especially useful/powerful\n> in the case of `git checkout`? If we're thinking more globally, i wonder if we\n> could find a Git command where more complex pathspecs are especiallly\n> useful and then include some examples of using a complex pathspec there.\n>\n> If we include a compelling example and then a \"see X for more about...\" (here or\n> somewhere else) I think it would be much more likely to motivate users to follow\n> the breadcrumbs to learn more.\n\nI think pathspecs are great for git-grep(1).\n\n    # Docs but ignore release notes\n    git grep loop -- Documentation/ ':^Documentation/RelNotes'\n    # Just the git(1) manuals (more or less)\n    git grep loop -- 'Documentation/git-*adoc'\n\nAnd also for narrowing a git-diff(1), like ignoring `pom.xml` changes in\na Java project.\n\n(But I never got into the habit of using them with git-checkout(1))\n\nBut once you learn about them you indeed can find uses for them in a lot\nof corners.  I used them today and yesterday to selectively git-clean(1)\nand git-rm(1).\n\nThere should be a gitpathspecs(7).  Not just a glossary entry.\n"},{"id":"526201","messageId":"xmqqy0qjmyh9.fsf@gitster.g","threadId":"64030","inReplyTo":"236a79f4-e9a2-4335-bbff-79ae0cc67e9b@app.fastmail.com","subject":"Re: [PATCH v4 0/7] doc: git-checkout: clarify DESCRIPTION section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-09-12T16:23:14Z","receivedAt":"2025-09-12T16:23:16Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" <julia@jvns.ca> writes:\n\n> Do you think that the concept of a \"pathspec\" is especially useful/powerful\n> in the case of `git checkout`?\n\nIn a project that organizes its files reasonably cleanly, after\ndoing a random explory development to reach a good stopping point, a\nuser would realize that changes to subdirectory X and Y are good but\nchanges to subdirectory Z are all useless, in which case of course\n\"git checkout Z\" (from the index, if you haven't done 'git add' to\nrecord interim state to the index), or \"git checkout HEAD Z\" (to get\nback to the pristine state) would be especially useful/powerful.\n\nOf course, all the commands that take pathspec gain its benefits\nequally well, like \"git grep -e pattern ':!not-here/'\" to find\npattern from everywhere except somewhere, \"git log -p Doc/\" to see\nchanges that touched subset of paths, \"git reset Z/\" to undo earlier\nseries of \"git add\"s only for the specified subset of paths.\n\nIf you are trying to find a command that new people are likely to\nfirst benefit from pathspec, I tend to think 'checkout' is not one\nof them.  Be it 'reset' or 'checkout', the form with pathspec is\ntypically used to undo the effect of earlier 'add' with pathspec, so\nin that sense, if we want to give a quick tutorial for pathspec to\nnewbies in the documentation for a single command, 'add' probably is\nmore appropriate than 'checkout'.\n"},{"id":"526403","messageId":"xmqq4it3e1y7.fsf@gitster.g","threadId":"64030","inReplyTo":"35faaf30-6326-4784-80ff-723c20ed6b13@app.fastmail.com","subject":"Re: [PATCH v4 0/7] doc: git-checkout: clarify DESCRIPTION section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-09-15T23:22:08Z","receivedAt":"2025-09-15T23:22:11Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Kristoffer Haugsbakk\" <kristofferhaugsbakk@fastmail.com> writes:\n\n> There should be a gitpathspecs(7).  Not just a glossary entry.\n\nThis sounds like a good #leftoverbits topic for new-ish people to\nwork on, with help from old timers?  I do agree that the entry in\nthe glossary has grown to be way too big.  The pathspec magic itself\nshould be mentioned there in the glossary, but the details of it\nfeels a bit too much and the topic probably deserves its own manual\npage, just like gitrevisions(7) has one.\n\nThanks.\n"},{"id":"526422","messageId":"b144874c-c4b4-4f77-a1d8-675314517bf5@app.fastmail.com","threadId":"64030","inReplyTo":"xmqq4it3e1y7.fsf@gitster.g","subject":"Re: [PATCH v4 0/7] doc: git-checkout: clarify DESCRIPTION section","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-09-16T06:41:40Z","receivedAt":"2025-09-16T06:42:02Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Tue, Sep 16, 2025, at 01:22, Junio C Hamano wrote:\n> \"Kristoffer Haugsbakk\" <kristofferhaugsbakk@fastmail.com> writes:\n>\n>> There should be a gitpathspecs(7).  Not just a glossary entry.\n>\n> This sounds like a good #leftoverbits topic for new-ish people to\n> work on, with help from old timers?  I do agree that the entry in\n> the glossary has grown to be way too big.  The pathspec magic itself\n> should be mentioned there in the glossary, but the details of it\n> feels a bit too much and the topic probably deserves its own manual\n> page, just like gitrevisions(7) has one.\n\nI added it to the unofficial tracker.\n\nhttps://github.com/gitgitgadget/git/issues/1971\n\n-- \nKristoffer Haugsbakk\n"},{"id":"526612","messageId":"xmqq8qicdivb.fsf@gitster.g","threadId":"64030","inReplyTo":"pull.1962.v4.git.1757531669.gitgitgadget@gmail.com","subject":"Re: [PATCH v4 0/7] doc: git-checkout: clarify DESCRIPTION section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-09-17T18:38:48Z","receivedAt":"2025-09-17T18:38:50Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> Changes in v4:\n>\n>  * Rewrite all the commit messages to try to take a more Problem / Solution\n>    approach, from Junio's review and thanks to help from @nasamuffin in\n>    Discord. Also change the cover letter format to match the style in\n>    https://lore.kernel.org/git/CAOLa=ZStgwBN0fMK3YxoqeR+1i772f621supva3Kvr7YPq4g8g@mail.gmail.com/T/#m8c99a3144cbdfb445e04f8f83a79364bfe8d797d\n>    , which hopefully matches the norms of this mailing list better.\n>  * Try a different approach to the \"left unchanged...\", from Junio's review\n>  * Bring back \"index\" (with a few hints about what the word might mean),\n>    from Junio's review.\n>  * Bring back the numbered list at the beginning from v1, since I think I\n>    misunderstood a comment about lists, and that the original was clearer\n>  * Fix an issue I noticed in -B (\"instead of failing\", not \"instead of\n>    creating it\")\n>  * Add a comma after branch or commit, to try to make it clear what \"either\"\n>    refers to in that sentence\n>  * Replace \"will fail without making any changes\" throughout with just \"will\n>    fail\". I think the default assumption is that Git will fail operations in\n>    a clean way, and that cases where it does not fail cleanly are the\n>    exceptions that the documentation should flag.\n\nThanks for updating.  After re-reading these over, I think the\nupdated text is a vast improvement.  Also, after waiting for a\nwhile, we haven't heard much more comments on these changes.\n\nShall we congratulate a job very well done, declare victory, and\nmerge these down to 'next' now?\n\nThanks.\n"},{"id":"527592","messageId":"df251b0c-c593-41ed-903e-8fb1c323b874@app.fastmail.com","threadId":"64030","inReplyTo":"e636475cba2246ea98e461579a25b41b0ef4e99d.1757531669.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v4 4/7] doc: git-checkout: clarify `-b` and `-B`","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-09-29T18:07:35Z","receivedAt":"2025-09-29T18:07:57Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Wed, Sep 10, 2025, at 21:14, Julia Evans via GitGitGadget wrote:\n>[snip]\n> diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\n> index 0db32b098e..7ae2ae9483 100644\n> --- a/Documentation/git-checkout.adoc\n> +++ b/Documentation/git-checkout.adoc\n> @@ -47,27 +47,21 @@ $ git checkout -b <branch> --track <remote>/<branch>\n>  Running `git checkout` without specifying a branch has no effect except\n>  to print out the tracking information for the current branch.\n>\n> -`git checkout (-b|-B) <new-branch> [<start-point>]`::\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, _<new-branch>_ is created if it doesn't exist; otherwise, it\n> -is reset. This is the transactional equivalent of\n> -+\n> -------------\n> -$ git branch -f <branch> [<start-point>]\n> -$ git checkout <branch>\n> -------------\n> +`git checkout -b <new-branch> [<start-point>]`::\n> +\n> +\tCreate a new branch named _<new-branch>_, start it at _<start-point>_\n> +\t(defaults to the current commit), and check out the new branch.\n> +\tYou can use the `--track` or `--no-track` options to set the branch's\n> +\tupstream tracking information.\n>  +\n> -that is to say, the branch is not reset/created unless \"git checkout\" is\n> -successful (e.g., when the branch is in use in another worktree, not\n> -just the current branch stays the same, but the branch is not reset to\n> -the start-point, either).\n> +This will fail if there's an error checking out _<new-branch>_, for\n> +example if checking out the `<start-point>` commit would overwrite your\n> +uncommitted changes.\n> +\n> +`git checkout -B <branch> [<start-point>]`::\n> +\n> +\tThe same as `-b`, except that if the branch already exists it\n> +\tresets `_<branch>_` to the start point instead of failing.\n\ns/`_<branch>_`/_<branch>_/\n\nThe backticks causes it to be rendered with the underlines.\n\n>\n>  `git checkout --detach [<branch>]`::\n>  `git checkout [--detach] <commit>`::\n> @@ -157,16 +151,14 @@ of it\").\n>  \tsee linkgit:git-branch[1] for details.\n>\n>  `-B <new-branch>`::\n> -\tCreates the branch _<new-branch>_, start it at _<start-point>_;\n> -\tif it already exists, then reset it to _<start-point>_. And then\n> -\tcheck the resulting branch out.  This is equivalent to running\n> -\t`git branch` with `-f` followed by `git checkout` of that branch;\n> -\tsee linkgit:git-branch[1] for details.\n> +\tThe same as `-b`, except that if the branch already exists it\n> +\tresets `_<branch>_` to the start point instead of failing.\n\ns/`_<branch>_`/_<branch>_/\n\n>\n>  `-t`::\n>  `--track[=(direct|inherit)]`::\n>  \tWhen creating a new branch, set up \"upstream\" configuration. See\n> -\t`--track` in linkgit:git-branch[1] for details.\n> +\t`--track` in linkgit:git-branch[1] for details. As a convenience,\n> +\t--track without -b implies branch creation.\n>  +\n>  If no `-b` option is given, the name of the new branch will be\n>  derived from the remote-tracking branch, by looking at the local part of\n> --\n> gitgitgadget\n"},{"id":"527821","messageId":"359afc34863.1759430054.git.code@khaugsbakk.name","threadId":"64030","inReplyTo":"df251b0c-c593-41ed-903e-8fb1c323b874@app.fastmail.com","subject":"[PATCH] doc: git-checkout: fix placeholder markup","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-10-02T18:37:52Z","receivedAt":"2025-10-02T18:38:34Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk <code@khaugsbakk.name>\n\nThe placeholder markup is underscore (_), not backtick (`) as well.\n\nThe inline-verbatim markup (backticks) handle interior formatting. This\nmeans in this case that it applies HTML `<code>` to the underscores and\n`<em>` to the placeholder.\n\nThat is the effect, anyway; we can see from the rest of 042d6f34 (doc:\ngit-checkout: clarify `-b` and `-B`, 2025-09-10) that this was probably\nan unintended mix-up.\n\nSigned-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n---\n\nNotes (series):\n    Since this has landed in `master` now.\n\n Documentation/git-checkout.adoc | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex 431185ca0ba..6f281b298ef 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -61,7 +61,7 @@ uncommitted changes.\n `git checkout -B <branch> [<start-point>]`::\n \n \tThe same as `-b`, except that if the branch already exists it\n-\tresets `_<branch>_` to the start point instead of failing.\n+\tresets _<branch>_ to the start point instead of failing.\n \n `git checkout --detach [<branch>]`::\n `git checkout [--detach] <commit>`::\n@@ -155,7 +155,7 @@ of it\").\n \n `-B <new-branch>`::\n \tThe same as `-b`, except that if the branch already exists it\n-\tresets `_<branch>_` to the start point instead of failing.\n+\tresets _<branch>_ to the start point instead of failing.\n \n `-t`::\n `--track[=(direct|inherit)]`::\n\nbase-commit: 83a9405e59e9cdfb587b19c50f0c040f346dd4ea\n-- \n2.51.0.327.gddebdc8c038\n\n"},{"id":"529029","messageId":"54bc6875cc5.1760652634.git.code@khaugsbakk.name","threadId":"64030","inReplyTo":"359afc34863.1759430054.git.code@khaugsbakk.name","subject":"[PATCH resend] doc: git-checkout: fix placeholder markup","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-10-16T22:11:30Z","receivedAt":"2025-10-16T22:11:42Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk <code@khaugsbakk.name>\n\nThe placeholder markup is underscore (_), not backtick (`) as well.\n\nThe inline-verbatim markup (backticks) handle interior formatting. This\nmeans in this case that it applies HTML `<code>` to the underscores and\n`<em>` to the placeholder.\n\nThat is the effect, anyway; we can see from the rest of 042d6f34 (doc:\ngit-checkout: clarify `-b` and `-B`, 2025-09-10) that this was probably\nan unintended mix-up.\n\nSigned-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n---\n\nNotes (series):\n    Since this has landed in `master` now.\n\n Documentation/git-checkout.adoc | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex 431185ca0ba..6f281b298ef 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -61,7 +61,7 @@ uncommitted changes.\n `git checkout -B <branch> [<start-point>]`::\n \n \tThe same as `-b`, except that if the branch already exists it\n-\tresets `_<branch>_` to the start point instead of failing.\n+\tresets _<branch>_ to the start point instead of failing.\n \n `git checkout --detach [<branch>]`::\n `git checkout [--detach] <commit>`::\n@@ -155,7 +155,7 @@ of it\").\n \n `-B <new-branch>`::\n \tThe same as `-b`, except that if the branch already exists it\n-\tresets `_<branch>_` to the start point instead of failing.\n+\tresets _<branch>_ to the start point instead of failing.\n \n `-t`::\n `--track[=(direct|inherit)]`::\n\nbase-commit: 83a9405e59e9cdfb587b19c50f0c040f346dd4ea\n-- \n2.51.1.498.g8f0801f1c10\n\n"},{"id":"529066","messageId":"8bf911ab-c9d9-4a22-acd2-2dcd05517f41@app.fastmail.com","threadId":"64030","inReplyTo":"54bc6875cc5.1760652634.git.code@khaugsbakk.name","subject":"Re: [PATCH resend] doc: git-checkout: fix placeholder markup","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-10-17T13:56:33Z","receivedAt":"2025-10-17T13:57:40Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"Thanks, apologies for missing this at the time.\n\nOn Thu, Oct 16, 2025, at 6:11 PM, kristofferhaugsbakk@fastmail.com wrote:\n> From: Kristoffer Haugsbakk <code@khaugsbakk.name>\n>\n> The placeholder markup is underscore (_), not backtick (`) as well.\n>\n> The inline-verbatim markup (backticks) handle interior formatting. This\n> means in this case that it applies HTML `<code>` to the underscores and\n> `<em>` to the placeholder.\n>\n> That is the effect, anyway; we can see from the rest of 042d6f34 (doc:\n> git-checkout: clarify `-b` and `-B`, 2025-09-10) that this was probably\n> an unintended mix-up.\n>\n> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n> ---\n>\n> Notes (series):\n>     Since this has landed in `master` now.\n>\n>  Documentation/git-checkout.adoc | 4 ++--\n>  1 file changed, 2 insertions(+), 2 deletions(-)\n>\n> diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\n> index 431185ca0ba..6f281b298ef 100644\n> --- a/Documentation/git-checkout.adoc\n> +++ b/Documentation/git-checkout.adoc\n> @@ -61,7 +61,7 @@ uncommitted changes.\n>  `git checkout -B <branch> [<start-point>]`::\n> \n>  \tThe same as `-b`, except that if the branch already exists it\n> -\tresets `_<branch>_` to the start point instead of failing.\n> +\tresets _<branch>_ to the start point instead of failing.\n> \n>  `git checkout --detach [<branch>]`::\n>  `git checkout [--detach] <commit>`::\n> @@ -155,7 +155,7 @@ of it\").\n> \n>  `-B <new-branch>`::\n>  \tThe same as `-b`, except that if the branch already exists it\n> -\tresets `_<branch>_` to the start point instead of failing.\n> +\tresets _<branch>_ to the start point instead of failing.\n> \n>  `-t`::\n>  `--track[=(direct|inherit)]`::\n>\n> base-commit: 83a9405e59e9cdfb587b19c50f0c040f346dd4ea\n> -- \n> 2.51.1.498.g8f0801f1c10\n"},{"id":"529080","messageId":"v2-cb38c701537.1760716150.git.code@khaugsbakk.name","threadId":"64030","inReplyTo":"54bc6875cc5.1760652634.git.code@khaugsbakk.name","subject":"[PATCH v2] doc: git-checkout: fix placeholder markup","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-10-17T15:50:12Z","receivedAt":"2025-10-17T15:50:41Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk <code@khaugsbakk.name>\n\nThe placeholder markup is underscore (_), not backtick (`) as well.\n\nThe inline-verbatim markup (backticks) handle interior formatting. This\nmeans in this case that it applies HTML `<code>` to the underscores and\n`<em>` to the placeholder.\n\nThat is the effect, anyway; we can see from the rest of 042d6f34 (doc:\ngit-checkout: clarify `-b` and `-B`, 2025-09-10) that this was probably\nan unintended mix-up.\n\nAcked-by: Julia Evans <julia@jvns.ca>\nSigned-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n---\n\nNotes (series):\n    v2:\n    Add Ack.  I also considered removing “probably” from “mix-up” but\n    left it alone as a point-in-time note.  The msg + ack makes it clear.\n    \n    v1:\n    Since this has landed in `master` now.\n\n Documentation/git-checkout.adoc | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex 431185ca0ba..6f281b298ef 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -61,7 +61,7 @@ uncommitted changes.\n `git checkout -B <branch> [<start-point>]`::\n \n \tThe same as `-b`, except that if the branch already exists it\n-\tresets `_<branch>_` to the start point instead of failing.\n+\tresets _<branch>_ to the start point instead of failing.\n \n `git checkout --detach [<branch>]`::\n `git checkout [--detach] <commit>`::\n@@ -155,7 +155,7 @@ of it\").\n \n `-B <new-branch>`::\n \tThe same as `-b`, except that if the branch already exists it\n-\tresets `_<branch>_` to the start point instead of failing.\n+\tresets _<branch>_ to the start point instead of failing.\n \n `-t`::\n `--track[=(direct|inherit)]`::\n\nRange-diff against v1:\n1:  54bc6875cc5 ! 1:  cb38c701537 doc: git-checkout: fix placeholder markup\n    @@ Commit message\n         git-checkout: clarify `-b` and `-B`, 2025-09-10) that this was probably\n         an unintended mix-up.\n     \n    +    Acked-by: Julia Evans <julia@jvns.ca>\n         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n     \n     \n      ## Notes (series) ##\n    +    v2:\n    +    Add Ack.  I also considered removing “probably” from “mix-up” but\n    +    left it alone as a point-in-time note.  The msg + ack makes it clear.\n    +\n    +    v1:\n         Since this has landed in `master` now.\n     \n      ## Documentation/git-checkout.adoc ##\n\nbase-commit: 83a9405e59e9cdfb587b19c50f0c040f346dd4ea\n-- \n2.51.1.498.g8f0801f1c10\n\n"}]}