如何使用Git的Checkout命令撤销本地未提交的代码修改？

本文共计977个文字，预计阅读时间需要4分钟。

在Git 2.23版本中，`git checkout`已被标记为过时，官方推荐使用`git restore`来替代。然而，许多团队仍在使用旧版Git，且`git checkout`在处理未暂存的（unstaged）文件时可能会产生误操作——它不会提示确认，直接覆盖工作区文件内容。

执行 git checkout -- <file> 会把该文件恢复到 HEAD 版本（即最近一次 commit 的状态），所有本地编辑、新增行、删减都会被清空，且无法通过 git reflog 恢复（因为没产生新引用）。

• 只对已跟踪（tracked）文件生效；对 git status 显示为 Untracked files: 的新文件无效
• 如果文件有暂存（staged）修改，git checkout -- <file> 会同时丢弃暂存区和工作区改动
• 路径必须存在，否则报错：error: pathspec 'xxx' did not match any file(s) known to git

撤销单个文件用 git checkout -- filename

这是最常见也最容易出错的操作场景：改了一个配置文件，想退回上一版，但忘了自己刚加了三行调试日志。

命令格式固定：git checkout -- <code>src/config.js（注意双横线和空格）

• 双横线 -- 是分隔符，防止文件名被误解析为分支名（比如文件叫 main）
• 不加 -- 可能触发分支切换（如 git checkout main），导致意外切换当前分支
• 若文件已暂存，建议先 git reset HEAD <code>src/config.js 再 git checkout -- <code>src/config.js，避免误删暂存内容

批量撤销多个文件或整个目录

不能直接写 git checkout -- src/ —— Git 默认不支持通配符展开，会报错 pathspec 'src/' did not match any file。

正确做法是让 shell 展开通配符，例如：

git checkout -- src/*.js

或者用 find 配合 xargs（Linux/macOS）：

find src -name "*.ts" -type f | xargs git checkout --

• Windows PowerShell 用户需改用 Get-ChildItem + %{ git checkout -- $_.FullName }
• 路径中含空格时，xargs -d '\n' 更安全；否则可能因空格截断路径
• 不建议对整个项目根目录执行 git checkout -- .，除非你明确要丢弃所有未提交改动

Git 2.23+ 应该优先用 git restore

新版 Git 把恢复操作语义拆得更清楚：git restore 专用于撤销工作区/暂存区，git switch 专用于切换分支。这减少了 git checkout 一命令多职带来的混淆。

等效替代如下：

• 撤销单个未暂存文件：git restore <code>src/config.js
• 撤销暂存区（保留工作区）：git restore --staged <code>src/config.js
• 同时撤销暂存区和工作区：git restore -s HEAD -S -W <code>src/config.js（-s 指定源 commit，-S 撤暂存，-W 撤工作区）

关键是 git restore 默认只影响工作区，行为更可预期；而 git checkout -- 一旦敲错路径或漏写 --，就可能切分支或报错中断流程。

真正危险的不是命令本身，而是没看清 git status 输出里哪些是 modified:、哪些是 deleted:、哪些是 untracked: —— 撤销前扫一眼，比记住所有参数更重要。