What does git checkout still do after git switch got introduced?

Question

As everyone knows, git checkout is a very overloaded command. And I do understand that certain commands got introduced to distribute, e.g. to git switch.

Before I used the following commands:

$ git checkout <existing-branch>
$ git checkout <hash>
$ git checkout -b <new-branch-name>

So I am wondering after git switch got introduced, what is the left purpose of git-checkout? Is this a deprecated command?

Answer 1

Git 2.46 (Q3 2024), batch 15 confirms: git checkout is here to stay.

See commit 028bb23, commit fcf0f48, commit 6ccf041, commit 57ec925 (14 Jun 2024) by Patrick Steinhardt (pks-t).
^{(Merged by Junio C Hamano -- gitster -- in commit 166cdd8, 20 Jun 2024)}

BreakingChanges: document that we do not plan to deprecate git-checkout

^{Signed-off-by: Patrick Steinhardt}

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.

BreakingChanges now includes in its man page:

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

And:

docs: introduce document to announce breaking changes

^{Signed-off-by: Patrick Steinhardt}

Over time, Git has grown quite a lot.
With this evolution, many ideas that were sensible at the time they were introduced are not anymore and are thus considered to be deprecated.
And while some deprecations may be noted in manpages, most of them are actually deprecated in the "hive mind" of the Git community, only.

Introduce a new document that tracks such breaking changes, but also deprecations which we are not willing to go through with, to address this issue.
This document serves multiple purposes:

• It is a way to facilitate discussion around proposed deprecations.
• It allows users to learn about deprecations and speak up in case they have good reasons why a certain feature should not be deprecated.
• It states intent and documents where the Git project wants to go, both in the case where we want to deprecate, but also in the case where we don't want to deprecate a specific feature.

BreakingChanges now includes in its man page:

Upcoming breaking changes

The Git project aims to ensure backwards compatibility to the best extent possible. Minor releases will not break backwards compatibility unless there is a very strong reason to do so, like for example a security vulnerability.

Regardless of that, due to the age of the Git project, it is only natural to accumulate a backlog of backwards-incompatible changes that will eventually be required to keep the project aligned with a changing world. These changes fall into several categories:

• Changes to long established defaults.
• Concepts that have been replaced with a superior design.
• Concepts, commands, configuration or options that have been lacking in major ways and that cannot be fixed and which will thus be removed without any replacement.

Explicitly not included in this list are fixes to minor bugs that may cause a change in user-visible behavior.

The Git project irregularly releases breaking versions that deliberately break backwards compatibility with older versions. This is done to ensure that Git remains relevant, safe and maintainable going forward. The release cadence of breaking versions is typically measured in multiple years. We had the following major breaking releases in the past:

• Git 1.6.0, released in August 2008.
• Git 2.0, released in May 2014.

We use <major>.<minor> release numbers these days, starting from Git 2.0.
For future releases, our plan is to increment <major> in the release number when we make the next breaking release.
Before Git 2.0, the release numbers were 1.<major>.<minor> with the intention to increment <major> for "usual" breaking releases, reserving the jump to Git 2.0 for really large backward-compatibility breaking changes.

The intent of this document is to track upcoming deprecations for future breaking releases.
Furthermore, this document also tracks what will not be deprecated. This is done such that the outcome of discussions documents both when the discussion favors deprecation, but also when it rejects a deprecation.

Git 3.0

Superseded features that will not be deprecated

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.

Answer 2

It's retained at least for backward compatibility. Think about millions of scripts that still use git checkout — should we hurry to rewrite all of them? Certainly no.

It's not even deprecated, actually. There is nothing about deprecation in the docs. On the other hand the docs for git restore and git switch say "THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE."