| Message ID | 40594bda5c8050c2a863df8c9f6f92cd98ea8484.1717141598.git.ps@pks.im (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | docs: document upcoming breaking changes | expand |
Patrick Steinhardt <ps@pks.im> writes: > 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 neither of these commands will not go away anytime soon. "neither" -> "none"? It is accepted to use neither to pick among three things these days, but the latter is clearer.
Junio C Hamano wrote: > Patrick Steinhardt <ps@pks.im> writes: > >> 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 neither of these commands will not go away anytime soon. > > "neither" -> "none"? It is accepted to use neither to pick among > three things these days, but the latter is clearer. I think 'will not' should lose the 'not' as well: Document that neither|none of these commands will go away anytime soon. Alternately, the neither/none question could be resolved by dropping it entirely: Document that these commands will not go away anytime soon. I'm not sure that's better; it leaves ambiguity about what "these commands" includes. Maybe: Document that all three commands will remain for the foreseeable future. But after writing all that, I only just noticed this is in the commit message. And while that's important, the more important content of the change itself uses clear language to say all three commands will stay. :)
diff --git a/Documentation/BreakingChanges.md b/Documentation/BreakingChanges.md index 14c0972b08..fb2c8ddf5a 100644 --- a/Documentation/BreakingChanges.md +++ b/Documentation/BreakingChanges.md @@ -99,3 +99,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 superseded features. + + - 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 neither of these commands will not go away anytime soon. 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.md | 12 ++++++++++++ 1 file changed, 12 insertions(+)