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

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 26, 2025, 21:38 UTC
Message-ID: <xmqqldn5ix0r.fsf@gitster.g>
In-Reply-To: <b8873c4529caeddc85879efd122e5a57278352f0.1756148933.git.gitgitgadget@gmail.com>

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

Show 36 quoted lines

> From: Julia Evans <julia@jvns.ca>
>
> - "To prepare for working on _<branch>_..." is confusing to some users:
>   it makes it sound like these are steps that the user has to do, not
>   steps that Git itself will do. Reword it.
> - Use "changes" instead of "modifications" (which Git normally does)
> - Mention that `git checkout` will fail if there's a merge conflict
> - The current explanation of `You could omit <branch>`... is confusing
>   to users (what are the "expensive side effects"? what's a better way
>   of getting the same info?). Be more direct and mention that `git
>   status` is likely a better option.
>
> Signed-off-by: Julia Evans <julia@jvns.ca>
> ---
>  Documentation/git-checkout.adoc | 18 +++++++++---------
>  1 file changed, 9 insertions(+), 9 deletions(-)
>
> diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
> index ddda891c0ff7..a3edb95973a2 100644
> --- a/Documentation/git-checkout.adoc
> +++ b/Documentation/git-checkout.adoc
> @@ -30,11 +30,12 @@ See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.
>  Here's a description of all of the modes:
>  
>  `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 will update the files in the working tree,
> +	point `HEAD` at the branch, and update the index. Local changes to
> +	the files in the working tree are kept, so that they can be committed
> +	to the _<branch>_. If the local changes conflict with the changes on
> +	_<branch>_, no changes will be made and the checkout operation will
> +	fail.

Do we expect readers to truly understand what is to "switch to branch" without explanation? IOW, I am undecided if the lost "To prepare for working on" is a good thing.

Usually with "changes on _<branch>_", people mean quite a different thing from what the above paragraph refers to.

Imagine that you are on a branch that you forked from 'main' some time ago, built a handful of commits, among which there may be ones that touch file F. You further have local modification to file F. Now you want to switch to another branch. That branch, since it forked from 'main', never touched F. Your local changes do not conflict with "the changes on branch" (there is no changes on branch to conflict with your work, as F stayed the same).

To improve, "with the changes on _<branch>_" should be phrased more like "with the differences between the current state and that of the _<branch>_" or something.

Show 14 quoted lines

>  +
>  If _<branch>_ is not found but there does exist a tracking branch in
>  exactly one remote (call it _<remote>_) with a matching name and
> @@ -44,10 +45,9 @@ 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 will output the
> +tracking information, if it exists, for the current branch, but it's
> +slower than getting the same information from `git status`.

I do not think "glorified no-op" is a reference to "status". At least, when I wrote it, I didn't mean it that way to compare this glorified no-op with "git status" [*]. It is a reference to "even though you are invoking the 'checkout' command, you are not checking out anything." The side effect is to see the tracking information, which is "rather expensive side-effects"---compared to doing nothing, anything is expensive ;-).

I strongly suspect that running "git status" is much more costly than "git checkout", simply because the former has to do a lot more than just peeking the tracking information; it internally runs diff between HEAD and the index, and between the index and the working tree, and it also has to find and list untracked paths. Both commands compute the tracking info by calling the same remote.c::format_tracking_info() function.

Other than these minor points, the new text seems a definite improvement.

[References]

 * https://lore.kernel.org/git/7vk3shm5d5.fsf@alter.siamese.dyndns.org/
   is where the "glorified no-op" came from.