Re: PATCH: improve git switch documentation

[Felipe Contreras <felipe.contreras@gmail.com>]

Martin wrote:
> On 12/07/2021 18:58, Felipe Contreras wrote:

> The "-C" option could then be (incorporating the "could be lost" from a 
> prior mail.
> 
>  > -C <new-branch> <commit>
>  >    Same the --new option.

But it's not the same as --new.

>  >    But allows to use an existing branch-name.

If this is an essential part of the previous sentence, it should be part
of the sentence:.

  Same [as] the --new option, but allows to use an existing branch name.

But this is wasted space:

  Shouting is the same as talking, but with a different volume.

There's no need for another sentence explaining in what way it is
different (higher volume), do it in the same sentence.

What happens when we use an existing branch name?

>  > The [existing|old] branch [for the name] will be removed,

Except this is a lie. At no point is the branch removed; the branch name
is never gone, neither are the commits.

What is actually happening is that the branch head is changed. That is
all. And as I already explained in the subthread, everyone understands
what changing the branch head does to the branch.

Everyone knows what happens when you reset your computer without saving
your Excel spreadsheet. The word "reset" implies loosing state.

If you don't want to use the word "reset", or the term "branch head",
then you can say:

  Same as --new, but if the branch already exists it's replaced.

This *still* doesn't explain what it is doing, you would need to read
--new.

  Create a new branch like '--new', but if the branch already exists
  it's replaced.

Now it is actually self-contained.

> > and its commits could be lost.

The commits are not lost, they are just not part of this branch anymore.
They could easily be part of another branch already.

  Create a new branch like '--new', but if the branch already exists
  it's replaced. The commits that are initially part of the branch might
  not be part of the branch afterwards.

I think the last sentence is superfluous and obvious. Everyone
understands that if A is replaced by B, B might be different from A, and
thus not everything of A might end up in B.

If you want to send a patch with that unnecessary information, go ahead,
what I'm saying is that if the first part is written correctly the last
part is obvious.

Cheers.

-- 
Felipe Contreras