如何撤销 Git add 操作但保留本地文件修改

如果你已经执行了 git add 但还没 commit，想要取消暂存同时保留本地修改，最推荐的做法是使用 git restore `--staged` 命令（Git 2.23 及以上版本），或者兼容旧版本的 git reset HEAD 命令。

先说结论：这两个命令只操作暂存区，不会删除工作目录的文件内容。

命令速用版

根据你的 Git 版本和习惯，选择以下任一命令即可。注意将 <file> 替换为实际文件名，或使用 . 代表所有文件。

方案一：新版推荐（Git 2.23+）

git restore `--staged` <file>
# 撤销所有暂存文件
git restore `--staged` .

方案二：旧版兼容（所有版本）

git reset HEAD <file>
# 撤销所有暂存文件
git reset HEAD

步骤 1：检查当前状态

在执行撤销前，先确认哪些文件被暂存了。

git status

查看输出中 Changes to be committed 部分列出的文件。

步骤 2：执行撤销命令

如果要撤销特定文件：

git restore `--staged` example.txt

如果要撤销所有已 add 的文件：

git restore `--staged` .

步骤 3：再次检查状态

执行后再次运行 git status，确认文件已移回 Changes not staged for commit 区域，且文件内容未丢失。

执行完撤销命令后，通过以下两点验证：

状态检查：运行 git status，原本在 Changes to be committed 下的文件应出现在 Changes not staged for commit（已修改未暂存）或 Untracked files（如果是新文件）下。
内容检查：打开文件确认本地修改依然存在，没有被还原到上一次提交的状态。

1. 误用 `--hard` 参数

千万不要使用 git reset `--hard`。该命令会同时重置暂存区和工作区，导致你本地未提交的修改被永久删除。

2. 新文件的状态变化

如果是第一次添加的新文件（之前未 tracked），撤销暂存后，它会变成 Untracked 状态。这不代表文件丢失，只是 Git 不再跟踪它，下次 commit 需要重新 add。

3. 版本兼容性

git restore 是较新的命令。如果在旧版 Git 环境（如某些老旧服务器）中运行报错，请改用 git reset HEAD。

问题 1：命令找不到 (command not found)

如果运行 git restore 提示未知命令，说明 Git 版本低于 2.23。请使用兼容命令：

git reset HEAD <file>

问题 2：路径不匹配 (pathspec did not match)

如果提示错误，通常是因为文件路径写错了。先运行 git status 查看文件的准确相对路径，再执行撤销命令。注意不要带上多余的斜杠或错误的前缀。