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

[Junio C Hamano <gitster@pobox.com>]

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

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

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