patchRevert "Declare both git-switch and git-restore experimental"

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:

The reverted commit also mentions this:

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(-)

On Tue, Feb 20, 2024, at 10:29, Matthieu Baerts (NGI0) wrote:

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)?

Hi Kristoffer,

Thank you for your comment.

On 20/02/2024 10:36, Kristoffer Haugsbakk wrote:

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

On Tue, Feb 20, 2024, at 10:58, Matthieu Baerts wrote:

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" <code@khaugsbakk.name> writes:

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/

Hi Junio,

Thank you for your reply!

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

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

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

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?

To me, they don't need departing changes. If they are still experimental after 5 years, it is hard to recommend them :)

Cheers, Matt

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

 From 2

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

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.

On 20/02/2024 10:36, Kristoffer Haugsbakk wrote:

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:

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

On Tue, Feb 20, 2024, at 14:32, Martin wrote:

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