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

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

[Justin Tobler]

Greetings,

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, over this time, there has not
been much change that would warrant these commands being labeled as
experimental.

There was a patch submitted[1] about a year ago also with the intent to
remove the experimental marker for these commands, but fizzled out
seemingly due to uncertainty around whether past discussions around
git-switch(1) had been resolved. Digging through some of these
conversations[2], a point of concern for git-switch(1) was around some of
the chosen short flags for git-switch(1), namely the `-c` flag for
creating a branch and the `-m` flag for merging local modifications into
the target branch via a three-way merge. The idea was that maybe these
short flags should instead be reserved for other not yet implemented
options in the future.

At this point, it seems rather difficult to justify changing
`-c/--create` to something different as it has been that way for a long
time and is used frequently. Also I'm not entirely convinced switching
to something like `-n/--new` is much better as it would run into a
similar issue of taking the short flag commonly used for the `--dry-run`
option. As for the `-m/--merge` flag, I don't think there is much harm
in dropping the short flag for what I presume to be a relatively
uncommon option. Outside of these explicitly brought up concerns though,
I have not found anything that would require a breaking change to
git-switch(1).

By removing the experimental marker, we help clarify the stability and
maturity of these commands. It will also make it easier for users to
adopt and recommend, as the experimental label has been a point of
hesitation for some. For new users, git-switch(1) and git-restore(1) do
help avoid some confusion that comes with the one-command-do-all
git-checkout(1) so helping to further promote their use should be
beneficial.

Thanks,
-Justin

[1]: <20240220092957.1296283-2-matttbe@kernel.org>
[2]: <877dkdwgfe.fsf@evledraar.gmail.com>

Justin Tobler (2):
  builtin: remove merge short flag for switch and restore
  builtin: unmark git-switch and git-restore as experimental

 Documentation/git-restore.adoc |  3 ---
 Documentation/git-switch.adoc  |  3 ---
 builtin/checkout.c             | 24 ++++++++++++++++--------
 3 files changed, 16 insertions(+), 14 deletions(-)


base-commit: 3f2a94875d2f41fe4758a439f68d8b73cfb19d0f
-- 
2.50.1.214.ga30f80fde9

[PATCH 1/2] builtin: remove merge short flag for switch and restore

[Justin Tobler]

Both git-switch(1) and git-restore(1) inherit some common options from
git-checkout(1). One such option is the `--merge` flag and its
accompanying short flag `-m`.

In previous discussion[1] around removing the experimental marker for
git-switch(1), it has been suggested that this short flag could instead
be used for an option similar to `--move` from git-branch(1). Such a
feature is not yet implemented for this command, but reserving a short
flag for an uncommon option is unnecessary and hinders potential future
extension.

While these commands are still marked as experimental, remove the `-m`
flag from both git-switch(1) and git-restore(1) and update the
documentation accordingly. The `--conflict` flag is also now defined
explicitly for each command as to remain alongside its related `--merge`
companion.

[1]: https://lore.kernel.org/git/877dkdwgfe.fsf@evledraar.gmail.com/

Signed-off-by: Justin Tobler <jltobler@gmail.com>
---
 Documentation/git-restore.adoc |  1 -
 Documentation/git-switch.adoc  |  1 -
 builtin/checkout.c             | 24 ++++++++++++++++--------
 3 files changed, 16 insertions(+), 10 deletions(-)

diff --git a/Documentation/git-restore.adoc b/Documentation/git-restore.adoc
index 877b7772e66..96de9bb5ed7 100644
--- a/Documentation/git-restore.adoc
+++ b/Documentation/git-restore.adoc
@@ -82,7 +82,6 @@ Note that during `git rebase` and `git pull --rebase`, `ours` and
 `theirs` may appear swapped. See the explanation of the same options
 in linkgit:git-checkout[1] for details.
 
-`-m`::
 `--merge`::
 	When restoring files on the working tree from the index,
 	recreate the conflicted merge in the unmerged paths.
diff --git a/Documentation/git-switch.adoc b/Documentation/git-switch.adoc
index 9f62abf9e2b..7b24450f841 100644
--- a/Documentation/git-switch.adoc
+++ b/Documentation/git-switch.adoc
@@ -123,7 +123,6 @@ variable.
 	submodule content is also restored to match the switching
 	target. This is used to throw away local changes.
 
