What is the `git restore` command and what is the difference between `git restore` and `git reset`?

I have presented git restore (which is still marked as “experimental”) in “How to reset all files from working directory but not from staging area?“, with the recent Git 2.23 (August 2019).

It helps separate git checkout into two commands:

As reset, restore and revert documentation states:

There are three commands with similar names: git reset, git restore and git revert.

  • git-revert is about making a new commit that reverts the changes made by other commits.
  • git-restore is about restoring files in the working tree from either the index or another commit.
    This command does not update your branch.
    The command can also be used to restore files in the index from another commit.
  • git-reset is about updating your branch, moving the tip in order to add or remove commits from the branch. This operation changes the commit history.
    git reset can also be used to restore the index, overlapping with git restore.

So:

To restore a file in the index to match the version in HEAD (this is the same as using git-reset)

git restore --staged hello.c

or you can restore both the index and the working tree (this the same as using git-checkout)

git restore --source=HEAD --staged --worktree hello.c

or the short form which is more practical but less readable:

git restore -s@ -SW hello.c

With Git 2.25.1 (Feb. 2020), “git restore --staged” did not correctly update the cache-tree structure, resulting in bogus trees to be written afterwards, which has been corrected.

See discussion.

restore: invalidate cache-tree when removing entries with –staged

Reported-by: Torsten Krah
Signed-off-by: Jeff King

When “git restore --staged ” removes a path that’s in the index, it marks the entry with CE_REMOVE, but we don’t do anything to invalidate the cache-tree.
In the non-staged case, we end up in checkout_worktree(), which calls remove_marked_cache_entries(). That actually drops the entries from the index, as well as invalidating the cache-tree and untracked-cache.

But with --staged, we never call checkout_worktree(), and the CE_REMOVE entries remain. Interestingly, they are dropped when we write out the index, but that means the resulting index is inconsistent: its cache-tree will not match the actual entries, and running “git commit” immediately after will create the wrong tree.

We can solve this by calling remove_marked_cache_entries() ourselves before writing out the index. Note that we can’t just hoist it out of checkout_worktree(); that function needs to iterate over the CE_REMOVE entries (to drop their matching worktree files) before removing them.

One curiosity about the test: without this patch, it actually triggers a BUG() when running git-restore:

BUG: cache-tree.c:810: new1 with flags 0x4420000 should not be in cache-tree

But in the original problem report, which used a similar recipe, git restore actually creates the bogus index (and the commit is created with the wrong tree). I’m not sure why the test here behaves differently than my out-of-suite reproduction, but what’s here should catch either symptom (and the fix corrects both cases).

With Git 2.27 (Q2 2020), “git restore --staged --worktree” now defaults to take the contents out of “HEAD”, instead of erring out.

See commit 088018e (05 May 2020) by Eric Sunshine (sunshineco).
(Merged by Junio C Hamano — gitster — in commit 4c2941a, 08 May 2020)

restore: default to HEAD when combining –staged and –worktree

By default, files are restored from the index for --worktree, and from HEAD for --staged.

When --worktree and --staged are combined, --source must be specified to disambiguate the restore source, thus making it cumbersome to restore a file in both the worktree and the index.

(Due to an oversight, the --source requirement, though documented, is not actually enforced.)

However, HEAD is also a reasonable default for --worktree when combined with --staged, so make it the default anytime --staged is used (whether combined with --worktree or not).

So now, this works:

git restore --staged --worktree
git restore -SW

