
某个日志文件没有出现在 git status 里,原因可能是被规则忽略,也可能是它早已进入版本控制。只盯着 .gitignore 搜文件名不一定找得到答案:规则可能是通配符,路径也可能来自更具体的规则。git check-ignore -v 可以把匹配结果连同规则位置打出来;碰上已跟踪文件,还要知道它默认会跳过 index 中的路径。
-v 把规则来源打印出来
脚本在系统临时目录创建了一个本地仓库,没有改博客仓库,也没有访问网络。提交一个 tracked.log 后,再添加只含 *.log 的 .gitignore,另建一个未跟踪的 fresh.log。用 git check-ignore -v fresh.log 得到:
== fresh.log: verbose match ==
exit: 0
stdout: .gitignore:1:*.log fresh.log
== tracked.log: default index-aware check ==
输出里的 .gitignore 是规则文件,1 是行号,*.log 是匹配模式,最后的 fresh.log 是被查询路径。这里返回码为 0,说明该未跟踪路径被忽略。这个结果把「哪个模式生效」落到了具体位置,不用先猜它来自根目录配置、子目录文件还是其他规则文件。
排查时可直接对可疑路径运行:
git check-ignore -v -- path/to/file
路径前的 -- 用来结束选项解析,路径名即使以连字符开头也不容易被当成参数。-v 只展示命中来源,不会改动仓库状态。若没有匹配结果,命令以非零状态结束;在脚本里不应把「没有忽略命中」误报成命令故障,可以按返回码分开处理。这个区别在批量检查时尤其重要:返回 1 通常表示被查询路径没有被忽略,不代表 Git 程序崩溃。若包装脚本要继续扫描其他文件,应分别收集命中和未命中结果,再把真正的执行错误单独报告。路径要写成仓库内实际存在或待生成的目标,不要只查询一个目录名就推断目录下每个文件都受到同一条规则影响。
已跟踪路径要加 --no-index
实验里的 tracked.log 也符合 *.log,但它在规则出现前已经提交。普通的 git check-ignore -v tracked.log 返回 1,输出为空;.gitignore 里有这条模式,默认检查仍会跳过已经被 index 跟踪的路径。加上 --no-index 后,Git 按忽略规则检查,不再因跟踪状态跳过它,结果变成 .gitignore:1:*.log。
这两个命令回答的问题不同:默认形式检查「这条路径是否作为未跟踪内容被忽略」,带 --no-index 的形式则用来诊断「忽略规则会不会匹配它」。后者不会把文件从版本控制里移走,也不会让已提交文件停止出现在后续提交中。若目标是停止跟踪,需另行处理索引;不要把 --no-index 当成修复忽略状态的开关。
同理,看到文件仍在 git status 里,也不能直接断定 .gitignore 失效。对已跟踪文件,先用 git ls-files -- path/to/file 确认它是否处于索引中,再用 git check-ignore -v --no-index -- path/to/file 看规则。一个命令查跟踪事实,另一个查规则匹配,分开看会更清楚。改动已跟踪文件后,git status 仍会列出它的修改;忽略规则不会撤销之前的跟踪状态。检查命令给出的模式命中信息,解释的是规则与路径的关系,不会改变 Git 对该路径的版本管理记录。
脚本最终确认 tracked.log 仍由 git ls-files 列出,默认检查无匹配输出,禁用 index 检查则命中第 1 行。实验验证的是一个仓库级通配规则,不代表所有忽略文件的优先级组合;遇到多层规则时,-v 输出的来源才是继续核对的起点。我会先区分路径是否已经跟踪,再决定要不要加 --no-index,否则很容易把索引状态误判为忽略规则失效。验证脚本是 tools/verify-git-check-ignore-20261116.py,完整输出保存在 tools/git-check-ignore-rules.log。