git switch/restore, still experimental?

> the "git switch" and "git restore" commands were released two years
> ago, but the manpage still says "THIS COMMAND IS EXPERIMENTAL. THE
> BEHAVIOR MAY CHANGE.".
> 
> i'd love to use them, but this warning gives me pause, perhaps i
> should wait until it stops being experimental, i worry that it might
> change in behavior unexpectedly and cause problems for me.

>
> hi,
>
> the "git switch" and "git restore" commands were released two years
> ago, but the manpage still says "THIS COMMAND IS EXPERIMENTAL. THE
> BEHAVIOR MAY CHANGE.".
>
> i'd love to use them, but this warning gives me pause, perhaps i
> should wait until it stops being experimental, i worry that it might
> change in behavior unexpectedly and cause problems for me.
>
> considering that they were released two years ago, could the
> experimental-warning be removed now?
>
> thanks,
> gabor

> On Tue, May 4, 2021 at 3:36 AM Gábor Farkas <gabor.farkas@gmail.com> wrote:
> > the "git switch" and "git restore" commands were released two years
> > ago, but the manpage still says "THIS COMMAND IS EXPERIMENTAL. THE
> > BEHAVIOR MAY CHANGE.".
> >
> > considering that they were released two years ago, could the
> > experimental-warning be removed now?
>
> This probably makes sense.  The author of switch and restore isn't
> involved in the git project anymore.  He decided to work on other
> things, which was and is a big loss for us.  I think others (myself
> included) didn't know all the things that might have been in Duy's
> head that he wanted to verify were working well before marking this as
> good, but these two commands have generally been very well received
> and it has been a few years.  Personally, I'm not aware of anything
> that we'd need or want to change with these commands.

> On Tue, May 4, 2021 at 3:36 AM Gábor Farkas <gabor.farkas@gmail.com> wrote:
>>
>> hi,
>>
>> the "git switch" and "git restore" commands were released two years
>> ago, but the manpage still says "THIS COMMAND IS EXPERIMENTAL. THE
>> BEHAVIOR MAY CHANGE.".
>>
>> i'd love to use them, but this warning gives me pause, perhaps i
>> should wait until it stops being experimental, i worry that it might
>> change in behavior unexpectedly and cause problems for me.
>>
>> considering that they were released two years ago, could the
>> experimental-warning be removed now?
>>
>> thanks,
>> gabor
>
> This probably makes sense.  The author of switch and restore isn't
> involved in the git project anymore.  He decided to work on other
> things, which was and is a big loss for us.  I think others (myself
> included) didn't know all the things that might have been in Duy's
> head that he wanted to verify were working well before marking this as
> good, but these two commands have generally been very well received
> and it has been a few years.  Personally, I'm not aware of anything
> that we'd need or want to change with these commands.

> In summary, I think it should be changed to act like this:
>     
>     |---------------------------+------------------------+---------------------------|
>     | What                      | Now                    | New                       |
>     |---------------------------+------------------------+---------------------------|
>     | Switch                    | git switch existing    | git switch existing       |
>     | Error                     | git switch nonexisting | <no change (errors)>      |
>     | Switch with --merge       | git switch -m branch   | git switch --merge branch |
>     | Create                    | git switch -c new      | git switch -n new         |
>     | Create from existing      | N/A                    | git switch -c new [<old>] |
>     | Move & switch to existing | N/A                    | git switch -m new [<old>] |
>     |---------------------------+------------------------+---------------------------|