-`-m`::
 `--merge`::
 	If you have local modifications to one or more files that are
 	different between the current branch and the branch to which
diff --git a/builtin/checkout.c b/builtin/checkout.c
index 0a90b86a729..0d5b182166e 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -1689,13 +1689,9 @@ static struct option *add_common_options(struct checkout_opts *opts,
 	struct option options[] = {
 		OPT__QUIET(&opts->quiet, N_("suppress progress reporting")),
 		OPT_CALLBACK_F(0, "recurse-submodules", NULL,
-			    "checkout", "control recursive updating of submodules",
-			    PARSE_OPT_OPTARG, option_parse_recurse_submodules_worktree_updater),
+			       "checkout", "control recursive updating of submodules",
+			       PARSE_OPT_OPTARG, option_parse_recurse_submodules_worktree_updater),
 		OPT_BOOL(0, "progress", &opts->show_progress, N_("force progress reporting")),
-		OPT_BOOL('m', "merge", &opts->merge, N_("perform a 3-way merge with the new branch")),
-		OPT_CALLBACK(0, "conflict", opts, N_("style"),
-			     N_("conflict style (merge, diff3, or zdiff3)"),
-			     parse_opt_conflict),
 		OPT_END()
 	};
 	struct option *newopts = parse_options_concat(prevopts, options);
@@ -1976,6 +1972,10 @@ int cmd_checkout(int argc,
 		OPT_BOOL(0, "guess", &opts.dwim_new_local_branch,
 			 N_("second guess 'git checkout <no-such-branch>' (default)")),
 		OPT_BOOL(0, "overlay", &opts.overlay_mode, N_("use overlay mode (default)")),
+		OPT_BOOL('m', "merge", &opts.merge, N_("perform a 3-way merge with the new branch")),
+		OPT_CALLBACK(0, "conflict", &opts, N_("style"),
+			     N_("conflict style (merge, diff3, or zdiff3)"),
+			     parse_opt_conflict),
 		OPT_END()
 	};
 
@@ -2026,6 +2026,10 @@ int cmd_switch(int argc,
 			 N_("second guess 'git switch <no-such-branch>'")),
 		OPT_BOOL(0, "discard-changes", &opts.discard_changes,
 			 N_("throw away local modifications")),
+		OPT_BOOL(0, "merge", &opts.merge, N_("perform a 3-way merge with the new branch")),
+		OPT_CALLBACK(0, "conflict", &opts, N_("style"),
+			     N_("conflict style (merge, diff3, or zdiff3)"),
+			     parse_opt_conflict),
 		OPT_END()
 	};
 
@@ -2060,12 +2064,16 @@ int cmd_restore(int argc,
 		OPT_STRING('s', "source", &opts.from_treeish, "<tree-ish>",
 			   N_("which tree-ish to checkout from")),
 		OPT_BOOL('S', "staged", &opts.checkout_index,
-			   N_("restore the index")),
+			 N_("restore the index")),
 		OPT_BOOL('W', "worktree", &opts.checkout_worktree,
-			   N_("restore the working tree (default)")),
+			 N_("restore the working tree (default)")),
 		OPT_BOOL(0, "ignore-unmerged", &opts.ignore_unmerged,
 			 N_("ignore unmerged entries")),
 		OPT_BOOL(0, "overlay", &opts.overlay_mode, N_("use overlay mode")),
+		OPT_BOOL(0, "merge", &opts.merge, N_("perform a 3-way merge with the new branch")),
+		OPT_CALLBACK(0, "conflict", &opts, N_("style"),
+			     N_("conflict style (merge, diff3, or zdiff3)"),
+			     parse_opt_conflict),
 		OPT_END()
 	};
 
-- 
2.50.1.214.ga30f80fde9

Re: [PATCH 1/2] builtin: remove merge short flag for switch and restore

[Junio C Hamano]

Justin Tobler <jltobler@gmail.com> writes:

> Both git-switch(1) and git-restore(1) inherit some common options from
> git-checkout(1). One such option is the `--merge` flag and its
> accompanying short flag `-m`.
>
> In previous discussion[1] around removing the experimental marker for
> git-switch(1), it has been suggested that this short flag could instead
> be used for an option similar to `--move` from git-branch(1). Such a
> feature is not yet implemented for this command, but reserving a short
> flag for an uncommon option is unnecessary and hinders potential future
> extension.
>
> While these commands are still marked as experimental, remove the `-m`
> flag from both git-switch(1) and git-restore(1) and update the
> documentation accordingly.

