Re: PATCH: improve git switch documentation

[Martin <git@mfriebe.de>]

On 13/07/2021 00:12, Felipe Contreras wrote:
> Martin wrote:
> A user that does:
> 
>    git switch -n <branch>
> 
> Would naturally expect a new branch to be created.
> 
> If that command creates a new branch safely, why would the user do:
> 
>    git switch -N <branch>
> 
> What do you think the user expects to happen without reading the
> documenation?

Well, first of all what would he think it does if he reads the doc? And 
if that doc looses no (explicit) word on the possible loss?

First of all (not sure, if I mentioned that before), I have seen *many* 
case like that:
The user wants to create a new branch on master "my-feature".
    git switch -c my-feature
Then he realizes that he had not been on master, but on some other 
branch. "-c" now gives an error.
So the  user reads the documentation.
Up to this point, everything is exactly as it should be.
Now what the user reads is that "-C" works if the branch already exists. 
At this point, without being prompted those user will not think of any 
content of the branch (they haven't even added some).
"-C" does in that case what they want.

Of course now, that they had no need to think about any commits, an no 
warning that would have prompted that, they believe "-C" to be save.
Next time they will have commit. And they are gone.

And as for the reflog, look at "checkout -B", "switch -C", "branch -f", 
or "reset".
In the context of re-creating/ressetting a branch, neither of them 
mention how to get it back. (and reflog is something most people learn a 
lot later)

As I said, the first part I have seen many times. The 2nd part, 
obviously only a subset. But that is rather down to people being lucky, 
than to people actually understanding that the commits will disappear.

Now, of course I cannot predict how many people would remember a warning 
it the docs.
But I can tell, if I read a doc, and it says "you may loose...", I will 
pay attention.




> 
> And what do you think they'll expect to happen given this documentation:
> 
>    Create a new branch like '--new', but if the branch already exists
>    it's replaced.
> 
> Forget about what they could misunderstand. Nobody does anything without
> a reason, so what would be the reason why a user does `git switch -N`
> instead of `git switch -n`?
> 

You and I will make the connection between "something happens to the 
branch" and "something happens to the commits".
A lot of people with less experience, who a busy looking through lots of 
stuff to solve their problem, they will not make that connection in that 
particular moment.
Heck, I've seen highly educated people missing far more obvious things 
like that.


> To me this is another instance of "do not drink scorching hot coffee".
> Sure, some users might benefit from reading this, but how many? And how
> many would be annoyed by the obvious unnecessary warning?

Well, at least in the U.S, you apparently have to tell your customers 
that the coffee you sell is hot. (If you recall, there was a "famous" 
court case).
I have always thought, that coffee should be hot (except iced coffee).
You also have to warn people not to put their pets into the microwave. 
Again to me: bleeding obvious.



> 
> Moreover, most users don't even read the documentation. Some might even
> be doing `git switch -h`, and others using zsh completion description.
> So we can't just rely on them reading this line.

Well, so we can't warn the rest? Why do we have docs at all?


> 
> If you are really worried about the user losing information, why don't
> we add a true warning:
> 
>    hint: The previous state of the '%s' branch might have been lost.
>    hint: The id was '%s'.
>    hint:
>    hint: If you didn't intend to do this, you can restore the previous
>    hint: state with:
>    hint:
>    hint:  git reset --hard @{1}
>    hint:
>    hint: Disable this message with "git config advice.switchForceNew false"
> 
> That way the user doesn't need to read the documentation.

Well yes, printing a recovery note, may be another helpful addition.

But as you said, a single way of pushing info, will not reach everyone. 
People putting the command in a script, may not read this.
Btw, a better warning would be similar to the one you get, if you leave 
behind a detached commit.
IIRC, print the sha1, and how to create a branch on that sha1.



Of course there is a different alternative, but IMHO it is overdone.
    git switch -C branch
will only force the current "head value" (I.e. the sha1 used a pointer).
So if you have no commits on that branch, or if they are part of another 
branch, then this will work.

If you stand to "loose" commits, you would have to do:
    git switch -D -C branch

(the D is just an example / other letters/words may be better)
   -D  drop commits


But even, then until that is implemented, a temporary fix by changing 
the docs would still be appropriate.