Subject: Re: [PATCH 2/2] builtin: unmark git-switch and git-restore as experimental

From: Junio C Hamano <[email-masked]>
Date: Tue, 22 Jul 2025 14:00:10 -0700

Justin Tobler <[email-masked]> writes:

> In 4e43b7ff (Declare both git-switch and git-restore experimental,
> 2019-04-25), the newly introduced git-switch(1) and git-restore(1)
> commands were marked as experimental. This was done to provide time to
> make breaking changes to the interface. It has now been over six years
> since these commands were implemented and there has not been much change
> that would warrant these commands remaining experimental.

Remove "and there has not been ..." and everything after this point,
and replace it with something like

    but there hasn't been much change.  In the meantime, these
    commands being experimental has become an old news.  People have
    become so grown to rely on how these commands work, it is no
    longer feasible for us to now make breaking changes to them.

    Let's mark them no longer experimental.

or something like that, perhaps.

> diff --git a/Documentation/git-restore.adoc b/Documentation/git-restore.adoc
> index 96de9bb5ed7..903e8c4618a 100644
> --- a/Documentation/git-restore.adoc
> +++ b/Documentation/git-restore.adoc
> @@ -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.adoc b/Documentation/git-switch.adoc
> index 7b24450f841..1d46010292d 100644
> --- a/Documentation/git-switch.adoc
> +++ b/Documentation/git-switch.adoc
> @@ -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>_::

I think these two changes are OK.  I personally do not think [1/2]
is a great idea.  At least I am not convinced myself not yet.

And if [1/2] were a good idea, then we probably should apply it, and
then wait for another 5 years before proceeding to this [2/2] patch.