Surely the whole point of marking the commands as experimental is to
allow us to make a change like this one.

I doubt that this particular one is a sensible change, though.

"git checkout -m <another-branch>" is one of the most frequently
used operation in my daily workflow, and having to type "git switch
--merge" (not having to learn to do so) would be a major annoyance.

> The `--conflict` flag is also now defined
> explicitly for each command as to remain alongside its related `--merge`
> companion.

I doubt this is a wise move.  Unless we are planning to make the
option diverge across these three commands, that is.

The main logic that implements the "move to a different branch,
while merging local changes into the new base" does use these two
things together in the same code path (in merge_working_tree()).
The same for "check out a single path out to the working tree",
which does use these two things together in the same code path (in
checkout_merged()).  I actually think keeping it in the common part
would help the readers of the code even more---by making it clear
that these three commands parse the option exactly the same way.

Re: [PATCH 1/2] builtin: remove merge short flag for switch and restore

[Justin Tobler]

On 25/07/22 01:54PM, Junio C Hamano wrote:
> Justin Tobler <jltobler@gmail.com> writes:
> I doubt that this particular one is a sensible change, though.
> 
> "git checkout -m <another-branch>" is one of the most frequently
> used operation in my daily workflow, and having to type "git switch
> --merge" (not having to learn to do so) would be a major annoyance.

In general, I think it is best to reserve short flags for relavitely
common operations. That way, if a new super useful option were to be
introduced that we want a short flag for, there is a better chance a
good flag choice will be available.

That being said, I incorrectly assumed `--merge` was an uncommon option.
If there are workflows that make frequent use of this option, we should
drop this patch and keep the short flag available.

> > The `--conflict` flag is also now defined
> > explicitly for each command as to remain alongside its related `--merge`
> > companion.
> 
> I doubt this is a wise move.  Unless we are planning to make the
> option diverge across these three commands, that is.
> 
> The main logic that implements the "move to a different branch,
> while merging local changes into the new base" does use these two
> things together in the same code path (in merge_working_tree()).
> The same for "check out a single path out to the working tree",
> which does use these two things together in the same code path (in
> checkout_merged()).  I actually think keeping it in the common part
> would help the readers of the code even more---by making it clear
> that these three commands parse the option exactly the same way.

That's fair. If we do want to keep this patch, we could still keep it as
part of `builtin/checkout.c:add_common_options()`, but add an argument
to toggle short flag usage. This way it is at least clear to readers of
the code that it is same option.

Thanks,
-Justin

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

[Justin Tobler]

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.

A previous series[1] from about a year ago, also proposed removing the
experimental marker for these commands. One point of hesitation
pertained to an unaddressed suggestion[2] to change the `-c` and `-m`
short flags in git-switch(1) to allow them to be used for different
operations that may be a better fit. In the preceding patch, the `-m`
short flag is dropped following this suggestion. For the `-c` short flag
though, the operation to create a new branch is common enough to warrant
a short flag. Given how common this option is, changing it would be
disruptive to users and, absent a substantially better choice, is
difficult to justify changing.

Outside of these suggested option changes, there does not appear to be
any other discussion that would warrant breaking changes to these
commands. This likely signals that the foundations of these commands are
in a decent state. Furthermore, by removing the experimental marker, the
stability and maturity of these commands is clarified making it easier
for users to adopt and recommend.

Update the documentation for git-switch(1) and git-restore(1) to remove
the experimental label.

[1]: https://lore.kernel.org/git/20240220092957.1296283-2-matttbe@kernel.org/
[2]: https://lore.kernel.org/git/877dkdwgfe.fsf@evledraar.gmail.com/

Signed-off-by: Justin Tobler <jltobler@gmail.com>
---
 Documentation/git-restore.adoc | 2 --
 Documentation/git-switch.adoc  | 2 --
 2 files changed, 4 deletions(-)

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>_::
-- 
2.50.1.214.ga30f80fde9

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

[Junio C Hamano]

Justin Tobler <jltobler@gmail.com> 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.

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

[Justin Tobler]

On 25/07/22 02:00PM, Junio C Hamano wrote:
> Justin Tobler <jltobler@gmail.com> 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.

