为何`git checkout`文档称保留工作树本地修改，实际却报错中止？

先明确文档描述的适用前提：只有当你本地修改的文件，在当前分支和目标<branch>分支中的版本完全一致时，Git才会保留你的本地修改并完成分支切换，这也是文档里“工作树文件的本地修改将被保留，以便可提交至<branch>分支”的真实含义。

分两种场景具体说明：

• 场景一：如果某个文件在当前分支和目标分支的内容完全相同，你在本地对该文件做了修改，执行git checkout [<branch>]时，Git不会去覆盖这个文件，你的修改会被直接带到目标分支中，后续可以正常提交到目标分支。
• 场景二：如果同一个文件在当前分支和目标分支里的版本存在差异，而你本地又修改了这个文件，此时Git无法自动判断应该保留你的本地修改还是应用目标分支的版本，为了避免你的修改被意外覆盖，Git会直接报错并中止切换操作。

简单来说，文档的描述没有错误，只是省略了前提条件。Git报错不是“不保留修改”，而是在存在版本冲突的场景下，用报错的方式保护你的本地修改不被丢失或覆盖。

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