git check-ignore 回答一个很具体的问题：这个文件到底被哪条忽略规则挡住了？配合 -v，它会直接输出「哪个文件、第几行、哪条规则」，排查 .gitignore 时比反复 git status 猜快得多。

本文把 git check-ignore 的常用参数与 .gitignore 的规则语法一起整理，作为第一轮基础命令的收尾。

ℹ️
关于本系列
本文是《Git 使用教程》按命令拆分的第 28 / 28 篇，全部收录在 Git 栏目。参数表列的是日常高频项，并非穷举；想看某个命令的完整参数，用 git check-ignore -h 看精简列表、git help check-ignore 看完整手册。示例以 Git 2.56.0 为准。

一、命令语法

先看语法骨架，再对照下一节的参数表。<占位> 表示必填值，实际输入时不要带尖括号；[...] 表示可选项，-- 用来分隔选项与路径。

bash语法
git check-ignore [<options>] <pathname>...
git check-ignore [<options>] --stdin

二、参数逐项详解

下表按用途列出 git check-ignore 的常用参数，每项都注明了「它到底改变了什么」。

参数作用
-v / --verbose输出「配置文件:行号:规则   路径」，排查首选
--no-index不查索引，纯粹按忽略规则判断路径（已跟踪文件也能查）
-n / --non-matching把没有被忽略的路径也列出来，配合 -v 看全貌
-q / --quiet不输出，只用退出码表示是否命中（0 命中 / 1 未命中），适合脚本
-zNUL 分隔输出，处理含空格或换行的文件名
--stdin从标准输入逐行读路径，批量检查时用
--分隔选项与路径

.gitignore 规则语法速查

写法匹配规则
# 注释井号开头为注释行
*.log任意目录下的 .log 文件
/config.php只忽略仓库根目录下的 config.php
build/任意层级的 build 目录，结尾斜杠表示目录
doc/*.txt单星不跨目录，只匹配 doc 下第一层
doc/**/*.pdf双星跨任意层级目录
temp? / [abc].txt问号匹配单字符，方括号匹配字符集合
!important.log取反，重新纳入被前面规则排除的文件

三、常用示例

一份够用的 .gitignore

gitignore一份够用的 .gitignore
# 依赖与构建产物
node_modules/
vendor/
dist/
*.log

# 本地环境文件
.env
.env.local
!.env.example

# 编辑器
.idea/
.vscode/
*.swp

排查「为什么没被忽略 / 为什么被忽略」

bash排查「为什么没被忽略 / 为什么被忽略」
git check-ignore -v dist/app.js
# .gitignore:3:dist/    dist/app.js
git check-ignore -vn src/app.js
git status --ignored -s | head -20

批量检查与脚本用法

bash批量检查与脚本用法
git ls-files -o --exclude-standard | git check-ignore -v --stdin
if git check-ignore -q build/app.js; then echo "被忽略"; fi

四、注意事项

⚠️
.gitignore 只对未跟踪文件生效
文件已经被提交过，再加忽略规则也不会让它从仓库里消失。正确做法是 git rm --cached <file> → 提交 → 之后规则才生效。注意这会让其它协作者下次 pull 时本地副本被删除，涉及共享配置要先沟通。
规则来源不止 .gitignore： 还有仓库的 .git/info/exclude 和全局 core.excludesFile。git check-ignore -v 会把具体文件和行号打出来，一眼就能看出是哪一层生效。

五、小结

把 git check-ignore -v 当作忽略规则的「调试器」，把 --no-index 和 -n 当作两个补充视角，再记住「已跟踪文件不受 ignore 影响」这条边界，.gitignore 就不再是玄学。到这里第一轮的基础命令就全部过完了。

本系列共 28 篇，一个命令一篇，完整目录见 Git 栏目。本系列第一轮完结，第二轮将进入 rebase -i、cherry-pick、bisect、worktree 等进阶命令。