Re: PATCH: improve git switch documentation

From: Martin <git@mfriebe.de>
Date: Jul 11, 2021, 09:10 UTC
Message-ID: <1e18c4ed-6975-5041-4b4f-75c4d3d21860@mfriebe.de>
In-Reply-To: <60ea2eb562f26_2a69208e8@natae.notmuch>

On 11/07/2021 01:35, Felipe Contreras wrote:

Show 13 quoted lines

> Martin wrote:
>> At the end of the current or rewritten "-C" doc, add:
>>   >     This can drop commits
>>
>> 4 words. All that is needed.
> 
> OK. I'm not opposed to that, that would definitely be an improvement
> from the current text.
> 
> What I'm saying is that if we are trying to improve the text, it would
> behoove us to consider all other options, and instead if adding a note
> at the end (which is correct), reconsider the whole thing to *start*
> with what's important:

Ah, ok. So we have been missing each others point.

Show 18 quoted lines

> Instead of this:
> 
>    -C <new-branch>::
>    --force-create <new-branch>::
>      Similar to `--create` except that if `<new-branch>` already
>      exists, it will be reset to `<start-point>`. This is a
>      convenient shortcut for:
>    +
>    ------------
>    $ git branch -f <new-branch>
>    $ git switch <new-branch>
>    ------------
> 
> Do this:
> 
>    -N <branch>::
>      Create a new branch like '--new', but if it already exists reset it
>      like '--reset'.

As I said, I try to avoid reset, and also there is no "--reset" to match. Only a "reset" command, and it does a wide range of diff things

     -force-new <branch-name> <commit>
     -N <branch-name> <commit>
       See the --new option.
       Allows to [re-]use the name of an existing branch.
       This may drop commits of that branch.

Or
       See the --new option.
       Can use the name of an existing branch.
       Removing that branch may drop commits.
If needs must
       "Removing" => "Resetting"

Or even shorter
       See the --new option.
       Allows to re-use a branch-name and may drop commits
       [resetting it].