{"thread":{"id":"63825","subject":"[PATCH 0/2] builtin: unmark git-switch and git-restore as experimental","startedAt":"2025-07-22T18:15:26Z","lastAt":"2025-07-28T20:52:04Z","messageCount":11,"participants":["Justin Tobler","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"522485","messageId":"20250722180818.1043014-1-jltobler@gmail.com","threadId":"63825","inReplyTo":null,"subject":"[PATCH 0/2] builtin: unmark git-switch and git-restore as experimental","fromName":"Justin Tobler","fromEmail":"jltobler@gmail.com","sentAt":"2025-07-22T18:08:16Z","receivedAt":"2025-07-22T18:15:26Z","isPatch":true,"sender":{"key":"jltobler@gmail.com","avatar":"https://avatars.githubusercontent.com/u/53454972?v=4"},"body":"Greetings,\n\nIn 4e43b7ff (Declare both git-switch and git-restore experimental,\n2019-04-25), the newly introduced git-switch(1) and git-restore(1)\ncommands were marked as experimental. This was done to provide time to\nmake breaking changes to the interface. It has now been over six years\nsince these commands were implemented and, over this time, there has not\nbeen much change that would warrant these commands being labeled as\nexperimental.\n\nThere was a patch submitted[1] about a year ago also with the intent to\nremove the experimental marker for these commands, but fizzled out\nseemingly due to uncertainty around whether past discussions around\ngit-switch(1) had been resolved. Digging through some of these\nconversations[2], a point of concern for git-switch(1) was around some of\nthe chosen short flags for git-switch(1), namely the `-c` flag for\ncreating a branch and the `-m` flag for merging local modifications into\nthe target branch via a three-way merge. The idea was that maybe these\nshort flags should instead be reserved for other not yet implemented\noptions in the future.\n\nAt this point, it seems rather difficult to justify changing\n`-c/--create` to something different as it has been that way for a long\ntime and is used frequently. Also I'm not entirely convinced switching\nto something like `-n/--new` is much better as it would run into a\nsimilar issue of taking the short flag commonly used for the `--dry-run`\noption. As for the `-m/--merge` flag, I don't think there is much harm\nin dropping the short flag for what I presume to be a relatively\nuncommon option. Outside of these explicitly brought up concerns though,\nI have not found anything that would require a breaking change to\ngit-switch(1).\n\nBy removing the experimental marker, we help clarify the stability and\nmaturity of these commands. It will also make it easier for users to\nadopt and recommend, as the experimental label has been a point of\nhesitation for some. For new users, git-switch(1) and git-restore(1) do\nhelp avoid some confusion that comes with the one-command-do-all\ngit-checkout(1) so helping to further promote their use should be\nbeneficial.\n\nThanks,\n-Justin\n\n[1]: <20240220092957.1296283-2-matttbe@kernel.org>\n[2]: <877dkdwgfe.fsf@evledraar.gmail.com>\n\nJustin Tobler (2):\n builtin: remove merge short flag for switch and restore\n builtin: unmark git-switch and git-restore as experimental\n\n Documentation/git-restore.adoc | 3 ---\n Documentation/git-switch.adoc | 3 ---\n builtin/checkout.c | 24 ++++++++++++++++--------\n 3 files changed, 16 insertions(+), 14 deletions(-)\n\n\nbase-commit: 3f2a94875d2f41fe4758a439f68d8b73cfb19d0f\n-- \n2.50.1.214.ga30f80fde9\n\n"},{"id":"522486","messageId":"20250722180818.1043014-2-jltobler@gmail.com","threadId":"63825","inReplyTo":"20250722180818.1043014-1-jltobler@gmail.com","subject":"[PATCH 1/2] builtin: remove merge short flag for switch and restore","fromName":"Justin Tobler","fromEmail":"jltobler@gmail.com","sentAt":"2025-07-22T18:08:17Z","receivedAt":"2025-07-22T18:15:27Z","isPatch":true,"sender":{"key":"jltobler@gmail.com","avatar":"https://avatars.githubusercontent.com/u/53454972?v=4"},"body":"Both git-switch(1) and git-restore(1) inherit some common options from\ngit-checkout(1). One such option is the `--merge` flag and its\naccompanying short flag `-m`.\n\nIn previous discussion[1] around removing the experimental marker for\ngit-switch(1), it has been suggested that this short flag could instead\nbe used for an option similar to `--move` from git-branch(1). Such a\nfeature is not yet implemented for this command, but reserving a short\nflag for an uncommon option is unnecessary and hinders potential future\nextension.\n\nWhile these commands are still marked as experimental, remove the `-m`\nflag from both git-switch(1) and git-restore(1) and update the\ndocumentation accordingly. The `--conflict` flag is also now defined\nexplicitly for each command as to remain alongside its related `--merge`\ncompanion.\n\n[1]: https://lore.kernel.org/git/877dkdwgfe.fsf@evledraar.gmail.com/\n\nSigned-off-by: Justin Tobler \n---\n Documentation/git-restore.adoc | 1 -\n Documentation/git-switch.adoc | 1 -\n builtin/checkout.c | 24 ++++++++++++++++--------\n 3 files changed, 16 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/git-restore.adoc b/Documentation/git-restore.adoc\nindex 877b7772e66..96de9bb5ed7 100644\n--- a/Documentation/git-restore.adoc\n+++ b/Documentation/git-restore.adoc\n@@ -82,7 +82,6 @@ Note that during `git rebase` and `git pull --rebase`, `ours` and\n `theirs` may appear swapped. See the explanation of the same options\n in linkgit:git-checkout[1] for details.\n \n-`-m`::\n `--merge`::\n \tWhen restoring files on the working tree from the index,\n \trecreate the conflicted merge in the unmerged paths.\ndiff --git a/Documentation/git-switch.adoc b/Documentation/git-switch.adoc\nindex 9f62abf9e2b..7b24450f841 100644\n--- a/Documentation/git-switch.adoc\n+++ b/Documentation/git-switch.adoc\n@@ -123,7 +123,6 @@ variable.\n \tsubmodule content is also restored to match the switching\n \ttarget. This is used to throw away local changes.\n \n-`-m`::\n `--merge`::\n \tIf you have local modifications to one or more files that are\n \tdifferent between the current branch and the branch to which\ndiff --git a/builtin/checkout.c b/builtin/checkout.c\nindex 0a90b86a729..0d5b182166e 100644\n--- a/builtin/checkout.c\n+++ b/builtin/checkout.c\n@@ -1689,13 +1689,9 @@ static struct option *add_common_options(struct checkout_opts *opts,\n \tstruct option options[] = {\n \t\tOPT__QUIET(&opts->quiet, N_(\"suppress progress reporting\")),\n \t\tOPT_CALLBACK_F(0, \"recurse-submodules\", NULL,\n-\t\t\t \"checkout\", \"control recursive updating of submodules\",\n-\t\t\t PARSE_OPT_OPTARG, option_parse_recurse_submodules_worktree_updater),\n+\t\t\t \"checkout\", \"control recursive updating of submodules\",\n+\t\t\t PARSE_OPT_OPTARG, option_parse_recurse_submodules_worktree_updater),\n \t\tOPT_BOOL(0, \"progress\", &opts->show_progress, N_(\"force progress reporting\")),\n-\t\tOPT_BOOL('m', \"merge\", &opts->merge, N_(\"perform a 3-way merge with the new branch\")),\n-\t\tOPT_CALLBACK(0, \"conflict\", opts, N_(\"style\"),\n-\t\t\t N_(\"conflict style (merge, diff3, or zdiff3)\"),\n-\t\t\t parse_opt_conflict),\n \t\tOPT_END()\n \t};\n \tstruct option *newopts = parse_options_concat(prevopts, options);\n@@ -1976,6 +1972,10 @@ int cmd_checkout(int argc,\n \t\tOPT_BOOL(0, \"guess\", &opts.dwim_new_local_branch,\n \t\t\t N_(\"second guess 'git checkout ' (default)\")),\n \t\tOPT_BOOL(0, \"overlay\", &opts.overlay_mode, N_(\"use overlay mode (default)\")),\n+\t\tOPT_BOOL('m', \"merge\", &opts.merge, N_(\"perform a 3-way merge with the new branch\")),\n+\t\tOPT_CALLBACK(0, \"conflict\", &opts, N_(\"style\"),\n+\t\t\t N_(\"conflict style (merge, diff3, or zdiff3)\"),\n+\t\t\t parse_opt_conflict),\n \t\tOPT_END()\n \t};\n \n@@ -2026,6 +2026,10 @@ int cmd_switch(int argc,\n \t\t\t N_(\"second guess 'git switch '\")),\n \t\tOPT_BOOL(0, \"discard-changes\", &opts.discard_changes,\n \t\t\t N_(\"throw away local modifications\")),\n+\t\tOPT_BOOL(0, \"merge\", &opts.merge, N_(\"perform a 3-way merge with the new branch\")),\n+\t\tOPT_CALLBACK(0, \"conflict\", &opts, N_(\"style\"),\n+\t\t\t N_(\"conflict style (merge, diff3, or zdiff3)\"),\n+\t\t\t parse_opt_conflict),\n \t\tOPT_END()\n \t};\n \n@@ -2060,12 +2064,16 @@ int cmd_restore(int argc,\n \t\tOPT_STRING('s', \"source\", &opts.from_treeish, \"\",\n \t\t\t N_(\"which tree-ish to checkout from\")),\n \t\tOPT_BOOL('S', \"staged\", &opts.checkout_index,\n-\t\t\t N_(\"restore the index\")),\n+\t\t\t N_(\"restore the index\")),\n \t\tOPT_BOOL('W', \"worktree\", &opts.checkout_worktree,\n-\t\t\t N_(\"restore the working tree (default)\")),\n+\t\t\t N_(\"restore the working tree (default)\")),\n \t\tOPT_BOOL(0, \"ignore-unmerged\", &opts.ignore_unmerged,\n \t\t\t N_(\"ignore unmerged entries\")),\n \t\tOPT_BOOL(0, \"overlay\", &opts.overlay_mode, N_(\"use overlay mode\")),\n+\t\tOPT_BOOL(0, \"merge\", &opts.merge, N_(\"perform a 3-way merge with the new branch\")),\n+\t\tOPT_CALLBACK(0, \"conflict\", &opts, N_(\"style\"),\n+\t\t\t N_(\"conflict style (merge, diff3, or zdiff3)\"),\n+\t\t\t parse_opt_conflict),\n \t\tOPT_END()\n \t};\n \n-- \n2.50.1.214.ga30f80fde9\n\n"},{"id":"522487","messageId":"20250722180818.1043014-3-jltobler@gmail.com","threadId":"63825","inReplyTo":"20250722180818.1043014-1-jltobler@gmail.com","subject":"[PATCH 2/2] builtin: unmark git-switch and git-restore as experimental","fromName":"Justin Tobler","fromEmail":"jltobler@gmail.com","sentAt":"2025-07-22T18:08:18Z","receivedAt":"2025-07-22T18:15:28Z","isPatch":true,"sender":{"key":"jltobler@gmail.com","avatar":"https://avatars.githubusercontent.com/u/53454972?v=4"},"body":"In 4e43b7ff (Declare both git-switch and git-restore experimental,\n2019-04-25), the newly introduced git-switch(1) and git-restore(1)\ncommands were marked as experimental. This was done to provide time to\nmake breaking changes to the interface. It has now been over six years\nsince these commands were implemented and there has not been much change\nthat would warrant these commands remaining experimental.\n\nA previous series[1] from about a year ago, also proposed removing the\nexperimental marker for these commands. One point of hesitation\npertained to an unaddressed suggestion[2] to change the `-c` and `-m`\nshort flags in git-switch(1) to allow them to be used for different\noperations that may be a better fit. In the preceding patch, the `-m`\nshort flag is dropped following this suggestion. For the `-c` short flag\nthough, the operation to create a new branch is common enough to warrant\na short flag. Given how common this option is, changing it would be\ndisruptive to users and, absent a substantially better choice, is\ndifficult to justify changing.\n\nOutside of these suggested option changes, there does not appear to be\nany other discussion that would warrant breaking changes to these\ncommands. This likely signals that the foundations of these commands are\nin a decent state. Furthermore, by removing the experimental marker, the\nstability and maturity of these commands is clarified making it easier\nfor users to adopt and recommend.\n\nUpdate the documentation for git-switch(1) and git-restore(1) to remove\nthe experimental label.\n\n[1]: https://lore.kernel.org/git/20240220092957.1296283-2-matttbe@kernel.org/\n[2]: https://lore.kernel.org/git/877dkdwgfe.fsf@evledraar.gmail.com/\n\nSigned-off-by: Justin Tobler \n---\n Documentation/git-restore.adoc | 2 --\n Documentation/git-switch.adoc | 2 --\n 2 files changed, 4 deletions(-)\n\ndiff --git a/Documentation/git-restore.adoc b/Documentation/git-restore.adoc\nindex 96de9bb5ed7..903e8c4618a 100644\n--- a/Documentation/git-restore.adoc\n+++ b/Documentation/git-restore.adoc\n@@ -28,8 +28,6 @@ otherwise from the index. Use `--source` to restore from a different commit.\n See \"Reset, restore and revert\" in linkgit:git[1] for the differences\n between the three commands.\n \n-THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.\n-\n OPTIONS\n -------\n `-s `::\ndiff --git a/Documentation/git-switch.adoc b/Documentation/git-switch.adoc\nindex 7b24450f841..1d46010292d 100644\n--- a/Documentation/git-switch.adoc\n+++ b/Documentation/git-switch.adoc\n@@ -29,8 +29,6 @@ Switching branches does not require a clean index and working tree\n however if the operation leads to loss of local changes, unless told\n otherwise with `--discard-changes` or `--merge`.\n \n-THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.\n-\n OPTIONS\n -------\n __::\n-- \n2.50.1.214.ga30f80fde9\n\n"},{"id":"522493","messageId":"xmqqldogrn64.fsf@gitster.g","threadId":"63825","inReplyTo":"20250722180818.1043014-1-jltobler@gmail.com","subject":"Re: [PATCH 0/2] builtin: unmark git-switch and git-restore as experimental","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-07-22T20:22:11Z","receivedAt":"2025-07-22T20:22:14Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Justin Tobler writes:\n\n> Greetings,\n>\n> In 4e43b7ff (Declare both git-switch and git-restore experimental,\n> 2019-04-25), the newly introduced git-switch(1) and git-restore(1)\n> commands were marked as experimental. This was done to provide time to\n> make breaking changes to the interface. It has now been over six years\n> since these commands were implemented and, over this time, there has not\n> been much change that would warrant these commands being labeled as\n> experimental.\n\nDo you mean \"as not experimental anymore\", don't you? We were\nhoping that we would come up with vast UI improvements, that are so\nmuch better that warrant departure from the past, allowing us room\nto even break the backward compatibility. Unfortunately, we do not\nhave much to show after 5 years. But ...\n\n> At this point, it seems rather difficult to justify changing\n> `-c/--create` to something different as it has been that way for a long\n> time and is used frequently.\n\n... yeah, people grew to rely on that experimental UI that we added,\nwith intention to revamp and replace with much better alternative,\nand now it is too late to change it.\n\n> By removing the experimental marker, we help clarify the stability and\n> maturity of these commands.\n\nSo, even though I may agree with the conclusion that we no longer\nwould allow ourselves to break backward compatibility for these two\ncommands, I doubt that it is stability and maturity to celebrate\nabout. It (not the \"have two speparate commands\" part, but \"leave\nourselves room to improve these two commands\" part) was a clearly\nfailed experiment.\n\n"},{"id":"522495","messageId":"xmqq1pq8rlo5.fsf@gitster.g","threadId":"63825","inReplyTo":"20250722180818.1043014-2-jltobler@gmail.com","subject":"Re: [PATCH 1/2] builtin: remove merge short flag for switch and restore","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-07-22T20:54:34Z","receivedAt":"2025-07-22T20:54:36Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Justin Tobler writes:\n\n> Both git-switch(1) and git-restore(1) inherit some common options from\n> git-checkout(1). One such option is the `--merge` flag and its\n> accompanying short flag `-m`.\n>\n> In previous discussion[1] around removing the experimental marker for\n> git-switch(1), it has been suggested that this short flag could instead\n> be used for an option similar to `--move` from git-branch(1). Such a\n> feature is not yet implemented for this command, but reserving a short\n> flag for an uncommon option is unnecessary and hinders potential future\n> extension.\n>\n> While these commands are still marked as experimental, remove the `-m`\n> flag from both git-switch(1) and git-restore(1) and update the\n> documentation accordingly.\n\nSurely the whole point of marking the commands as experimental is to\nallow us to make a change like this one.\n\nI doubt that this particular one is a sensible change, though.\n\n\"git checkout -m \" is one of the most frequently\nused operation in my daily workflow, and having to type \"git switch\n--merge\" (not having to learn to do so) would be a major annoyance.\n\n> The `--conflict` flag is also now defined\n> explicitly for each command as to remain alongside its related `--merge`\n> companion.\n\nI doubt this is a wise move. Unless we are planning to make the\noption diverge across these three commands, that is.\n\nThe main logic that implements the \"move to a different branch,\nwhile merging local changes into the new base\" does use these two\nthings together in the same code path (in merge_working_tree()).\nThe same for \"check out a single path out to the working tree\",\nwhich does use these two things together in the same code path (in\ncheckout_merged()). I actually think keeping it in the common part\nwould help the readers of the code even more---by making it clear\nthat these three commands parse the option exactly the same way.\n\n"},{"id":"522496","messageId":"xmqqv7nkq6ud.fsf@gitster.g","threadId":"63825","inReplyTo":"20250722180818.1043014-3-jltobler@gmail.com","subject":"Re: [PATCH 2/2] builtin: unmark git-switch and git-restore as experimental","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-07-22T21:00:10Z","receivedAt":"2025-07-22T21:00:12Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Justin Tobler writes:\n\n> In 4e43b7ff (Declare both git-switch and git-restore experimental,\n> 2019-04-25), the newly introduced git-switch(1) and git-restore(1)\n> commands were marked as experimental. This was done to provide time to\n> make breaking changes to the interface. It has now been over six years\n> since these commands were implemented and there has not been much change\n> that would warrant these commands remaining experimental.\n\nRemove \"and there has not been ...\" and everything after this point,\nand replace it with something like\n\n but there hasn't been much change. In the meantime, these\n commands being experimental has become an old news. People have\n become so grown to rely on how these commands work, it is no\n longer feasible for us to now make breaking changes to them.\n\n Let's mark them no longer experimental.\n\nor something like that, perhaps.\n\n> diff --git a/Documentation/git-restore.adoc b/Documentation/git-restore.adoc\n> index 96de9bb5ed7..903e8c4618a 100644\n> --- a/Documentation/git-restore.adoc\n> +++ b/Documentation/git-restore.adoc\n> @@ -28,8 +28,6 @@ otherwise from the index. Use `--source` to restore from a different commit.\n> See \"Reset, restore and revert\" in linkgit:git[1] for the differences\n> between the three commands.\n> \n> -THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.\n> -\n> OPTIONS\n> -------\n> `-s `::\n> diff --git a/Documentation/git-switch.adoc b/Documentation/git-switch.adoc\n> index 7b24450f841..1d46010292d 100644\n> --- a/Documentation/git-switch.adoc\n> +++ b/Documentation/git-switch.adoc\n> @@ -29,8 +29,6 @@ Switching branches does not require a clean index and working tree\n> however if the operation leads to loss of local changes, unless told\n> otherwise with `--discard-changes` or `--merge`.\n> \n> -THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.\n> -\n> OPTIONS\n> -------\n> __::\n\nI think these two changes are OK. I personally do not think [1/2]\nis a great idea. At least I am not convinced myself not yet.\n\nAnd if [1/2] were a good idea, then we probably should apply it, and\nthen wait for another 5 years before proceeding to this [2/2] patch.\n"},{"id":"522497","messageId":"hjvkryax5gq7im6m6jnlczykfctntnqf73xicbrfehe2j2c3rt@62m3urrkecg7","threadId":"63825","inReplyTo":"xmqq1pq8rlo5.fsf@gitster.g","subject":"Re: [PATCH 1/2] builtin: remove merge short flag for switch and restore","fromName":"Justin Tobler","fromEmail":"jltobler@gmail.com","sentAt":"2025-07-22T21:16:27Z","receivedAt":"2025-07-22T21:22:18Z","isPatch":true,"sender":{"key":"jltobler@gmail.com","avatar":"https://avatars.githubusercontent.com/u/53454972?v=4"},"body":"On 25/07/22 01:54PM, Junio C Hamano wrote:\n> Justin Tobler writes:\n> I doubt that this particular one is a sensible change, though.\n> \n> \"git checkout -m \" is one of the most frequently\n> used operation in my daily workflow, and having to type \"git switch\n> --merge\" (not having to learn to do so) would be a major annoyance.\n\nIn general, I think it is best to reserve short flags for relavitely\ncommon operations. That way, if a new super useful option were to be\nintroduced that we want a short flag for, there is a better chance a\ngood flag choice will be available.\n\nThat being said, I incorrectly assumed `--merge` was an uncommon option.\nIf there are workflows that make frequent use of this option, we should\ndrop this patch and keep the short flag available.\n\n> > The `--conflict` flag is also now defined\n> > explicitly for each command as to remain alongside its related `--merge`\n> > companion.\n> \n> I doubt this is a wise move. Unless we are planning to make the\n> option diverge across these three commands, that is.\n> \n> The main logic that implements the \"move to a different branch,\n> while merging local changes into the new base\" does use these two\n> things together in the same code path (in merge_working_tree()).\n> The same for \"check out a single path out to the working tree\",\n> which does use these two things together in the same code path (in\n> checkout_merged()). I actually think keeping it in the common part\n> would help the readers of the code even more---by making it clear\n> that these three commands parse the option exactly the same way.\n\nThat's fair. If we do want to keep this patch, we could still keep it as\npart of `builtin/checkout.c:add_common_options()`, but add an argument\nto toggle short flag usage. This way it is at least clear to readers of\nthe code that it is same option.\n\nThanks,\n-Justin\n"},{"id":"522498","messageId":"i5r2zmrfcdt5huyds42aixvewrql3aipcxrvdbqcuru4yc62ei@4b7jutquqruf","threadId":"63825","inReplyTo":"xmqqv7nkq6ud.fsf@gitster.g","subject":"Re: [PATCH 2/2] builtin: unmark git-switch and git-restore as experimental","fromName":"Justin Tobler","fromEmail":"jltobler@gmail.com","sentAt":"2025-07-22T21:20:45Z","receivedAt":"2025-07-22T21:26:36Z","isPatch":true,"sender":{"key":"jltobler@gmail.com","avatar":"https://avatars.githubusercontent.com/u/53454972?v=4"},"body":"On 25/07/22 02:00PM, Junio C Hamano wrote:\n> Justin Tobler writes:\n> \n> > In 4e43b7ff (Declare both git-switch and git-restore experimental,\n> > 2019-04-25), the newly introduced git-switch(1) and git-restore(1)\n> > commands were marked as experimental. This was done to provide time to\n> > make breaking changes to the interface. It has now been over six years\n> > since these commands were implemented and there has not been much change\n> > that would warrant these commands remaining experimental.\n> \n> Remove \"and there has not been ...\" and everything after this point,\n> and replace it with something like\n> \n> but there hasn't been much change. In the meantime, these\n> commands being experimental has become an old news. People have\n> become so grown to rely on how these commands work, it is no\n> longer feasible for us to now make breaking changes to them.\n> \n> Let's mark them no longer experimental.\n> \n> or something like that, perhaps.\n\nWill update in the next version.\n\n> \n> > diff --git a/Documentation/git-restore.adoc b/Documentation/git-restore.adoc\n> > index 96de9bb5ed7..903e8c4618a 100644\n> > --- a/Documentation/git-restore.adoc\n> > +++ b/Documentation/git-restore.adoc\n> > @@ -28,8 +28,6 @@ otherwise from the index. Use `--source` to restore from a different commit.\n> > See \"Reset, restore and revert\" in linkgit:git[1] for the differences\n> > between the three commands.\n> > \n> > -THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.\n> > -\n> > OPTIONS\n> > -------\n> > `-s `::\n> > diff --git a/Documentation/git-switch.adoc b/Documentation/git-switch.adoc\n> > index 7b24450f841..1d46010292d 100644\n> > --- a/Documentation/git-switch.adoc\n> > +++ b/Documentation/git-switch.adoc\n> > @@ -29,8 +29,6 @@ Switching branches does not require a clean index and working tree\n> > however if the operation leads to loss of local changes, unless told\n> > otherwise with `--discard-changes` or `--merge`.\n> > \n> > -THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.\n> > -\n> > OPTIONS\n> > -------\n> > __::\n> \n> I think these two changes are OK. I personally do not think [1/2]\n> is a great idea. At least I am not convinced myself not yet.\n> \n> And if [1/2] were a good idea, then we probably should apply it, and\n> then wait for another 5 years before proceeding to this [2/2] patch.\n\nI'm not sure even five years would be enough ;-)\n\nThanks,\n-Justin\n"},{"id":"522500","messageId":"g23v5k2m4pcqeyralbxnuop5s4qlrg3j6bjecwxaatuigneaej@mqsijwz6qp7d","threadId":"63825","inReplyTo":"xmqqldogrn64.fsf@gitster.g","subject":"Re: [PATCH 0/2] builtin: unmark git-switch and git-restore as experimental","fromName":"Justin Tobler","fromEmail":"jltobler@gmail.com","sentAt":"2025-07-22T21:32:34Z","receivedAt":"2025-07-22T21:38:24Z","isPatch":true,"sender":{"key":"jltobler@gmail.com","avatar":"https://avatars.githubusercontent.com/u/53454972?v=4"},"body":"On 25/07/22 01:22PM, Junio C Hamano wrote:\n> Justin Tobler writes:\n> \n> > Greetings,\n> >\n> > In 4e43b7ff (Declare both git-switch and git-restore experimental,\n> > 2019-04-25), the newly introduced git-switch(1) and git-restore(1)\n> > commands were marked as experimental. This was done to provide time to\n> > make breaking changes to the interface. It has now been over six years\n> > since these commands were implemented and, over this time, there has not\n> > been much change that would warrant these commands being labeled as\n> > experimental.\n> \n> Do you mean \"as not experimental anymore\", don't you?\n\nApoligies, the wording on my part is a bit poor. Your understanding is\ncorrect.\n\n> We were\n> hoping that we would come up with vast UI improvements, that are so\n> much better that warrant departure from the past, allowing us room\n> to even break the backward compatibility. Unfortunately, we do not\n> have much to show after 5 years. But ...\n> \n> > At this point, it seems rather difficult to justify changing\n> > `-c/--create` to something different as it has been that way for a long\n> > time and is used frequently.\n> \n> ... yeah, people grew to rely on that experimental UI that we added,\n> with intention to revamp and replace with much better alternative,\n> and now it is too late to change it.\n> \n> > By removing the experimental marker, we help clarify the stability and\n> > maturity of these commands.\n> \n> So, even though I may agree with the conclusion that we no longer\n> would allow ourselves to break backward compatibility for these two\n> commands, I doubt that it is stability and maturity to celebrate\n> about. It (not the \"have two speparate commands\" part, but \"leave\n> ourselves room to improve these two commands\" part) was a clearly\n> failed experiment.\n\nThat's fair. The wording should probably be toned down here. My intent\nis really just to indicate that users will likely be more inclined to\nuse these commands if they are not marked as experimental.\n\nThanks for the review. I'll give it some time to collect for feedback\nand then submit a follow up version. \n\n-Justin\n"},{"id":"522881","messageId":"20250728194218.2379432-1-jltobler@gmail.com","threadId":"63825","inReplyTo":"20250722180818.1043014-1-jltobler@gmail.com","subject":"[PATCH] builtin: unmark git-switch and git-restore as experimental","fromName":"Justin Tobler","fromEmail":"jltobler@gmail.com","sentAt":"2025-07-28T19:42:18Z","receivedAt":"2025-07-28T19:48:38Z","isPatch":true,"sender":{"key":"jltobler@gmail.com","avatar":"https://avatars.githubusercontent.com/u/53454972?v=4"},"body":"In 4e43b7ff (Declare both git-switch and git-restore experimental,\n2019-04-25), the newly introduced git-switch(1) and git-restore(1)\ncommands were marked as experimental. This was done to provide time to\nmake breaking changes to the interface. It has now been over six years\nsince these commands were implemented and there hasn't been much change.\nConsequently, users have grown to rely on how these commands work and it\nis no longer feasible to make any breaking changes.\n\nLet's remove the experimental label for git-switch(1) and\ngit-restore(1).\n\nSigned-off-by: Justin Tobler \n---\n Documentation/git-restore.adoc | 2 --\n Documentation/git-switch.adoc | 2 --\n 2 files changed, 4 deletions(-)\n\ndiff --git a/Documentation/git-restore.adoc b/Documentation/git-restore.adoc\nindex 877b7772e66..3763a7f4f43 100644\n--- a/Documentation/git-restore.adoc\n+++ b/Documentation/git-restore.adoc\n@@ -28,8 +28,6 @@ otherwise from the index. Use `--source` to restore from a different commit.\n See \"Reset, restore and revert\" in linkgit:git[1] for the differences\n between the three commands.\n \n-THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.\n-\n OPTIONS\n -------\n `-s `::\ndiff --git a/Documentation/git-switch.adoc b/Documentation/git-switch.adoc\nindex 9f62abf9e2b..87707e92652 100644\n--- a/Documentation/git-switch.adoc\n+++ b/Documentation/git-switch.adoc\n@@ -29,8 +29,6 @@ Switching branches does not require a clean index and working tree\n however if the operation leads to loss of local changes, unless told\n otherwise with `--discard-changes` or `--merge`.\n \n-THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.\n-\n OPTIONS\n -------\n __::\n-- \n2.50.1.214.ga30f80fde9\n\n"},{"id":"522897","messageId":"xmqq1pq0ujgu.fsf@gitster.g","threadId":"63825","inReplyTo":"20250728194218.2379432-1-jltobler@gmail.com","subject":"Re: [PATCH] builtin: unmark git-switch and git-restore as experimental","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-07-28T20:52:01Z","receivedAt":"2025-07-28T20:52:04Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Justin Tobler writes:\n\n> In 4e43b7ff (Declare both git-switch and git-restore experimental,\n> 2019-04-25), the newly introduced git-switch(1) and git-restore(1)\n> commands were marked as experimental. This was done to provide time to\n> make breaking changes to the interface. It has now been over six years\n> since these commands were implemented and there hasn't been much change.\n> Consequently, users have grown to rely on how these commands work and it\n> is no longer feasible to make any breaking changes.\n>\n> Let's remove the experimental label for git-switch(1) and\n> git-restore(1).\n>\n> Signed-off-by: Justin Tobler \n> ---\n> Documentation/git-restore.adoc | 2 --\n> Documentation/git-switch.adoc | 2 --\n> 2 files changed, 4 deletions(-)\n\nThanks for tying loose ends. This completely slipped my mind.\n\nWill queue. Thanks.\n\n> diff --git a/Documentation/git-restore.adoc b/Documentation/git-restore.adoc\n> index 877b7772e66..3763a7f4f43 100644\n> --- a/Documentation/git-restore.adoc\n> +++ b/Documentation/git-restore.adoc\n> @@ -28,8 +28,6 @@ otherwise from the index. Use `--source` to restore from a different commit.\n> See \"Reset, restore and revert\" in linkgit:git[1] for the differences\n> between the three commands.\n> \n> -THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.\n> -\n> OPTIONS\n> -------\n> `-s `::\n> diff --git a/Documentation/git-switch.adoc b/Documentation/git-switch.adoc\n> index 9f62abf9e2b..87707e92652 100644\n> --- a/Documentation/git-switch.adoc\n> +++ b/Documentation/git-switch.adoc\n> @@ -29,8 +29,6 @@ Switching branches does not require a clean index and working tree\n> however if the operation leads to loss of local changes, unless told\n> otherwise with `--discard-changes` or `--merge`.\n> \n> -THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.\n> -\n> OPTIONS\n> -------\n> __::\n"}]}