> Ævar Arnfjörð Bjarmason wrote:
>> In summary, I think it should be changed to act like this:
>>     
>>     |---------------------------+------------------------+---------------------------|
>>     | What | Now | New |
>>     |---------------------------+------------------------+---------------------------|
>>     | Switch | git switch existing | git switch existing |
>>     | Error | git switch nonexisting | <no change (errors)> |
>>     | Switch with --merge | git switch -m branch | git switch
>>     | --merge branch |
>>     | Create | git switch -c new | git switch -n new |
>>     | Create from existing | N/A | git switch -c new [<old>] |
>>     | Move & switch to existing | N/A | git switch -m new [<old>] |
>>     |---------------------------+------------------------+---------------------------|
>
> I'm in favor of this too.
>
>> In its current state I find "git switch" to be unusable. That sounds
>> like dramatic hyperbole, but I'm serious.
>
> I concur.
>
> I've tried to use it multiple times, and I always come back to using git
> branch / git checkout.

> On Tue, May 04 2021, Elijah Newren wrote:
>
>> On Tue, May 4, 2021 at 3:36 AM Gábor Farkas <gabor.farkas@gmail.com> wrote:
>>>
>>> hi,
>>>
>>> the "git switch" and "git restore" commands were released two years
>>> ago, but the manpage still says "THIS COMMAND IS EXPERIMENTAL. THE
>>> BEHAVIOR MAY CHANGE.".
>>>
>>> i'd love to use them, but this warning gives me pause, perhaps i
>>> should wait until it stops being experimental, i worry that it might
>>> change in behavior unexpectedly and cause problems for me.
>>>
>>> considering that they were released two years ago, could the
>>> experimental-warning be removed now?
>>>
>>> thanks,
>>> gabor
>>
>> This probably makes sense.  The author of switch and restore isn't
>> involved in the git project anymore.  He decided to work on other
>> things, which was and is a big loss for us.  I think others (myself
>> included) didn't know all the things that might have been in Duy's
>> head that he wanted to verify were working well before marking this as
>> good, but these two commands have generally been very well received
>> and it has been a few years.  Personally, I'm not aware of anything
>> that we'd need or want to change with these commands.
>
> I am.
>

> And:
>
>    # Moves a branch (or -M for --force)
>    git branch -m old new
>
> That last one we can't have either because "switch" squats on "-m" for
> "--merge", which I daresay is a much more obscure use-case not deserving
> of a short option than "rename and switch to".

> Sergey Organov <sorganov@gmail.com> writes:
>
>> Isn't --merge a different (and inferior) way to achieve what we already
>> have elsewhere with --autostash? Does it make sense to get rid of --merge
>> here in favor of --autostash?
>
> Not really.

> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>
>> On Tue, May 04 2021, Elijah Newren wrote:
>>
>>> On Tue, May 4, 2021 at 3:36 AM Gábor Farkas <gabor.farkas@gmail.com> wrote:
>>>>
>>>> hi,
>>>>
>>>> the "git switch" and "git restore" commands were released two years
>>>> ago, but the manpage still says "THIS COMMAND IS EXPERIMENTAL. THE
>>>> BEHAVIOR MAY CHANGE.".
>>>>
>>>> i'd love to use them, but this warning gives me pause, perhaps i
>>>> should wait until it stops being experimental, i worry that it might
>>>> change in behavior unexpectedly and cause problems for me.
>>>>
>>>> considering that they were released two years ago, could the
>>>> experimental-warning be removed now?
>>>>
>>>> thanks,
>>>> gabor
>>>
>>> This probably makes sense.  The author of switch and restore isn't
>>> involved in the git project anymore.  He decided to work on other
>>> things, which was and is a big loss for us.  I think others (myself
>>> included) didn't know all the things that might have been in Duy's
>>> head that he wanted to verify were working well before marking this as
>>> good, but these two commands have generally been very well received
>>> and it has been a few years.  Personally, I'm not aware of anything
>>> that we'd need or want to change with these commands.
>>
>> I am.
>>
>
> [...]
>
>> And:
>>
>>    # Moves a branch (or -M for --force)
>>    git branch -m old new
>>
>> That last one we can't have either because "switch" squats on "-m" for
>> "--merge", which I daresay is a much more obscure use-case not deserving
>> of a short option than "rename and switch to".
>
> Isn't --merge a different (and inferior) way to achieve what we already
> have elsewhere with --autostash? Does it make sense to get rid of --merge
> here in favor of --autostash?

