Re: PATCH: improve git switch documentation

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: Jul 10, 2021, 23:35 UTC
Message-ID: <60ea2eb562f26_2a69208e8@natae.notmuch>
In-Reply-To: <30e4c874-6b87-b03d-fa33-fde5b7e50b2a@mfriebe.de>

Martin wrote:

Show 41 quoted lines

> On 10/07/2021 22:49, Felipe Contreras wrote:
> > Martin wrote:
> >>   From the docs (and similar on git checkout)
> >>> --force
> >>>
> >>>      An alias for --discard-changes.
> >>> --discard-changes
> >>>
> >>>      Proceed even if the index or the working tree differs from HEAD.
> >>> Both the index and working tree are restored to match the switching
> >>> target. If --recurse-submodules is specified, submodule content is
> >>> also restored to match the switching target. This is used to throw
> >>> away local changes.
> ....
> 
> >> If the working tree is made to match the target, then it can not retain
> >> local changes. That can be concluded.
> >> Yet, it is explicitly mentioned.
> >>
> >> Does it really hurt to mention it?
> > 
> > Yes it does.
> > 
> > Time is the most precious resource we all have. We should not waste the
> > most precious resource of our readers.
> > 
> >    Throw away local changes.
> > 
> > That does a much better job.
> > 
> > If you want to be more explicit, you can add a bit more information:
> > 
> >    Throw away local changes either in the staging area or the working
> >    tree.
> > 
> > Why does the user have to know what HEAD is? And why does it matter that
> > the staging area is held in a file called "index"?
> > 
> > The current explanation is just bad.
> 
> Time is precious, but to really save on it, you have to invest some of it.

Sure.

Show 12 quoted lines

> About the HEAD/index stuff => that was not at all related to the point I 
> was making.
> But I agree that bit can be shortened
> 
> The thing that I was pointing out, is the last sentence only.
>  >    This is used to throw away local changes.
> 
> But even that can be reduced to your proposal
>  >    Throw away local changes.
> 
> It still supports my point. It does state explicitly that data is (or 
> can be) thrown away.

OK, yeah, it does state explicitly that data is thrown away, but it's the *last* sentence, when it should be the first, and everything else is redundant.

Show 12 quoted lines

> Now, if that can be stated on this option, then all I ask is to add a 
> similar statement (as short as possible) to "-C".
> It should indicate that *commit* may be *dropped".
> Find a better word for dropped: lost, unreachable, removed.....
> 
> Currently only the branch is mentioned.
> Currently nothing does explicitly say that *commits* can be affected.
> 
> 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:

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

I don't know how is that unclear in any way.

Show 9 quoted lines

> > There's only one person you need to convince.
> > 
> > So, what I suggest you to do is take into consideration all we have
> > discussed and send another patch, because that's ultimately all that
> > matters. Moreover, it usually happens to me that while I write the patch
> > is when finally the previously-discussed ideas start to click.
> 
> Well, I will see to make some time and put something together.
> Might be a bit before I get to it, but that gives some time to think about.

Take your time. One of the good things about open source is that there's no rush.

Cheers.

-- 
Felipe Contreras