Re: PATCH: improve git switch documentation

From: Martin <git@mfriebe.de>
Date: Jul 12, 2021, 17:52 UTC
Message-ID: <0d7bd249-2aba-236a-9f93-3a5b30182d15@mfriebe.de>
In-Reply-To: <60ec74c513b2b_a45252081b@natae.notmuch>

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

Show 25 quoted lines

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

Show 6 quoted lines

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