Will update in the next version.

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

I'm not sure even five years would be enough ;-)

Thanks,
-Justin

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

[Junio C Hamano]

Justin Tobler <jltobler@gmail.com> writes:

> Greetings,
>
> 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, over this time, there has not
> been much change that would warrant these commands being labeled as
> experimental.

Do you mean "as not experimental anymore", don't you?  We were
hoping that we would come up with vast UI improvements, that are so
much better that warrant departure from the past, allowing us room
to even break the backward compatibility.  Unfortunately, we do not
have much to show after 5 years.  But ...

> At this point, it seems rather difficult to justify changing
> `-c/--create` to something different as it has been that way for a long
> time and is used frequently.

... yeah, people grew to rely on that experimental UI that we added,
with intention to revamp and replace with much better alternative,
and now it is too late to change it.

> By removing the experimental marker, we help clarify the stability and
> maturity of these commands.

So, even though I may agree with the conclusion that we no longer
would allow ourselves to break backward compatibility for these two
commands, I doubt that it is stability and maturity to celebrate
about.  It (not the "have two speparate commands" part, but "leave
ourselves room to improve these two commands" part) was a clearly
failed experiment.

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

[Justin Tobler]

On 25/07/22 01:22PM, Junio C Hamano wrote:
> Justin Tobler <jltobler@gmail.com> writes:
> 
> > Greetings,
> >
> > 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, over this time, there has not
> > been much change that would warrant these commands being labeled as
> > experimental.
> 
> Do you mean "as not experimental anymore", don't you?

Apoligies, the wording on my part is a bit poor. Your understanding is
correct.

> We were
> hoping that we would come up with vast UI improvements, that are so
> much better that warrant departure from the past, allowing us room
> to even break the backward compatibility.  Unfortunately, we do not
> have much to show after 5 years.  But ...
> 
> > At this point, it seems rather difficult to justify changing
> > `-c/--create` to something different as it has been that way for a long
> > time and is used frequently.
> 
> ... yeah, people grew to rely on that experimental UI that we added,
> with intention to revamp and replace with much better alternative,
> and now it is too late to change it.
> 
> > By removing the experimental marker, we help clarify the stability and
> > maturity of these commands.
> 
> So, even though I may agree with the conclusion that we no longer
> would allow ourselves to break backward compatibility for these two
> commands, I doubt that it is stability and maturity to celebrate
> about.  It (not the "have two speparate commands" part, but "leave
> ourselves room to improve these two commands" part) was a clearly
> failed experiment.

That's fair. The wording should probably be toned down here. My intent
is really just to indicate that users will likely be more inclined to
use these commands if they are not marked as experimental.

Thanks for the review. I'll give it some time to collect for feedback
and then submit a follow up version. 

-Justin

[PATCH] builtin: unmark git-switch and git-restore as experimental

[Justin Tobler]

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 hasn't been much change.
Consequently, users have grown to rely on how these commands work and it
is no longer feasible to make any breaking changes.

Let's remove the experimental label for git-switch(1) and
git-restore(1).

Signed-off-by: Justin Tobler <jltobler@gmail.com>
---
 Documentation/git-restore.adoc | 2 --
 Documentation/git-switch.adoc  | 2 --
 2 files changed, 4 deletions(-)

diff --git a/Documentation/git-restore.adoc b/Documentation/git-restore.adoc
index 877b7772e66..3763a7f4f43 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 9f62abf9e2b..87707e92652 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>_::
-- 
2.50.1.214.ga30f80fde9

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

[Junio C Hamano]

Justin Tobler <jltobler@gmail.com> 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 hasn't been much change.
> Consequently, users have grown to rely on how these commands work and it
> is no longer feasible to make any breaking changes.
>
> Let's remove the experimental label for git-switch(1) and
> git-restore(1).
>
> Signed-off-by: Justin Tobler <jltobler@gmail.com>
> ---
>  Documentation/git-restore.adoc | 2 --
>  Documentation/git-switch.adoc  | 2 --
>  2 files changed, 4 deletions(-)

Thanks for tying loose ends.  This completely slipped my mind.

Will queue.  Thanks.

> diff --git a/Documentation/git-restore.adoc b/Documentation/git-restore.adoc
> index 877b7772e66..3763a7f4f43 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 9f62abf9e2b..87707e92652 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>_::