> On Wed, May 05 2021, Sergey Organov wrote:
>
>> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>>
>>> On Tue, May 04 2021, Elijah Newren wrote:
>>>
>>>> On Tue, May 4, 2021 at 3:36 AM Gábor Farkas <gabor.farkas@gmail.com> wrote:
>>>>>
>>>>> hi,
>>>>>
>>>>> the "git switch" and "git restore" commands were released two years
>>>>> ago, but the manpage still says "THIS COMMAND IS EXPERIMENTAL. THE
>>>>> BEHAVIOR MAY CHANGE.".
>>>>>
>>>>> i'd love to use them, but this warning gives me pause, perhaps i
>>>>> should wait until it stops being experimental, i worry that it might
>>>>> change in behavior unexpectedly and cause problems for me.
>>>>>
>>>>> considering that they were released two years ago, could the
>>>>> experimental-warning be removed now?
>>>>>
>>>>> thanks,
>>>>> gabor
>>>>
>>>> This probably makes sense.  The author of switch and restore isn't
>>>> involved in the git project anymore.  He decided to work on other
>>>> things, which was and is a big loss for us.  I think others (myself
>>>> included) didn't know all the things that might have been in Duy's
>>>> head that he wanted to verify were working well before marking this as
>>>> good, but these two commands have generally been very well received
>>>> and it has been a few years.  Personally, I'm not aware of anything
>>>> that we'd need or want to change with these commands.
>>>
>>> I am.
>>>
>>
>> [...]
>>
>>> And:
>>>
>>>    # Moves a branch (or -M for --force)
>>>    git branch -m old new
>>>
>>> That last one we can't have either because "switch" squats on "-m" for
>>> "--merge", which I daresay is a much more obscure use-case not deserving
>>> of a short option than "rename and switch to".
>>
>> Isn't --merge a different (and inferior) way to achieve what we already
>> have elsewhere with --autostash? Does it make sense to get rid of --merge
>> here in favor of --autostash?
>
> Probably, I haven't used the --merge option ever I think. Switching with
> dirty worktrees isn't really how I work.
>
> But to the extent that I've ever tried / run into errors with that I'd
> think that an option like --merge or --autostash is mostly a result of
> us being overzealous about "is_dirty() && die()" checks. E.g. rebase (at
> least a while ago, still) would refuse to rebase with a dirty tree, even
> though the path in question had nothing to do with paths that would be
> touched by the rebase.

> I mean, I see why. You don't want a typo of "master" as "maaster" to
> create a new "maaster" branch, so really that's out. But it really
> should be:
>
>     # -n or -N for --new / --new --force (the latter just in case of a
>     # race, and just for consistency)
>     git switch -n doesnotexist

> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>
>> I mean, I see why. You don't want a typo of "master" as "maaster" to
>> create a new "maaster" branch, so really that's out. But it really
>> should be:
>>
>>     # -n or -N for --new / --new --force (the latter just in case of a
>>     # race, and just for consistency)
>>     git switch -n doesnotexist
>
> I do not see why --new is better than --create; we did choose not to
> reuse --branch from "checkout" and I remember that was a deliberate
> decision (i.e. once split into "switch" and "restore", "switch"
> becomes only about branches, so unlike in the context of "checkout",
> in the context of "switch", the word "branch" adds a lot less value,
> and certainly does not signal we are creating a branch and switching
> to it).

>> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>>
>>> I mean, I see why. You don't want a typo of "master" as "maaster" to
>>> create a new "maaster" branch, so really that's out. But it really
>>> should be:
>>>
>>>     # -n or -N for --new / --new --force (the latter just in case of a
>>>     # race, and just for consistency)
>>>     git switch -n doesnotexist
>>
>> I do not see why --new is better than --create; we did choose not to
>> reuse --branch from "checkout" and I remember that was a deliberate
>> decision (i.e. once split into "switch" and "restore", "switch"
>> becomes only about branches, so unlike in the context of "checkout",
>> in the context of "switch", the word "branch" adds a lot less value,
>> and certainly does not signal we are creating a branch and switching
>> to it).
>
> I don't think --new is better than --create when considered in
> isolation. I happen to think --create is better.
>
> What I'm arguing is that we should be aiming for some consistency in the
> command-set. In this case the relatively small change of
> s/--create/--new/ server so make the rest consistent. I.e. the branch
> and switch commands can mirror each other in the ways that matter for
> these common operations of create/copy/move.
>
>> It would have been a stronger argument to favor --new if we had "git
>> branch --new <branchname>", but that is not the case.
>
> The argument is that switch's experimental design squats on 2x other
> options, so changing -c to -n so we can make -c and -m do the same thing
> is better.

>>> It would have been a stronger argument to favor --new if we had "git
>>> branch --new <branchname>", but that is not the case.
>>
>> The argument is that switch's experimental design squats on 2x other
>> options, so changing -c to -n so we can make -c and -m do the same thing
>> is better.
>
> Whatever the merit of the argument I'm putting forward here, it would be
> useful to get some idea of whether you'd be categorically opposed to
> changing the interface of switch/restore in breaking ways even though
> they've been marked as "THIS COMMAND IS EXPERIMENTAL".
>
> Of course any series to implement what I suggested in
> <877dkdwgfe.fsf@evledraar.gmail.com> would need to stand on its own
> merits.
>
> I'm not planning on working on that since I expect the response will be
> at best "neat, but that ship has sailed", but if that's not the case...

>>Which leaves us with two hard choices regarding switch/restore, none of them
>>really being comfortable:
>>
>>- we scrap switch/restore because their usability is not really all that
>>  improved relative to `git checkout`.
>
> Please do not do that. Switch/restore is much easier to understand
> for new users. The semantics are also more consistent with what
> others have done with git over the years anyway (EGit as an
> example). I have users who have transitioned because the commands
> make sense. They have not hit any missing bits in their workflows.
>
>>- we leave switch/restore as-are (because by now, changing the options or
>>  the design would be almost certainly disruptive to users who already
>>  tried to adopt the new commands, I being one of those users).
>
> I think we should work on the commands to cover between them
> (well... and reset) to functionally cover what checkout
> does. Leaving them as-is, I think is not a viable option. People
> do know these are experimental and not to use in scripts - we can
> hope anyway.

> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> 
> > I mean, I see why. You don't want a typo of "master" as "maaster" to
> > create a new "maaster" branch, so really that's out. But it really
> > should be:
> >
> >     # -n or -N for --new / --new --force (the latter just in case of a
> >     # race, and just for consistency)
> >     git switch -n doesnotexist
> 
> I do not see why --new is better than --create;

> Junio C Hamano wrote:
>> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>> 
>> > I mean, I see why. You don't want a typo of "master" as "maaster" to
>> > create a new "maaster" branch, so really that's out. But it really
>> > should be:
>> >
>> >     # -n or -N for --new / --new --force (the latter just in case of a
>> >     # race, and just for consistency)
>> >     git switch -n doesnotexist
>> 
>> I do not see why --new is better than --create;
>
> I do. Different languages equal different minds.
>
> New in this context is an adjetive: it is a modifier of a noun, in this
> case, a branch.
>
> Create is a verb; it's an action.
>
> Linguistically speaking they could not be more different.
>
>
> You don't do two verbs at a time. Either you sleep, or you eat, but you
> don't do both. Similarly you don't switch and create. Doesn't make
> sense.
>
> If you use natural language:
>
>   1. Git, switch to a new branch
>
>   2. Git, switch, create, branch
>
> One of these simply flows, the other is complete gibberish. I think
> anyone familiar with English can identify which is which.

