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.
