[PATCH] Revert "Declare both git-switch and git-restore experimental"

[PATCH] Revert "Declare both git-switch and git-restore experimental"

[Matthieu Baerts (NGI0)]

This reverts commit 4e43b7ff1ea4b6f16b93a432b6718e9ab38749bd.

Recently, I wanted to recommend the use of git-switch and git-restore
instead of git-checkout in new documentation pages. But then, I found
out that these two commands were still marked as experimental in the
documentation. git-switch and git-restore have been marked as such since
their introduction, in version 2.23.

That was for good reasons, according to the reverted commit:

> These two commands are basically redesigned git-checkout. We will not
> have that many opportunities to redo (because we run out of verbs, and
> that would also increase maintenance cost).

The reverted commit also mentions this:

> To play it safe, let's declare the two commands experimental in one or
> two releases. If there is a serious flaw in the UI, we could still fix
> it. If everything goes well and nobody complains loudly, we can remove
> the experimental status by reverting this patch.

Version 2.44 is approaching, almost 5 years after the introduction of
these two commands, it then looks safe to remove this experimental
status.

Signed-off-by: Matthieu Baerts (NGI0) <matttbe@kernel.org>
---

Notes:
    Here is a simple 'git revert', as suggested in 4e43b7ff1e ("Declare both
    git-switch and git-restore experimental"), without any conflicts to
    resolve.
    
    BTW, thank you very much for maintaining and still improving this great
    tool!

 Documentation/git-restore.txt | 2 --
 Documentation/git-switch.txt  | 2 --
 2 files changed, 4 deletions(-)

diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt
index 975825b44a..4f5531c440 100644
--- a/Documentation/git-restore.txt
+++ b/Documentation/git-restore.txt
@@ -28,8 +28,6 @@ otherwise from the index. Use `--source` to restore from a different commit.
 See "Reset, restore and revert" in linkgit:git[1] for the differences
 between the three commands.
 
-THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.
-
 OPTIONS
 -------
 -s <tree>::
diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt
index f38e4c8afa..96cfd9ba52 100644
--- a/Documentation/git-switch.txt
+++ b/Documentation/git-switch.txt
@@ -29,8 +29,6 @@ Switching branches does not require a clean index and working tree
 however if the operation leads to loss of local changes, unless told
 otherwise with `--discard-changes` or `--merge`.
 
-THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.
-
 OPTIONS
 -------
 <branch>::
-- 
2.43.0

Re: [PATCH] Revert "Declare both git-switch and git-restore experimental"

[Kristoffer Haugsbakk]

On Tue, Feb 20, 2024, at 10:29, Matthieu Baerts (NGI0) wrote:
> This reverts commit 4e43b7ff1ea4b6f16b93a432b6718e9ab38749bd.
> Version 2.44 is approaching, almost 5 years after the introduction of
> these two commands, it then looks safe to remove this experimental
> status.

Is this only based on the amount of time passed? Has there been any
relevant discussions on the mailing list that discuss how mature these
commands are and if they should be changed (with presumably a “no” to
the question about being changed)?

-- 
Kristoffer Haugsbakk

Re: [PATCH] Revert "Declare both git-switch and git-restore experimental"

[Matthieu Baerts]

Hi Kristoffer,

Thank you for your comment.

On 20/02/2024 10:36, Kristoffer Haugsbakk wrote:
> On Tue, Feb 20, 2024, at 10:29, Matthieu Baerts (NGI0) wrote:
>> This reverts commit 4e43b7ff1ea4b6f16b93a432b6718e9ab38749bd.
>> Version 2.44 is approaching, almost 5 years after the introduction of
>> these two commands, it then looks safe to remove this experimental
>> status.
> 
> Is this only based on the amount of time passed? Has there been any
> relevant discussions on the mailing list that discuss how mature these
> commands are and if they should be changed (with presumably a “no” to
> the question about being changed)?

It is only based on the amount of time passed, indeed.

I initially wanted to start a discussion on the mailing list: "is it
normal these commands are still marked as experimental?". Then I saw the
patch introducing this status, which was suggesting doing a revert in
version 2.24 or 2.25. That's why I sent this, to start the discussions
with a patch that is ready to apply. Is it not OK to do that here?

Also, when I quickly looked at the history, I didn't see any behaviour
changes since their introduction. Maybe there was a minor change with
commit 088018e34d ("restore: default to HEAD when combining --staged and
--worktree"), but it looks more like a fix than a behaviour change.

Cheers,
Matt
-- 
Sponsored by the NGI0 Core fund.

Re: [PATCH] Revert "Declare both git-switch and git-restore experimental"

[Kristoffer Haugsbakk]

On Tue, Feb 20, 2024, at 10:58, Matthieu Baerts wrote:
> Hi Kristoffer,
>
> Thank you for your comment.
>
> On 20/02/2024 10:36, Kristoffer Haugsbakk wrote:
>> On Tue, Feb 20, 2024, at 10:29, Matthieu Baerts (NGI0) wrote:
>>> This reverts commit 4e43b7ff1ea4b6f16b93a432b6718e9ab38749bd.
>>> Version 2.44 is approaching, almost 5 years after the introduction of
>>> these two commands, it then looks safe to remove this experimental
>>> status.
>>
>> Is this only based on the amount of time passed? Has there been any
>> relevant discussions on the mailing list that discuss how mature these
>> commands are and if they should be changed (with presumably a “no” to
>> the question about being changed)?
>
> It is only based on the amount of time passed, indeed.
>
> I initially wanted to start a discussion on the mailing list: "is it
> normal these commands are still marked as experimental?". Then I saw the
> patch introducing this status, which was suggesting doing a revert in
> version 2.24 or 2.25. That's why I sent this, to start the discussions
> with a patch that is ready to apply. Is it not OK to do that here?
>
> Also, when I quickly looked at the history, I didn't see any behaviour
> changes since their introduction. Maybe there was a minor change with
> commit 088018e34d ("restore: default to HEAD when combining --staged and
> --worktree"), but it looks more like a fix than a behaviour change.

All good reasons.

The only reason why I ask is because I was vaguely aware of some
discussions (don’t know how long ago) where someone was skeptical about
changing one of the two experimental commands, and then someone else in
turn expressed some frustration about this concern since they are after
all marked experimental. And the context was some UI/UX problems with
the command.

But we’ll see.

-- 
Kristoffer Haugsbakk

Re: [PATCH] Revert "Declare both git-switch and git-restore experimental"

[Junio C Hamano]

"Kristoffer Haugsbakk" <code@khaugsbakk.name> writes:

> The only reason why I ask is because I was vaguely aware of some
> discussions (don’t know how long ago) where someone was skeptical about
> changing one of the two experimental commands, and then someone else in
> turn expressed some frustration about this concern since they are after
> all marked experimental. And the context was some UI/UX problems with
> the command.

There was a discussion to further make "switch" deviate from
"checkout" by taking advantage of its experimental status [*1*], for
example.

Being marked as "EXPERIMENTAL" allows us to redefine the behaviour
in a way that would break existing users, like changing what the
"-c" option means completely (so that folks who are used to say
"switch -c blah" will be surprised next time they type that command,
but they cannot complain).  Once you remove the label, you no longer
have such a freedom to even imagine departing from the existing
behaviour (I wrote essentially the same thing before [*2*]).  Are we
ready to paint us into such a corner yet?  Is "switch/restore" perfect
and do not need departing changes anymore?


[References]

*1* https://lore.kernel.org/git/211021.86wnm6l1ip.gmgdl@evledraar.gmail.com/
*2* https://lore.kernel.org/git/xmqqzg6eocmi.fsf@gitster.g/

Re: [PATCH] Revert "Declare both git-switch and git-restore experimental"

[Matthieu Baerts]

Hi Junio,

Thank you for your reply!

On 20/02/2024 7:04 pm, Junio C Hamano wrote:
> "Kristoffer Haugsbakk" <code@khaugsbakk.name> writes:
> 
>> The only reason why I ask is because I was vaguely aware of some
>> discussions (don’t know how long ago) where someone was skeptical about
>> changing one of the two experimental commands, and then someone else in
>> turn expressed some frustration about this concern since they are after
>> all marked experimental. And the context was some UI/UX problems with
>> the command.
> 
> There was a discussion to further make "switch" deviate from
> "checkout" by taking advantage of its experimental status [*1*], for
> example.

I appreciate the references, thank you! It is interesting to note
changes have been proposed a few years ago, but none have been applied.

> Being marked as "EXPERIMENTAL" allows us to redefine the behaviour
> in a way that would break existing users, like changing what the
> "-c" option means completely (so that folks who are used to say
> "switch -c blah" will be surprised next time they type that command,
> but they cannot complain).

Personally, I think I would complain, and go back to git-checkout :-)

> Once you remove the label, you no longer
> have such a freedom to even imagine departing from the existing
> behaviour (I wrote essentially the same thing before [*2*]).  Are we
> ready to paint us into such a corner yet?

I'm not involved in this project, but I think after a few versions /
years, it is hard to still keep this experimental status. I understand
it is tempting to keep it, but I think it is now too late. Despite the
now old label, you probably already no longer have such freedom to
radically change their behaviours, no?

> Is "switch/restore" perfect
> and do not need departing changes anymore?
To me, they don't need departing changes. If they are still experimental
after 5 years, it is hard to recommend them :)

Cheers,
Matt
-- 
Sponsored by the NGI0 Core fund.

Re: [PATCH] Revert "Declare both git-switch and git-restore experimental"

[Martin]

On 20/02/2024 19:04, Junio C Hamano wrote:

> [References]
> 
> *1* https://lore.kernel.org/git/211021.86wnm6l1ip.gmgdl@evledraar.gmail.com/
> *2* https://lore.kernel.org/git/xmqqzg6eocmi.fsf@gitster.g/
> 

 From 2
> I think the "switch" was written exactly for such a transition so that folks who
> wanted a different behaviour do not have to break existing users of "checkout".

Yet then the table in link 1 suggests to re-use -c and -m in the old 
style, the way the currently are used in "git branch"

"Introducing a new behaviour" is exactly not having to copy old meanings 
of options...

As I wrote
> The flaw here is in "git branch" which by default list branches, but if give a name (and no option to specify an action) "git branch foo" will change its action to "create". 

If "git branche" actually had needed an option to change its action to 
create, what would it have been? --create or -c ?

And -n (as suggested in the table) is strongly associated with dry-run. 
(not only in git)


If I look at the suggestion to replace -m by --merge, just so that -m 
can be "move", then I seriously ask, what happens more often:
- Someone switching to a branch while having modifications in their 
worktree (needing to merge)
- Someone creating a new branch, wanting to copy reflog/options

Given not only that switching to a new branch happens more often than 
creating one (and thereby makes it alt least plausible, that the -m as 
"merge" is required more often)..., but also that "git switch" is more 
about switching than creating branches..., I believe that -m as "merge" 
is entirely the better choice.

For the "git branch" features, if "git switch" should support them, they 
could easily be made available as
--cc  create and copy
--mv  move

They - by all likelihood - are used less often, and should be the long 
options. And a 2 letter long option is still easy to use.

Re: [PATCH] Revert "Declare both git-switch and git-restore experimental"

[Martin]

On 20/02/2024 10:36, Kristoffer Haugsbakk wrote:
> On Tue, Feb 20, 2024, at 10:29, Matthieu Baerts (NGI0) wrote:
>> This reverts commit 4e43b7ff1ea4b6f16b93a432b6718e9ab38749bd.
>> Version 2.44 is approaching, almost 5 years after the introduction of
>> these two commands, it then looks safe to remove this experimental
>> status.
> Is this only based on the amount of time passed? Has there been any
> relevant discussions on the mailing list that discuss how mature these
> commands are and if they should be changed (with presumably a “no” to
> the question about being changed)?
>

Isn't the absence over such a long time of such a discussion in itself a 
statement?
If there had been need for a discussion, would it not have happened by now?
Unless, it is assumed that no one is using it, nor has wanted to use it 
(but has been deterred by the experimental state).
Has *every* other additions always had a "relevant" discussion, or would 
feature in the past have been accepted if no one objected?


Furthermore, if something is functional (I am using it, I can attest it 
works), and if it had no breaking changes over a very long time, then 
making/keeping it experimental forever => would that not create a "boy 
who cried wolf" effect? More and more people will use it. If it gets 
incompatible broken the outcry will be there. And the documentation as 
experimental will not lessen that outcry.


On the other hand I have been part of one discussion touching that topic 
=> However this wasn't about: should switch/restore exist at all. It was 
about if individual options to those commands had been assigned the 
optimal choice of letter. In that case "-c" for "create", which for 
users of "git branch" is associated with "copy".

If that is the case, it would be enough to move the experimental to 
those particular options. And have discussions on those options, rather 
than the overall existence/naming of switch/restore?


About the "-c":  create vs copy:
> The |-c| and |-C| options have the exact same semantics as |-m| and 
> |-M|, except instead of the branch being renamed, it will be copied to 
> a new name, along with its config and reflog.
"copy" is basically creating a new branch "to a new name" with a copy of 
certain metadata (config, reflog).
The flaw here is in "git branch" which by default list branches, but if 
give a name (and no option to specify an action) "git branch foo" will 
change its action to "create".

Anyway, the discussion on "-c" for copy in "switch" is only relevant if 
there had been a discussion if this is across all git users a common 
enough action, so it requires a shortcut outside of "git branch". And if 
it does, and given that copy can't be done without creation, then should 
"copy" not be an option that in "git switch" should be given together 
with "create"? e.g. git switch -c newname -X oldbranch  
[commit-startpoint]" where X is the option that says "copy metadata 
from" (if it wasn't the worst idea ever, a 2nd "-c" would come to mind. 
-a "assign" -o "Origin" -r "reflog" -s "source" -w "with" ... though 
many of them may have potential to conflict too.

Re: [PATCH] Revert "Declare both git-switch and git-restore experimental"

[Kristoffer Haugsbakk]

On Tue, Feb 20, 2024, at 14:32, Martin wrote:
> On 20/02/2024 10:36, Kristoffer Haugsbakk wrote:
>> On Tue, Feb 20, 2024, at 10:29, Matthieu Baerts (NGI0) wrote:
>>
>>> This reverts commit 4e43b7ff1ea4b6f16b93a432b6718e9ab38749bd.
>>> Version 2.44 is approaching, almost 5 years after the introduction of
>>> these two commands, it then looks safe to remove this experimental
>>> status.
>>>
>> Is this only based on the amount of time passed? Has there been any
>> relevant discussions on the mailing list that discuss how mature these
>> commands are and if they should be changed (with presumably a “no” to
>> the question about being changed)?
>>
>>
>
> Isn't the absence over such a long time of such a discussion in itself a statement?
> If there had been need for a discussion, would it not have happened by now?

I don’t know if there has been an absence of it. That’s why I asked.

-- 
Kristoffer Haugsbakk