Re: PATCH: improve git switch documentation

[Felipe Contreras <felipe.contreras@gmail.com>]

Martin wrote:
> 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.

Why would they think -C "saves"? And save how?

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

Once again I'm not talking about what they could miss, I'm talking about
what they are thinking the command will do.

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

Yes, and that's stupid. There's plenty of unnecessary warnings.

  * Do not hold the wrong end of a chainsaw.
  * Do not drive with sun shield in place.  
  * Avoid death.

https://www.forbes.com/2011/02/23/dumbest-warning-labels-entrepreneurs-sales-marketing-warning-labels_slide.html

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

The fact that you have to do it in USA doesn't mean you should.

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

To explain how to use commands.

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

Our objective is not to reach everyone.

-- 
Felipe Contreras