如何排查避免git中未跟踪文件在更新时被覆盖的问题？

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

错误提示中列出的 `untracked working tree files` 是实际存在的文件，不是 Git 虚拟的。直接运行 `git status` 就可以确认——这些文件既没有被 `git add` 过，也没有出现在 `.gitignore` 文件中。Git 完全看不见它们，但目标分支上可能有同名文件，所以请避免覆盖。

注意：有些文件看似是构建产物（比如 __pycache__、build/、target/），却因漏配 .gitignore 而成了未跟踪文件。这类文件最常引发问题，也最容易误删。

git clean -n 是必走的一步

git clean -n 不删任何东西，只告诉你“如果真删，会动哪些文件”。这步跳过等于闭眼操作。

• git clean -n：列出所有将被删除的未跟踪文件和目录
• git clean -n -x：额外包含被 .gitignore 忽略掉的文件（比如编译中间文件）
• 如果输出里出现你认识且需要的文件（比如临时配置、测试数据），立刻停手，换其他方法

删、stash、add，选哪个取决于文件用途

不能一概而论“清掉就完事”，得看文件性质：

• 是 __pycache__/、node_modules/、dist/ 这类生成物？→ 用 git clean -fd 或 git clean -fdx（加 -x 才清忽略项）
• 是你刚写的代码、还没想好提交信息？→ 用 git stash -u（-u 表示带上未跟踪文件）
• 是必须保留且要进版本库的配置或脚本？→ 先 git add <file>，再 git commit，否则下次切分支还会卡住

别用 git checkout -f 图省事——它不区分“未跟踪”和“已修改”，会直接丢弃所有本地改动，包括你刚改了三小时还没 git add 的文件。

预防比修复更省时间

这个问题反复出现，往往不是操作不对，而是工作流缺了关键动作：

• 新建项目后第一件事：写好 .gitignore，把语言/框架的典型构建目录全列进去
• 每次 git pull 或 git checkout 前，顺手敲一行 git status，扫一眼有没有红色（未跟踪）条目
• IDE 自动生成的文件（如 VS Code 的 .vscode/、PyCharm 的 .idea/）一旦漏进工作区，就立刻 git clean -f 或补进 .gitignore

真正容易被忽略的是：Git 不会主动提醒你哪些文件该 ignore，它只在冲突时才报错。等报错再处理，已经晚了一步。