patch, 2 partsbuiltin: 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]: <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

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

Justin Tobler <jltobler@gmail.com> writes:

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.

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.

On 25/07/22 01:54PM, Junio C Hamano wrote:

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.

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

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

Justin Tobler <jltobler@gmail.com> writes:

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.

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.

On 25/07/22 02:00PM, Junio C Hamano wrote:

Will update in the next version.

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

Thanks, -Justin

Justin Tobler <jltobler@gmail.com> writes:

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

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

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.

On 25/07/22 01:22PM, Junio C Hamano wrote:

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

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

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

Justin Tobler <jltobler@gmail.com> writes:

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

Will queue.  Thanks.