> > If you use natural language:
> >
> >   1. Git, switch to a new branch
> >
> >   2. Git, switch, create, branch
> >
> > One of these simply flows, the other is complete gibberish. I think
> > anyone familiar with English can identify which is which.
> 
> Well, there's "Git, create a new branch and switch to it"

> In any case, unless we're talking about rewamping git's entire command
> set (e.g. having a git-newtree or whatever) I'd like to think that it's
> more productive to focus on making the commands/switches we have
> internally consistent when possible, which is what I'm advocating in the
> E-Mail that started this sub-thread.

>> > If you use natural language:
>> >
>> >   1. Git, switch to a new branch
>> >
>> >   2. Git, switch, create, branch
>> >
>> > One of these simply flows, the other is complete gibberish. I think
>> > anyone familiar with English can identify which is which.
>> 
>> Well, there's "Git, create a new branch and switch to it"
>
> Which command is that?
>
>   git create branch --checkout?
>
> I'm following the order of the words from left to right.

>> Also, there's the verb "make" in common use in git's command set
>> e.g. git-mktag, git-mktree, as well as mkdir(1), mkfifo(1) etc.
>
> Sure, although I wouldn't consider them main commands. I for one never
> use them.
>
>> In any case, unless we're talking about rewamping git's entire command
>> set (e.g. having a git-newtree or whatever) I'd like to think that it's
>> more productive to focus on making the commands/switches we have
>> internally consistent when possible, which is what I'm advocating in the
>> E-Mail that started this sub-thread.
>
> But we are talking about a new command, it is precisely at this point we
> need to think about what could have been if mistakes of the past had not
> happened.
>
> We should not repeat past mistakes without a very good reason.
>
> I don't think we should seek consistency for consistency's sake. Sure,
> consistency is good, but it's only one of many considerations.
>
> In this case however we have a rare occasion in which both consistency and
> natural language meet, we should not squander it.
>
> In fact, to be even more consistent we could add a -n option to git
> branch, which would be reduntant but more explicit, like --list.

> On Thu, May 06 2021, Felipe Contreras wrote:
> 
> First of all, I think we're in rather violent agreement about the real
> matter at hand here, and are at best talking about the design of the
> keychain for the bikeshed...

> > Which command is that?
> >
> >   git create branch --checkout?
> >
> > I'm following the order of the words from left to right.
> 
> I'm just pointing out that git in general and certainly not the *nix
> tradition it follows tries to make commands readable in anything like
> English sentence order. If you attempt to read "log", "status", "rebase"
> etc. commands like that you'll at best end up sounding somewhat like
> Yoda.

> > In this case however we have a rare occasion in which both consistency and
> > natural language meet, we should not squander it.
> >
> > In fact, to be even more consistent we could add a -n option to git
> > branch, which would be reduntant but more explicit, like --list.
> 
> Indeed, I agree with all of that. I.e. we should move to "switch" to
> "-n" instead of "-c" etc., and add a "-n" to "branch" for
> consistency. After all that's my upthread proposal...
> 
> I just don't think it's worth trying to make the argv readable as a
> sentence, even if we had no backwards compatibility to worry about.

> On Tue, May 4, 2021 at 3:36 AM Gábor Farkas <gabor.farkas@gmail.com> wrote:
> >
> > the "git switch" and "git restore" commands were released two years
> > ago, but the manpage still says "THIS COMMAND IS EXPERIMENTAL. THE
> > BEHAVIOR MAY CHANGE.".
> >
> > i'd love to use them, but this warning gives me pause, perhaps i
> > should wait until it stops being experimental, i worry that it might
> > change in behavior unexpectedly and cause problems for me.
> >
> > considering that they were released two years ago, could the
> > experimental-warning be removed now?
>
> This probably makes sense.  The author of switch and restore isn't
> involved in the git project anymore.  He decided to work on other
> things, which was and is a big loss for us.  I think others (myself
> included) didn't know all the things that might have been in Duy's
> head that he wanted to verify were working well before marking this as
> good, but these two commands have generally been very well received
> and it has been a few years.  Personally, I'm not aware of anything
> that we'd need or want to change with these commands.

