Re: PATCH: improve git switch documentation

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

Martin wrote:

quoted

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.

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