关于git reset --merge文档与实际行为不符的技术问询

问题背景 #

怀疑git reset --merge的官方文档表述存在问题，引用官方文档内容：

重置索引并更新工作树中在<commit>与HEAD之间存在差异的文件，但保留索引与工作树之间存在差异的文件（即未暂存的更改）。如果在<commit>与索引之间存在差异的文件有未暂存更改，reset会中止。

核心疑问：仅看第一句，是否意味着<commit>与HEAD之间无差异的文件不会被回滚到工作目录？

但测试脚本中，文件a在HEAD与HEAD~1之间无差异，执行git reset --merge HEAD~1后，a的内容却被重置了。

测试脚本：

#!/bin/bash
git init
echo 1 > a
echo 1 > b
git add .
git commit -m 1
echo 2 > b
git add .
git commit -m 2
echo 3 > a
echo 3 > b
git add .
git reset --merge HEAD~1
cat a
cat b
rm -rf .git

原因分析 #

要理解这个行为，得拆解git reset --merge的实际逻辑：

• git reset --merge <commit>的本质是：将HEAD移动到<commit>，同时让索引和工作树匹配<commit>的状态，但仅保留执行reset前工作树与索引存在差异的文件（未暂存修改）。
• 测试中执行git add .后，文件a和b的修改都被暂存，此时索引与工作树完全一致，没有未暂存更改。
• 对于文件a，虽然HEAD（commit 2）与HEAD~1（commit 1）之间无差异，但当前索引中的a是修改后的内容（值为3），而目标<commit>（HEAD~1）中的a值为1。因为没有未暂存修改需要保留，所以git reset --merge会将索引和工作树的a回滚到HEAD~1的状态。

官方文档的表述容易产生误解，关键遗漏了“仅当文件存在未暂存修改时才保留”这个前提。它的第一句没有明确说明：如果文件的工作树与索引一致，不管HEAD和目标commit之间是否有差异，都会被重置到目标commit的状态。

结论 #

官方文档的表述确实不够精准，容易误导用户忽略“未暂存修改”这个保留条件。在测试场景中，由于a的工作树与索引已一致，git reset --merge HEAD~1会将a从索引和工作树都回滚到HEAD~1的状态，这符合命令的实际逻辑，只是文档表述未明确说明该前提。

内容的提问来源于stack exchange，提问作者avenir