> That said, we're only a few weeks from -rc0, and I'd rather remove the
> experimental label early in a release cycle, so maybe this would be a
> good thing to do after the June git-2.32 release.  That'd give plenty
> of time for others to chime in with anything they might be aware of
> that they want or need fixed.
>
> Thanks for flagging this.
>
> Elijah
>

>On Tue, 4 May 2021, Elijah Newren wrote:
>> On Tue, May 4, 2021 at 3:36 AM Gábor Farkas <gabor.farkas@gmail.com>
>wrote:
>> >
>> > the "git switch" and "git restore" commands were released two years
>> > ago, but the manpage still says "THIS COMMAND IS EXPERIMENTAL. THE
>> > BEHAVIOR MAY CHANGE.".
>> >
>> > i'd love to use them, but this warning gives me pause, perhaps i
>> > should wait until it stops being experimental, i worry that it might
>> > change in behavior unexpectedly and cause problems for me.
>> >
>> > considering that they were released two years ago, could the
>> > experimental-warning be removed now?
>>
>> This probably makes sense.  The author of switch and restore isn't
>> involved in the git project anymore.  He decided to work on other
>> things, which was and is a big loss for us.  I think others (myself
>> included) didn't know all the things that might have been in Duy's
>> head that he wanted to verify were working well before marking this as
>> good, but these two commands have generally been very well received
>> and it has been a few years.  Personally, I'm not aware of anything
>> that we'd need or want to change with these commands.
>
>I think that part of the intention to mark this as experimental was to gather
>feedback about the commands. After all, the goal was to improve the user
>experience of Git (because `git checkout` does too many things, and its major
>accomplishment is to confuse literally every single new Git user).
>
>However, that hope never was fulfilled if I may say so, we simply did not attract
>the best-suited experts to this mailing list, not if what we set out was to improve
>usability.
>
>Which leaves us with two hard choices regarding switch/restore, none of them
>really being comfortable:
>
>- we scrap switch/restore because their usability is not really all that
>  improved relative to `git checkout`.

>I say that neither of them is a really splendid choice because the original goal is
>not only not accomplished, but I would say it is even harder now than it was
>when we accepted switch/restore into an official release, because of that
>experience with switch/restore. We simply do not have the right expertise on
>this list, and therefore anything we do will always have that "UX designed by an
>engineer" feel.

>>Which leaves us with two hard choices regarding switch/restore, none of them
>>really being comfortable:
>>
>>- we scrap switch/restore because their usability is not really all that
>>  improved relative to `git checkout`.
>
> Please do not do that. Switch/restore is much easier to understand
> for new users. The semantics are also more consistent with what
> others have done with git over the years anyway (EGit as an
> example). I have users who have transitioned because the commands
> make sense. They have not hit any missing bits in their workflows.
>
>>- we leave switch/restore as-are (because by now, changing the options or
>>  the design would be almost certainly disruptive to users who already
>>  tried to adopt the new commands, I being one of those users).
>
> I think we should work on the commands to cover between them
> (well... and reset) to functionally cover what checkout
> does. Leaving them as-is, I think is not a viable option. People
> do know these are experimental and not to use in scripts - we can
> hope anyway.

> Which leaves us with two hard choices regarding switch/restore, none of
> them really being comfortable:
> 
> - we scrap switch/restore because their usability is not really all that
>   improved relative to `git checkout`.
> 
> - we leave switch/restore as-are (because by now, changing the options or
>   the design would be almost certainly disruptive to users who already
>   tried to adopt the new commands, I being one of those users).

> I say that neither of them is a really splendid choice because the
> original goal is not only not accomplished, but I would say it is even
> harder now than it was when we accepted switch/restore into an official
> release, because of that experience with switch/restore. We simply do not
> have the right expertise on this list, and therefore anything we do will
> always have that "UX designed by an engineer" feel.