From: Felipe Contreras <felipe.contreras@gmail.com>
To: Martin <git@mfriebe.de>,
Felipe Contreras <felipe.contreras@gmail.com>,
git@vger.kernel.org
Subject: Re: PATCH: improve git switch documentation
Date: Tue, 13 Jul 2021 11:02:07 -0500 [thread overview]
Message-ID: <60edb8ff814cf_ab6dd208d9@natae.notmuch> (raw)
In-Reply-To: <d3678ef6-1bcd-2666-87dc-751aef2ca1a7@mfriebe.de>
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
next prev parent reply other threads:[~2021-07-13 16:02 UTC|newest]
Thread overview: 103+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-06-29 15:28 PATCH: improve git switch documentation Martin
2021-06-29 16:35 ` Junio C Hamano
2021-06-29 19:04 ` Martin
2021-06-29 22:39 ` Junio C Hamano
2021-06-30 8:50 ` Martin
2021-06-30 22:59 ` Junio C Hamano
2021-07-01 10:06 ` Martin
2021-07-01 11:27 ` Sergey Organov
2021-07-07 18:34 ` Felipe Contreras
2021-07-07 20:46 ` Sergey Organov
2021-07-07 21:25 ` What actually is a branch? Felipe Contreras
2021-07-07 22:07 ` Sergey Organov
2021-07-07 22:35 ` Martin
2021-07-08 3:39 ` Felipe Contreras
2021-07-08 10:15 ` Martin
2021-07-08 17:33 ` Felipe Contreras
2021-07-08 19:21 ` Martin
2021-07-08 20:37 ` Felipe Contreras
2021-07-08 23:11 ` Martin
2021-07-09 0:45 ` Felipe Contreras
2021-07-09 13:24 ` Martin
2021-07-09 15:08 ` Felipe Contreras
2021-07-09 15:23 ` switch requires --detach [[Re: What actually is a branch]] Martin
2021-07-09 16:21 ` Felipe Contreras
2021-07-09 16:38 ` Randall S. Becker
2021-07-09 17:10 ` Felipe Contreras
2021-07-09 16:54 ` Martin
2021-07-10 10:08 ` Sergey Organov
2021-07-10 19:18 ` Felipe Contreras
2021-07-09 14:29 ` PATCH: improve git switch documentation Martin
2021-07-09 16:10 ` Felipe Contreras
2021-07-09 16:51 ` Martin
2021-07-09 17:41 ` Felipe Contreras
2021-07-09 18:23 ` Martin
2021-07-10 19:45 ` Felipe Contreras
2021-07-10 20:07 ` Martin
2021-07-10 20:49 ` Felipe Contreras
2021-07-10 22:13 ` Martin
2021-07-10 23:35 ` Felipe Contreras
2021-07-11 9:10 ` Martin
2021-07-11 9:30 ` Sergey Organov
2021-07-12 16:28 ` Felipe Contreras
2021-07-12 16:33 ` Martin
2021-07-12 16:58 ` Felipe Contreras
2021-07-12 17:52 ` Martin
2021-07-12 19:08 ` Felipe Contreras
[not found] ` <3a84e4c9-4e48-1cbe-4fe6-150ff56c8508@mfriebe.de>
[not found] ` <60ecbe577a086_a6b702082@natae.notmuch>
2021-07-13 10:42 ` Martin
2021-07-13 16:02 ` Felipe Contreras [this message]
2021-07-16 18:12 ` Martin
2021-07-16 18:31 ` Martin
2021-07-16 18:56 ` Felipe Contreras
2021-07-17 7:02 ` Martin
[not found] ` <1997ca3b-117a-e19a-0dee-7342a2f1a0e7@mfriebe.de>
[not found] ` <60f1f4c3dd8b1_14cb208c1@natae.notmuch>
[not found] ` <fedbfe1f-9e6d-f46f-ca41-e176a30e938c@mfriebe.de>
[not found] ` <60f22aaa6a4f1_1f602081b@natae.notmuch>
2021-07-17 10:07 ` Martin
[not found] ` <60f33f8a7c39b_507220823@natae.notmuch>
2021-07-17 21:23 ` Martin
2021-07-19 17:51 ` Felipe Contreras
2021-07-11 7:57 ` Sergey Organov
2021-07-11 9:27 ` Martin
2021-07-11 9:37 ` Sergey Organov
2021-07-11 10:24 ` Martin
2021-07-12 16:34 ` Felipe Contreras
2021-07-10 22:13 ` Naming the --forec option [[Re: PATCH: improve git switch documentation]] Martin
2021-07-10 23:18 ` Felipe Contreras
2021-07-11 0:39 ` Martin
2021-07-12 16:15 ` Felipe Contreras
2021-07-10 10:24 ` PATCH: improve git switch documentation Sergey Organov
2021-07-10 10:37 ` Bagas Sanjaya
2021-07-10 11:05 ` Martin
2021-07-10 16:32 ` Sergey Organov
2021-07-10 20:12 ` Felipe Contreras
2021-07-11 9:04 ` Sergey Organov
2021-07-11 10:05 ` Martin
2021-07-11 12:23 ` Sergey Organov
2021-07-11 13:39 ` Martin
2021-07-11 14:49 ` Sergey Organov
2021-07-11 16:51 ` Sergey Organov
2021-07-12 10:31 ` Kerry, Richard
2021-07-12 11:11 ` Sergey Organov
2021-07-12 16:55 ` Felipe Contreras
2021-07-12 16:24 ` Felipe Contreras
2021-07-12 16:39 ` Martin
2021-07-12 17:09 ` Felipe Contreras
2021-07-12 22:58 ` Sergey Organov
2021-07-12 23:36 ` Felipe Contreras
2021-07-13 11:20 ` Martin
2021-07-10 20:00 ` Felipe Contreras
2021-07-10 19:51 ` Felipe Contreras
2021-07-11 9:52 ` Sergey Organov
2021-07-12 16:44 ` Felipe Contreras
2021-07-13 10:57 ` Sergey Organov
2021-07-13 16:10 ` Felipe Contreras
2021-07-14 19:14 ` Sergey Organov
2021-07-14 19:51 ` Felipe Contreras
2021-07-14 20:42 ` Sergey Organov
2021-07-08 3:12 ` What actually is a branch? Felipe Contreras
2021-07-08 11:16 ` Sergey Organov
2021-07-08 18:05 ` Felipe Contreras
2021-07-01 14:58 ` PATCH: improve git switch documentation Junio C Hamano
2021-07-01 17:29 ` Martin
2021-07-01 17:46 ` Sergey Organov
2021-07-07 18:54 ` Felipe Contreras
2021-07-07 18:47 ` Felipe Contreras
2021-07-07 18:14 ` Felipe Contreras
2021-07-01 0:06 ` Matt Rogers
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=60edb8ff814cf_ab6dd208d9@natae.notmuch \
--to=felipe.contreras@gmail.com \
--cc=git@mfriebe.de \
--cc=git@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).