Related Posts:

  1. How do I use ‘git reset –hard HEAD’ to revert to a previous commit? [duplicate]
  2. How do I revert a Git repository to a previous commit?
  3. How do I revert a Git repository to a previous commit?
  4. What is difference between ‘git reset –hard HEAD~1’ and ‘git reset –soft HEAD~1’?
  5. How to undo git reset –soft to get my changes back?
  6. Move existing, uncommitted work to a new branch in Git
  7. How do I check out a remote Git branch?
  8. What is git tag, How to create tags & How to checkout git remote tag(s)
  9. What does ‘–set-upstream’ do?
  10. What does ‘–set-upstream’ do?
  11. What is the best (and safest) way to merge a Git branch into master?
  12. Squash my last X commits together using Git
  13. Git merge hotfix branch into feature branch
  14. Git submodule update
  15. How to apply a patch generated with git format-patch?
  16. Abort a Git Merge
  17. GitHub: Permission denied (publickey). fatal: Could not read from remote repository
  18. How to delete a remote tag?
  19. Updates were rejected because the tip of your current branch is behind its remote counterpart
  20. Updates were rejected because the tip of your current branch is behind its remote counterpart
  21. git stash apply version
  22. What does “Changes not staged for commit” mean
  23. git: fatal: Could not read from remote repository
  24. How do I update Homebrew?
  25. Git error when trying to push — pre-receive hook declined
  26. Ignoring directories in Git repositories on Windows
  27. How can I merge multiple commits onto another branch as a single squashed commit?
  28. Gitignore not working
  29. Could not open a connection to your authentication agent
  30. How to get just one file from another branch?
  31. git checkout a single file from another branch and put in different folder
  32. Update Git branches from master
  33. Stash only one file out of multiple files that have changed with Git?
  34. How to find my GitHub username so that I can be found via the URL?
  35. Create a branch in Git from another branch
  36. Create Git branch with current changes
  37. github website publish cannot publish unborn HEAD
  38. What is HEAD in Git?
  39. What are the differences between git remote prune, git prune, git fetch –prune, etc
  40. How to get the current branch name in Git?
  41. How can I git stash a specific file?
  42. What does git rev-parse do?
  43. git – pulling from specific branch
  44. How to name and retrieve a stash by name in git?
  45. GitHub: invalid username or password
  46. Why do I have to “git push –set-upstream origin “?
  47. Stash just a single file
  48. Stash just a single file
  49. Git – Ignore node_modules folder everywhere
  50. How to undo ‘git reset’?
  51. fatal: Not a valid object name: ‘master’
  52. Git and nasty “error: cannot lock existing info/refs fatal”
  53. How do I delete a local repository in git?
  54. git pull from master into the development branch
  55. Clone A Private Repository (Github)
  56. Throw away local commits in Git
  57. Hard reset of a single file
  58. How to remove remote origin from a Git repository
  59. .gitignore and “The following untracked working tree files would be overwritten by checkout”
  60. How do I copy a version of a single file from one Git branch to another?
  61. Git: cannot checkout branch – error: pathspec ‘…’ did not match any file(s) known to git
  62. Heroku: How to change a Git remote on Heroku
  63. Invalid VCS root mapping – 3 errors on my project
  64. Updates were rejected because the remote contains work that you do not have locally
  65. Undoing a ‘git push’
  66. What is the difference between pull and clone in git?
  67. How do I clone a single branch in Git?
  68. how to reset develop branch to master
  69. What does git push origin HEAD mean?
  70. “fatal: HttpRequestException encountered.” Error with GitHub/Bitbucket Repositories due to dropping TLS-1.0 support
  71. Git’s local repository and remote repository — confusing concepts
  72. How do I set up Eclipse/EGit with GitHub?
  73. Repository size limits for GitHub.com
  74. How do i git push specific branch?
  75. fatal: could not read Username for ‘https://github.com’: No such file or directory
  76. git push origin master does not work
  77. How can I see which Git branches are tracking which remote / upstream branch?
  78. git undo all uncommitted or unsaved changes
  79. Git clone verbose output?
  80. TortoiseGit-git did not exit cleanly (exit code 1)
  81. How to answer the git prompt in npm init for a local repo
  82. How to `git pull` while ignoring local changes?
  83. Uninitialize git repository
  84. How to create a local branch from an existing remote branch?
  85. Git says “Automatic merge failed”, what does it mean?
  86. How do I clone a subdirectory only of a Git repository?
  87. How to configure git bash command line completion?
  88. What is the .git folder?
  89. How to stop tracking and ignore changes to a file in Git?
  90. Updating and committing only a file’s permissions using git version control
  91. Create empty branch on GitHub
  92. Git – fatal: Unable to create ‘/path/my_project/.git/index.lock’: File exists
  93. What is the usual process of saving changes made at the CMS level into source control?
  94. Collaboratively develop a WordPress site
  95. Pull latest stable release via git [closed]
  96. Why do the Roots theme CSS files not load (404)?
  97. WordPress Core files not being ignored by Git
  98. Painless way to track remote Git repo for WordPress updates
  99. WordPress on git – need help with configuration
  100. Full site editor, hard-coded IDs in query blocks, and staging/dev servers

Leave a Comment