git clean清除未跟踪文件的用法【实战】

git clean清除未跟踪文件的用法【实战】

git clean -n 为什么必须先跑一遍

不预览就直接执行清理，无异于在工作区里直接敲下 rm -rf .。Git 的设计者显然考虑到了这一点，所以默认情况下，git clean 会拒绝执行任何操作，必须加上 -f 参数才能强制它干活。但请注意，这个 -f 只是绕过了 Git 的“确认提示”，它并不能防止你误删重要文件。

真正的安全阀是 -n 参数，也就是 --dry-run（模拟运行）。运行这个命令后，Git 会列出所有即将被删除的条目，并且每一行都会以 Would remove 这个明确的前缀开头。记住这个前缀：只有带它的项目才会被真正删除。如果看到 Skipping repository 这样的提示，那说明遇到了 Git 子模块，git clean 会出于安全考虑跳过它。

• 执行 git clean -dn 可以同时预览将被删除的目录和文件。
• 加上 -x 参数（例如 git clean -dxn）会额外显示那些被 .gitignore 规则忽略的项，比如常见的 __pycache__/、logs/ 或训练产生的 checkpoints/ 目录。
• Windows 用户如果遇到 unable to delete 错误，大概率是路径过长或包含特殊字符，可以尝试提前运行 git config --system core.longpaths true 来解决问题。

删目录必须加 -d，但 -d 单独用没效果

这里有个容易让人困惑的点：git clean 默认只清理未跟踪的文件，对于未跟踪的目录，它会完全无视。这并非 Bug，而是 Git 的一项安全设计。它假设那些空目录，或者里面装着文件的目录，可能是你手动创建但忘了加入版本控制的重要数据，比如本地配置文件、导出的报告或者临时生成的 SQL 文件。

只有加上 -d 参数，才会启用目录清理功能。不过，它依然受到其他规则的限制：

• -d 必须和 -f 一起使用，否则 Git 会报错并要求你再次确认，这是另一道安全关卡。
• 即使加了 -d，被 .gitignore 明确忽略的目录（哪怕里面非空）也不会被删除。如果想连这些目录一并清理，需要再加上 -x 参数。
• 如果目录里包含 Git 子模块（即存在 .git 子目录），-d 依然会跳过。想要强制删除，得用 -ff（两个 -f），但在绝大多数场景下，我们并不需要这么做。

什么时候该用 -x，什么时候该用 -X

这两个参数仅大小写之差，行为却天差地别，混用极易导致“翻车”事故。

-x 的意思是“连 .gitignore 里列出的文件/目录也一并删除”。这适用于需要彻底重建环境的场景，比如持续集成（CI）流水线中清理构建产物，或者 PyTorch 训练结束后清空 checkpoints/ 和 tensorboard/ 目录。而 -X 则恰恰相反，它的行为是“只删除那些被 .gitignore 忽略的文件”，同时会放过那些既没有被忽略、也没有被 Git 跟踪的“手动文件”，比如你临时编写的 debug.py 脚本。

• 日常清理日志、缓存、编译输出等通用垃圾，推荐使用 git clean -fdx。
• 如果只想清理团队约定俗成、写在 .gitignore 里的构建产物（同时保留自己随手创建的测试文件），那么应该用 git clean -fdX。
• 需要注意一个细节：当使用 -X 参数时，-d 参数是无效的——-X 只处理文件，不处理目录。

路径限定比全局清理更安全

不要一上来就习惯性地输入 git clean -fdx 进行全局扫荡。尤其是在团队协作的项目中，.gitignore 规则可能没有同步完整，或者存在一些你不知道的、项目特定的忽略项，全局删除很容易误伤。

更稳妥、更精准的做法是指定清理的路径范围：

• 只想清理 Python 缓存：git clean -fd __pycache__/ .ipynb_checkpoints/
• 只想清理构建输出目录：git clean -fdx build/ dist/ *.o
• 当指定了路径参数后，-d 参数会自动生效，无需额外添加。
• 路径支持通配符，但要注意 Shell 可能会提前展开通配符，建议用引号包裹起来：git clean -fn "logs/*.log"

最后，还有一个最常被忽略的黄金法则：在执行清理前，务必确认当前分支没有未提交的变更，或者已经用 git stash 暂存起来了。因为 git clean 只认“未跟踪”状态，它不管文件是否在暂存区或已提交。如果你刚刚修改了一个配置文件却忘了执行 git add，那么 git clean 会毫不犹豫地把它当作垃圾清理掉。