git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH v2 2/5] doc: git-checkout: clarify `git checkout <branch>`

From
Junio C Hamano <gitster@pobox.com>
Date
Aug 29, 2025, 16:03 UTC
Message-ID
<xmqqv7m6nmhz.fsf@gitster.g>
In-Reply-To
<23a738981abd2073c70bbb5dd36eea050065e643.1756467934.git.gitgitgadget@gmail.com>
"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
Show 11 quoted lines
>  `git checkout [<branch>]`::
> -	To prepare for working on _<branch>_, switch to it by updating
> -	the index and the files in the working tree, and by pointing
> -	`HEAD` at the branch. Local modifications to the files in the
> -	working tree are kept, so that they can be committed to the
> -	_<branch>_.
> +	Switch to _<branch>_. This sets the current branch to <branch> and
> +	updates the files in your working directory. Local changes to
> +	the files in the working tree are kept, so that they can be committed
> +	to the _<branch>_. If the local changes can't be cleanly merged into
> +	the _<branch>_, no changes will be made and the checkout operation will fail.
The condition to stop you is a bit stronger than that.

By default, we would not even attempt to "merge into the branch" at all. If your previous HEAD and the branch you are switching to are different at a path you have local modifications in, then no changes will be made and the checkout will fail. With "-m", we try to merge and this merge can leave conflicts for you to sort out.

Show 10 quoted lines
> @@ -42,10 +42,8 @@ exactly one remote (call it _<remote>_) with a matching name and
>  $ git checkout -b <branch> --track <remote>/<branch>
>  ------------
>  +
> -You could omit _<branch>_, in which case the command degenerates to
> -"check out the current branch", which is a glorified no-op with
> -rather expensive side-effects to show only the tracking information,
> -if it exists, for the current branch.
> +Running `git checkout` without specifying a branch has no effect except
> +to print out the tracking information for the current branch.

This is much better than the crappy original I wrote years ago. Thanks.

