Re: PATCH: improve git switch documentation

[Martin <git@mfriebe.de>]

On 12/07/2021 18:58, Felipe Contreras wrote:
> Martin wrote:
>> On 12/07/2021 18:28, Felipe Contreras wrote:
>>> Martin wrote:
>>>> On 11/07/2021 01:35, Felipe Contreras wrote:
>>>
>>>>> Do this:
>>>>>
>>>>>      -N <branch>::
>>>>>        Create a new branch like '--new', but if it already exists reset it
>>>>>        like '--reset'.
>>>
>>>> Or even shorter
>>>>          See the --new option.
>>>>          Allows to re-use a branch-name and may drop commits
>>>>          [resetting it].
>>>
>>> Yes, it is shorter, but now it doesn't even say what it does.
>>>
>>
>> Ok instead of " see the --new option"
>> use "Same as the --new option, but allows...."
> 
> Yeah, that explains more, but what happend when you use a branch name
> that already exists? Still not explained.
> 


I have to look back in the mails.
There was a lot about getting it shorter, I am happy with a verbose 
version too.

Taking a step back.

> -c <new-branch>
> --create <new-branch>
> 
>     Create a new branch named <new-branch> starting at
>     <start-point> before switching to the branch. 
>     This is a convenient shortcut for:

Should that actually say, that it will fail if the branch-name is 
already taken?
IMHO yes.

The "-C" option could then be (incorporating the "could be lost" from a 
prior mail.

 > -C <new-branch> <commit>
 >    Same the --new option.
 >    But allows to use an existing branch-name. The
 >    [existing|old] branch [for the name] will be removed, and
 >    its commits could be lost.

If using "existing" or "old" then "for the name" is *not* needed, and 
vice versa.

And, yes they can be lost. They can be found again, if one knows where 
to look.