| Message ID | 9ff94b6f320d76e6b7c767e855038f33b69f4155.1717402497.git.ps@pks.im (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | docs: document upcoming breaking changes | expand |
Patrick Steinhardt <ps@pks.im> writes: > + > +* git-restore(1) and git-switch(1) have been introduced as a replacement for > + git-checkout(1). As git-checkout(1) is quite established, and as the benefit > + of switching to git-restore(1) and git-switch(1) is contended, all three > + commands will stay. "As a replacement" is probably a bit different from the truth [*], but I suspect that the reason why they were introduced no longer has much relevance. How about The features git-checkout(1) offers are covered by the pair of commands git-restore(1) and git-switch(1). Because the use of git-checkout(1) is still widespread, and it is not expected that this will change anytime soon. or something (borrowing from your proposed log message)? [Footnote] * If we were to mention the history behind the introduction, we'd end up saying: as an experiment, we introduced the pair of commands that do different half of the original command to see if they can replace the original. The decision to keep the original would lead to implication that this was a failed experiment, which makes people (unnecessarily) wonder if the failed experiment should be removed. I am trying to avoid such unnecessary implication here.
On Mon, Jun 03, 2024 at 09:52:33AM -0700, Junio C Hamano wrote: > Patrick Steinhardt <ps@pks.im> writes: > > > + > > +* git-restore(1) and git-switch(1) have been introduced as a replacement for > > + git-checkout(1). As git-checkout(1) is quite established, and as the benefit > > + of switching to git-restore(1) and git-switch(1) is contended, all three > > + commands will stay. > > "As a replacement" is probably a bit different from the truth [*], > but I suspect that the reason why they were introduced no longer has > much relevance. How about > > The features git-checkout(1) offers are covered by the pair of > commands git-restore(1) and git-switch(1). Because the use of > git-checkout(1) is still widespread, and it is not expected that > this will change anytime soon. > > or something (borrowing from your proposed log message)? Fair enough, let's add it like this. Thanks! Patrick
diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt index b5088dcce2..3c38676f49 100644 --- a/Documentation/BreakingChanges.txt +++ b/Documentation/BreakingChanges.txt @@ -101,3 +101,15 @@ Some features have gained newer replacements that aim to improve the design in certain ways. The fact that there is a replacement does not automatically mean that the old way of doing things will eventually be removed. This section tracks those features with newer alternatives. + +* git-restore(1) and git-switch(1) have been introduced as a replacement for + git-checkout(1). As git-checkout(1) is quite established, and as the benefit + of switching to git-restore(1) and git-switch(1) is contended, all three + commands will stay. ++ +This decision may get revisited in case we ever figure out that there are +almost no users of any of the commands anymore. ++ +Cf. <xmqqttjazwwa.fsf@gitster.g>, +<xmqqleeubork.fsf@gitster.g>, +<112b6568912a6de6672bf5592c3a718e@manjaro.org>.
The git-checkout(1) command is seen by many as hard to understand because it connects two somewhat unrelated features: switching between branches and restoring worktree files from arbitrary revisions. In 2019, we thus implemented two new commands git-switch(1) and git-restore(1) to split out these separate concerns into standalone functions. This "replacement" of git-checkout(1) has repeatedly triggered concerns for our userbase that git-checkout(1) will eventually go away. This is not the case though: the use of that command is still widespread, and it is not expected that this will change anytime soon. Document that all three commands will remain for the foreseeable future. This decision may be revisited in case we ever figure out that most everyone has given up on any of the commands. Signed-off-by: Patrick Steinhardt <ps@pks.im> --- Documentation/BreakingChanges.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+)