From: Junio C Hamano <gitster@pobox.com>
Date: Wed, 03 Sep 2025 21:09:15 GMT
Subject: Re: [PATCH v3 0/6] doc: git-checkout: clarify DESCRIPTION section
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:

>  * 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-<.

>      @@ 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>_.

>      ++`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.