git-checkout

Create and switch to a new branch

$ git checkout -b [branch_name]

$ git checkout -b [branch_name] [reference]

$ git checkout [branch_name]

$ git checkout -

$ git checkout [[-t|--track]] [remote_name]/[branch_name]

$ git checkout .

$ git checkout [path/to/file]

$ git checkout [branch_name] -- [path/to/file]

git checkout []
git checkout []
git checkout [] [--] ...
git checkout [] [--] ...
git checkout -b|-B []
git checkout -p [] [--] [...]

-b <new-branch>
    Create a new branch named <new-branch> and switch to it.

-B <new-branch>
    Create or reset a branch named <new-branch> and switch to it. If the branch already exists, it will be reset.

--track | -t
    When creating a new branch, set it up to track an upstream branch.

--force | -f
    Force a checkout, even if the index or working tree has uncommitted changes that would be overwritten. Use with caution.

--detach
    Checkout a commit or tag, leaving HEAD in a detached state. This means you are not on any branch.

-p | --patch
    Interactively select hunks from the diff to checkout.

--ours
    When restoring files, take the version from 'ours' side of a merge (the current branch).

--theirs
    When restoring files, take the version from 'theirs' side of a merge (the branch being merged).

--orphan <new-branch>
    Create a new orphan branch, which starts with no history or files. Useful for initial commits or unrelated projects.

--quiet | -q
    Suppress most informational messages from the command.

--
    Used to separate command options from pathspecs, especially when a pathspec might be mistaken for an option.

The git checkout command is a versatile Git utility used primarily for navigating between branches, commits, or restoring files in your working directory. When used to switch branches, it updates the working tree to match the selected branch, also updating the Git index and moving the HEAD pointer. This allows you to work on different lines of development. When used with a pathspec, it restores specified files from a given tree-ish (like a branch, commit, or the index) into your working tree, or optionally into the index. It's a powerful tool but its dual functionality has led to the introduction of more specialized commands like git switch and git restore to simplify common operations.

The git checkout command is powerful but can be risky if used carelessly.

1. Overwriting Local Changes: Without the --force option, git checkout will refuse to switch branches or restore files if it would overwrite uncommitted local changes. However, if changes are staged, it might overwrite them without warning if they conflict with the checkout target.
2. Detached HEAD State: Checking out a commit hash or a tag will put Git into a 'detached HEAD' state. Any new commits made in this state will not belong to any branch, making them prone to being lost unless a new branch is explicitly created from them.
3. Ambiguous Usage: Due to its dual role (branch switching and file restoration), git checkout can be confusing. Modern Git versions (2.23+) introduce git switch for branch operations and git restore for file operations to provide a clearer, safer, and more intuitive interface. While git checkout still works, it's generally recommended to use the newer commands for their specific purposes.

When you checkout a specific commit hash, a remote-tracking branch, or a tag (e.g., git checkout <commit-hash>), you enter a 'detached HEAD' state. In this state, your HEAD pointer is pointing directly to a commit, not to a branch. This means any new commits you make will not automatically update any branch. To save new commits made in a detached HEAD state, you must create a new branch from your current HEAD (e.g., git branch <new-branch-name>).

As of Git 2.23, the functionality of git checkout has been logically split into two more intuitive commands: git switch for changing branches and git restore for restoring files from the index or another tree-ish. While git checkout still works, the new commands offer clearer semantics and are generally recommended for new users and modern workflows. For instance, instead of git checkout <branch>, use git switch <branch>; instead of git checkout -- <file>, use git restore <file>.

For a long time, git checkout served as the primary command for both switching branches and restoring files. Its original design was to be a single 'checkout' command that could manipulate both the HEAD and the working tree/index.

However, this dual functionality often led to confusion, especially for new users, as the same command had different behaviors depending on whether a branch/commit or a path was provided as an argument.

Recognizing this ambiguity and potential for user error, Git 2.23 (released in August 2019) introduced two new, more focused commands: git switch and git restore. These commands explicitly separate the responsibilities of git checkout. git switch handles branch operations, and git restore handles file restoration. While git checkout remains available for backward compatibility, its use for these specific tasks is largely superseded by the newer, clearer commands.

git-switch(1), git-restore(1), git-branch(1), git-reset(1), git-add(1)