Ditch Git Checkout: Use Git Switch and Git Restore Instead

If you use Git in your daily work, git checkout is a common command. It's often used to switch branches, and if you look at the documentation, you can see the phrase "switch branches or restore working tree files". But UNIX should be Do One Thing and Do It Well. This was confusing, so Git 2.23 brought a pair of commands to replace it.

---

Before introducing how it works, we need to briefly understand its associated Git concepts.

• Working copy (working tree file): It refers to the file in the repository that appears on the hard disk.

• Index (staging area or cache): it refers to you have git add-ed, or, what would be committed if you were to run git commit.

• HEAD: It refers to the “current” or “active” branch, when we need to check out a branch (referring to your attempt to match the branch with what is in the working copy), only one can be checked out at a time.

git checkout can checkout a branch or create a new branch and checkout into it:

# Switched to branch 'test'
$ git checkout test

# Switched to a new branch 'test'
$ git checkout -b test

# Switch back to the previous branch
$ git checkout -

# Switched to a commit
$ git checkout master~1

And git switch is used to take over branch related, so it can also do:

# Switched to branch 'test'
$ git switch test

# Switched to a new branch 'test'
$ git switch -c test

# Switch back to the previous branch
$ git switch -

# Switched to a commit
$ git switch -d master~1

And as we said at the beginning, git checkout can also restore working tree files. This part of the feature is taken over by git restore.

In the past, we could use git checkout -- main.c to restore the working tree file from the index, the syntax was git checkout [treeish] -- <filename>, where treeish could be specified as the source. Simple examples:

# Restoring the working tree from the index
$ git checkout -- ./main.c

# Restoring index content from HEAD
$ git reset -- ./main.c

# Restoring the working tree and index from HEAD
$ git checkout HEAD -- ./main.c

Note that when restoring index content from HEAD, we can only use git reset, and git checkout has no corresponding option.

Show with a graph:

git restore makes it easier to determine which files will be restored, and where they will be restored. The following options specify the restore location:

-W
--worktree
-S
--staged

By default, -W and --worktree will restore the working tree from the index, the same as if no options were specified (like git restore -- ./main.c ). Whereas -S and --staged will restore the index contents from HEAD. When passing both, the index and working tree will be restored from HEAD.

For instance:

# Restoring the working tree from the index
$ git restore -- ./main.c
# Equivalent to
$ git restore --worktree -- ./main.c

# Restoring index content from HEAD
$ git restore --staged -- ./main.c

# Restoring the working tree and index from HEAD
$ git restore --staged --worktree ./main.c

Show with a graph:

The above-mentioned is the default, if we want to restore from a different commit, we can use the --source option. E.g:

# Restore `./main.c` in the working tree with the last commit
$ git restore -s HEAD^ -- ./main.c
# Equivalent to
$ git restore --source=HEAD^ -- ./main.c

Another useful git restore case might be restoring a mishandled file. E.g:

# Incorrectly deleted files
$ rm -f ./main.c

# Quickly restore main.c from index
$ git restore ./main.c

For batch recovery:

# Restore all C source files to match the version in the index
$ git restore '*.c'

# Restore all files in the current directory
$ git restore .

# Restore all working tree files with top pathspec magic
$ git restore :/

Conclusion

The features of git checkout are clearly separated: git switch is used to switch branches, while git restore is used to restore working tree files. They provide more explicit semantics, in line with the UNIX philosophy.

Both commands were proposed in 2019, and as of now, they are experimental. There may be changes, but usually not by much, so you can use them now, they are easier to understand and less confusing.

If you found this helpful, please consider subscribing to my newsletter for more useful articles and tools about web development. Thanks for reading!