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

From: Julia Evans <julia@jvns.ca>
Date: Aug 28, 2025, 12:11 UTC
Message-ID: <276630b8-ad98-4ada-aa85-9f136d653d7b@app.fastmail.com>
In-Reply-To: <xmqqldn5ix0r.fsf@gitster.g>

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

I'm not sure what you mean here: "switch to <branch>" is as far as I can tell the most widely used term to refer to this operation, in other Git resources, in Git's own man pages, and in the error output of the `git checkout` command itself: ("Please commit your changes or stash them before you switch branches.") Which readers do you think would be confused by it?

Show 14 quoted lines

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

That makes sense. I'll work on a better way to phrase this.

Show 15 quoted lines

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

Ah, I thought `git status` was faster because I benchmarked it it on one of my repositories and got these results [1].

Now that I see that that's not what "expensive side-effects" was intended to mean, will change to something much simpler, like "Running `git checkout` without specifying a branch outputs the tracking information for the current branch. It has no other effect. "

- Julia

[1]
$ hyperfine 'git status'
Benchmark 1: git status
  Time (mean ± σ):       6.6 ms ±   1.2 ms    [User: 3.2 ms, System: 5.1 ms]
$ hyperfine 'git checkout'
  Time (mean ± σ):      29.5 ms ±   1.9 ms    [User: 12.6 ms, System: 14.8 ms]