Previous: Julia Evans via GitGitGadgetNext: Julia Evans
Message 31 of 68 in “doc: git-checkout: clarify DESCRIPTION section”
  1. 0/5 doc: git-checkout: clarify DESCRIPTION sectionJulia Evans via GitGitGadget, Aug 25, 2025
  2. 1/5 doc: git-checkout: clarify introJulia Evans via GitGitGadget, Aug 25, 2025
  3. Junio C HamanoAug 26, 2025
  4. Junio C HamanoAug 26, 2025
  5. Julia EvansAug 26, 2025
  6. D. Ben KnobleAug 28, 2025
  7. Julia EvansAug 28, 2025
  8. Junio C HamanoAug 28, 2025
  9. D. Ben KnobleAug 29, 2025
  10. Junio C HamanoAug 29, 2025
  11. D. Ben KnobleSep 3, 2025
  12. 2/5 doc: git-checkout: clarify `git checkout <branch>`Julia Evans via GitGitGadget, Aug 25, 2025
  13. Junio C HamanoAug 26, 2025
  14. Julia EvansAug 28, 2025
  15. Junio C HamanoAug 28, 2025
  16. Julia EvansAug 28, 2025
  17. 3/5 doc: git-checkout: don't use "reset"Julia Evans via GitGitGadget, Aug 25, 2025
  18. 4/5 doc: git-checkout: deduplicate --detach explanationJulia Evans via GitGitGadget, Aug 25, 2025
  19. 5/5 doc: git-checkout: clarify restoring files sectionJulia Evans via GitGitGadget, Aug 25, 2025
  20. Junio C HamanoAug 26, 2025
  21. Julia EvansAug 28, 2025
  22. D. Ben KnobleAug 28, 2025
  23. Julia EvansAug 28, 2025
  24. Junio C HamanoAug 28, 2025
  25. D. Ben KnobleAug 29, 2025
  26. 0/5 doc: git-checkout: clarify DESCRIPTION sectionJulia Evans via GitGitGadget, Aug 29, 2025
  27. 1/5 doc: git-checkout: clarify introJulia Evans via GitGitGadget, Aug 29, 2025
  28. Junio C HamanoAug 29, 2025
  29. Julia EvansSep 2, 2025
  30. 2/5 doc: git-checkout: clarify `git checkout <branch>`Julia Evans via GitGitGadget, Aug 29, 2025
  31. Junio C HamanoAug 29, 2025
  32. Julia EvansSep 2, 2025
  33. 3/5 doc: git-checkout: don't use "reset"Julia Evans via GitGitGadget, Aug 29, 2025
  34. Junio C HamanoAug 29, 2025
  35. Julia EvansSep 1, 2025
  36. Junio C HamanoSep 2, 2025
  37. 4/5 doc: git-checkout: deduplicate --detach explanationJulia Evans via GitGitGadget, Aug 29, 2025
  38. 5/5 doc: git-checkout: clarify restoring files sectionJulia Evans via GitGitGadget, Aug 29, 2025
  39. 0/6 doc: git-checkout: clarify DESCRIPTION sectionJulia Evans via GitGitGadget, Sep 3, 2025
  40. 1/6 doc: git-checkout: clarify introJulia Evans via GitGitGadget, Sep 3, 2025
  41. 2/6 doc: git-checkout: clarify `git checkout <branch>`Julia Evans via GitGitGadget, Sep 3, 2025
  42. 3/6 doc: git-checkout: clarify `-b` and `-B`Julia Evans via GitGitGadget, Sep 3, 2025
  43. 4/6 doc: git-checkout: deduplicate --detach explanationJulia Evans via GitGitGadget, Sep 3, 2025
  44. 5/6 doc: git-checkout: split up restoring files sectionJulia Evans via GitGitGadget, Sep 3, 2025
  45. 6/6 doc: git-checkout: clarify restoring files sectionJulia Evans via GitGitGadget, Sep 3, 2025
  46. Junio C HamanoSep 3, 2025
  47. Junio C HamanoSep 3, 2025
  48. Julia EvansSep 3, 2025
  49. 0/7 doc: git-checkout: clarify DESCRIPTION sectionJulia Evans via GitGitGadget, Sep 10, 2025
  50. 1/7 doc: git-checkout: clarify intro sentenceJulia Evans via GitGitGadget, Sep 10, 2025
  51. 2/7 doc: git-checkout: clarify ARGUMENT DISAMBIGUATIONJulia Evans via GitGitGadget, Sep 10, 2025
  52. 3/7 doc: git-checkout: clarify `git checkout <branch>`Julia Evans via GitGitGadget, Sep 10, 2025
  53. 4/7 doc: git-checkout: clarify `-b` and `-B`Julia Evans via GitGitGadget, Sep 10, 2025
  54. Kristoffer HaugsbakkSep 29, 2025
  55. doc: git-checkout: fix placeholder markupkristofferhaugsbakk@fastmail.com, Oct 2, 2025
  56. doc: git-checkout: fix placeholder markupkristofferhaugsbakk@fastmail.com, Oct 16, 2025
  57. Julia EvansOct 17, 2025
  58. doc: git-checkout: fix placeholder markupkristofferhaugsbakk@fastmail.com, Oct 17, 2025
  59. 5/7 doc: git-checkout: deduplicate --detach explanationJulia Evans via GitGitGadget, Sep 10, 2025
  60. 6/7 doc: git-checkout: split up restoring files sectionJulia Evans via GitGitGadget, Sep 10, 2025
  61. 7/7 doc: git-checkout: clarify restoring files sectionJulia Evans via GitGitGadget, Sep 10, 2025
  62. Ben KnobleSep 11, 2025
  63. Julia EvansSep 12, 2025
  64. Kristoffer HaugsbakkSep 12, 2025
  65. Junio C HamanoSep 15, 2025
  66. Kristoffer HaugsbakkSep 16, 2025
  67. Junio C HamanoSep 12, 2025
  68. Junio C HamanoSep 17, 2025

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.