Skip to contentSkip to conversation

builtin: unmark git-switch and git-restore as experimental

PATCH In review Justin Tobler 2 participants 11 messages Jul 22, 2025 – Jul 28, 2025 Documentation

lore
Share & tools
lore
#0 lore raw

cover builtin: unmark git-switch and git-restore as experimental

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]: <[email protected]> [2]: <[email protected]>

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

Signature · 1 line
2.50.1.214.ga30f80fde9
#1 lore raw

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

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/[email protected]/

---
 Documentation/git-restore.adoc |  1 -
 Documentation/git-switch.adoc  |  1 -
 builtin/checkout.c             | 24 ++++++++++++++++--------
 3 files changed, 16 insertions(+), 10 deletions(-)
Documentation/git-restore.adoc +0 -1
index 877b7772e66..96de9bb5ed7 100644
@@ -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.
Documentation/git-switch.adoc +0 -1
index 9f62abf9e2b..7b24450f841 100644
@@ -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
builtin/checkout.c +16 -8
index 0a90b86a729..0d5b182166e 100644
@@ -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()
 	};
 
Signature · 1 line
2.50.1.214.ga30f80fde9
#2 lore raw

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

Quoted 11 lines · 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.

Quoted 3 lines

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.

Quoted 3 lines

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.

#3 lore raw

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

Quoted 6 lines · Junio C Hamano

Justin Tobler <[email protected]> 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.

Quoted 7 lines
Quoted 3 lines

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.

Quoted 8 lines

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

#4 lore raw

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

In reply to 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/[email protected]/
[2]: https://lore.kernel.org/git/[email protected]/

---
 Documentation/git-restore.adoc | 2 --
 Documentation/git-switch.adoc  | 2 --
 2 files changed, 4 deletions(-)
Documentation/git-restore.adoc +0 -2
index 96de9bb5ed7..903e8c4618a 100644
@@ -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>`::
Documentation/git-switch.adoc +0 -2
index 7b24450f841..1d46010292d 100644
@@ -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>_::
Signature · 1 line
2.50.1.214.ga30f80fde9
#5 lore raw
Quoted 6 lines · 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.

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.

Quoted 18 lines
Documentation/git-restore.adoc +0 -2
index 96de9bb5ed7..903e8c4618a 100644
@@ -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>`::
Documentation/git-switch.adoc +0 -0
index 7b24450f841..1d46010292d 100644

Documentation/git-switch.adoc Switching branches does not require a clean index and working tree · line 34

Quoted 8 lines
Documentation/git-switch.adoc +0 -2
@@ -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.

#6 lore raw
Quoted 12 lines · Junio C Hamano
Quoted 6 lines · 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.

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

Quoted 8 lines

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.

Quoted 31 lines
Quoted 19 lines
Documentation/git-restore.adoc +0 -2
index 96de9bb5ed7..903e8c4618a 100644
@@ -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>`::
Documentation/git-switch.adoc +0 -0
index 7b24450f841..1d46010292d 100644

Documentation/git-switch.adoc Switching branches does not require a clean index and working tree · line 34

Quoted 8 lines
Documentation/git-switch.adoc +0 -2
@@ -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.

Quoted 2 lines

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

#7 lore raw
In reply to Justin Tobler
Quoted 9 lines · 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.

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

Quoted 3 lines

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.

Quoted 2 lines

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.

#8 lore raw
Quoted 12 lines · Junio C Hamano
Quoted 9 lines · 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.

Quoted 1 line

Do you mean "as not experimental anymore", don't you?

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

Quoted 17 lines

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

Quoted 3 lines

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.

Quoted 2 lines

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

Quoted 6 lines

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

#9 lore raw

PATCH 1/1 builtin: unmark git-switch and git-restore as experimental

In reply to 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).

---
 Documentation/git-restore.adoc | 2 --
 Documentation/git-switch.adoc  | 2 --
 2 files changed, 4 deletions(-)
Documentation/git-restore.adoc +0 -2
index 877b7772e66..3763a7f4f43 100644
@@ -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>`::
Documentation/git-switch.adoc +0 -2
index 9f62abf9e2b..87707e92652 100644
@@ -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>_::
Signature · 1 line
2.50.1.214.ga30f80fde9
#10 lore raw
Quoted 8 lines · 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.

Quoted 8 lines

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

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

Quoted 26 lines
Documentation/git-restore.adoc +0 -2
index 877b7772e66..3763a7f4f43 100644
@@ -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>`::
Documentation/git-switch.adoc +0 -2
index 9f62abf9e2b..87707e92652 100644
@@ -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>_::