Re: [PATCH v2 3/5] doc: git-checkout: don't use "reset"

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

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

> From: Julia Evans <julia@jvns.ca>
>
> Many Git users don't know what the term "reset" means. Resolve this by:

Even though it is the name of one of the most often used commands?
And yet a separate step in this series made the claim that everybody
knows what "switch" means because it is the name of another command?

I think the source of the problem is not that they "don't know what
the term means" at all.  Isn't the real problem that the use of the
verb in the original sentence you are correcting in this patch is
vague and does not say what the branch is reset *to*?

> - Expanding it into its definition, in one case

    The description says "-B <branch>" resets the branch if it
    exists, but does not say what it resets to.  Rephrase to clarify
    that it is made to point at the specified commit.

or something?

> - Giving a simpler but still accurate explanation ("the branch will not
>   be created or modified"), in the other case

By the way this kind of use of bulleted list in a proposed log
message I do not mind all that much.  What I reacted to was a list
without the introducing text (in the case of this patch, "resolve
this by doing these things:").
>
> Signed-off-by: Julia Evans <julia@jvns.ca>
> ---
>  Documentation/git-checkout.adoc | 11 +++++------
>  1 file changed, 5 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
> index 4de3ac6680..e4614674f0 100644
> --- a/Documentation/git-checkout.adoc
> +++ b/Documentation/git-checkout.adoc
> @@ -54,18 +54,17 @@ to print out the tracking information for the current branch.
>  	`--track` without `-b` implies branch creation; see the
>  	description of `--track` below.
>  +
> -If `-B` is given, _<new-branch>_ is created if it doesn't exist; otherwise, it
> -is reset. This is the transactional equivalent of
> +If `-B` is given, _<new-branch>_ is created if it doesn't exist;
> +otherwise `<new-branch>` is forced to point at the commit. ...

Good.

> ... This is the
> +transactional equivalent of
>  +
>  ------------
>  $ git branch -f <branch> [<start-point>]
>  $ git checkout <branch>
>  ------------
>  +
> -that is to say, the branch is not reset/created unless "git checkout" is
> -successful (e.g., when the branch is in use in another worktree, not
> -just the current branch stays the same, but the branch is not reset to
> -the start-point, either).
> +that is, the branch will not be created or modified unless
> +`git checkout` is successful.
>  
>  `git checkout --detach [<branch>]`::
>  `git checkout [--detach] <commit>`::

This is in response to "transactional equivalent".  I've always felt
that there is no need to say "transactional" in this at all.  IOW, I
wouldn't have minded if we rewrote this more heavily.

When you have to clarify with things like "that is", "what this
means is", etc., after some text, I've often found that the result
becomes crispier and more clear if we removed fuzzy text that needed
such clarification and rewrite the sentence using elements form only
the clarifying text.

    If `-B` is given, _<new-branch>_ is created if it doesn't exist,
    otherwise, it is made to point at the given commit.  And the
    branch is made the current branch.
    +
    Creation of the new branch or reseting of the existing branch to
    point at the commit happens only if the resulting branch can be
    successfully checked out.  Oterwise branch creation is not done
    and the exiting branch is left as-is.

or something?  I dunno.