Re: [PATCH v3 0/6] doc: git-checkout: clarify DESCRIPTION section

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 3, 2025, 21:09 UTC
Message-ID: <xmqqikhzdz0k.fsf@gitster.g>
In-Reply-To: <pull.1962.v3.git.1756918202.gitgitgadget@gmail.com>

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

Show 6 quoted lines

>  * Improve the storytelling in the commit messages
>  * Take a different approach to the git checkout -b description (keep reset
>    in -B, but simplify the description of -B a lot)
>  * Make the description of git checkout [<branch>] more accurate.
>  * Try a different approach to git checkout file.txt ("Discard any unstaged
>    changes...")

Not just you repeat having bulleted list in your proposed log messages (which I already said something about, remember?), now you have them in your cover letter, too? You must be so fond of bulletted list X-<.

Show 7 quoted lines

>      @@ Documentation/git-checkout.adoc: $ git log -g -2 HEAD
>       -to checkout these paths out of the index.
>       +When you run `git checkout <something>`, Git tries to guess whether
>       +`<something>` is intended to be a branch, a commit, or a set of file(s),
>      -+and then switches branches, switches commits, or restores the files.
>      ++and then either switches to that branch or commit or restores the
>      ++specified files.

Much better.

>      ++	Switch to _<branch>_. This sets the current branch to _<branch>_ and
>      ++	updates the files in your working directory. Files which are
>      ++	identical in _<branch>_ and your current commit are left unchanged
>      ++	so that you can keep your uncommitted changes to those files.

Here "left unchanged" is technically correct, but somehow it gives me a (n incorrect) connotation that they are not modified since HEAD, which is not what you wanted to say at all. I recall that we once explained this not as "left unchanged", but as "changes follow you", and I found the explanation easier to absorb.

I cannot come up with a good way to remove duplicates in the following desciption, but what we want the reader to understand are twofold:

 * For paths that are not identical between HEAD and the _<branch>_
   you are switching to, you MUST NOT have a local change.  After
   you switch to _<branch>_, these paths in the working tree match
   that of the _<branch_>.  This is to avoid losing your local
   changes.

 * For paths that are identical between HEAD and the _<branch>_ you
   are switching to, you may have local modifications, and they
   follow you to the switched-to _<branch>_.

Show 10 quoted lines

>      ++`git checkout -b <new-branch> [<start-point>]`::
>      ++
>      ++	Create a new branch named _<new-branch>_, start it at _<start-point>_
>      ++	(defaults to the current commit), and check out the new branch.
>      ++	You can use the `--track` or `--no-track` options to set the branch's
>      ++	upstream tracking information.
>        +
>      ++This fails without making any changes if there's an error checking out
>      ++_<new-branch>_, for example if checking out the `<start-point>`
>      ++commit would overwrite your uncommitted changes.

OK. Do people understand "making a(ny) changes" refers to creation of the new branch, I have to wonder, but if so, the above is much much nicer than the original text.

    This fails without doing anything and without creating a new
    branch, if checking out the <start-point> has to overwrite your
    uncommitted changes.

might be slightly better?  I dunno.