重新认识 .gitignore：目录级规则与 .git/info/exclude

.gitignore 到底在解决什么问题#

.gitignore 告诉 Git，哪些尚未被跟踪的文件或目录不必作为提交候选。它会影响这些操作：

1
git status
2
git add .
3
git ls-files --others --exclude-standard

它不会删除文件，也不会阻止程序生成文件，更不是安全保护。文件被忽略后，Git 默认不会把它作为待提交内容展示或加入索引。

这里最容易踩坑：已经被 Git 跟踪的文件，不会因为后来新增 .gitignore 规则就自动消失。

如果要停止跟踪一个已经提交过的文件，需要先把它从索引中移除，同时保留工作区文件：

1
git rm --cached path/to/file

然后再把对应路径写入 .gitignore，后续它才不会重新进入提交候选。

目录级 .gitignore 的作用域#

一个仓库可以有这样的结构：

1
repo/
2
├── .gitignore
3
├── src/
4
│   └── .gitignore
5
└── tools/
6
    └── .gitignore

判断 src/generated/cache.json 是否被忽略时，Git 会考虑仓库根目录、src/ 以及更靠近目标文件的目录中的 .gitignore。每份文件的规则都从它所在的目录开始，向下覆盖子目录。

例如，仓库根目录的 .gitignore：

1
# 只匹配仓库根目录下的 dist
2
/dist/
3

4
# 没有斜杠，匹配当前目录及所有子目录中的日志文件
5
*.log

src/.gitignore：

1
# 只匹配 src/generated，不匹配仓库根目录的 generated
2
/generated/

这里的 / 是相对于当前 .gitignore 所在目录的。于是，src/.gitignore 中的 /generated/ 对应的就是 src/generated/。

这也是我看到 .trellis/.gitignore 后才真正意识到的地方。子目录里的忽略文件可以把该目录自己的构建产物、缓存目录或工具运行时文件放在离它们更近的地方，不必把所有细节都堆进根目录的 .gitignore。

Git 会从哪些地方读取忽略规则#

Git 通常按下面的优先级读取排除规则，前面的来源优先级更高：

对于目录中的 .gitignore，Git 会同时考虑目标文件所在目录和父目录中的规则；更靠近目标文件的规则可以覆盖父目录中的规则。同一层级中，如果多个模式都匹配，后出现的模式决定最终结果。

所以，“全局忽略”“根目录忽略”和“子目录忽略”虽然都提供排除模式，但作用域、共享方式和优先级并不一样。

常见模式怎么解释#

1
*.log

1
app.log
2
logs/app.log
3
src/test/app.log

1
/tmp/

1
cache/

1
**/generated/

1
*.log
2
!keep.log

1
build/
2
!build/keep.log

1
build/*
2
!build/keep.log

.git/info/exclude 是什么#

.git/info/exclude 也是 Git 的忽略规则文件。它位于仓库的 .git 目录中，不会被提交，也不会随着普通的 git clone 复制给其他人。

它适合存放当前仓库的本地忽略配置：

• 规则只对当前仓库生效；
• 规则不会出现在提交记录中；
• 规则不会影响其他协作者；
• 它比全局忽略更具体，又不会污染项目公共的 .gitignore。

比如，只想在当前仓库忽略本地笔记和某个临时目录，可以编辑：

1
$EDITOR "$(git rev-parse --git-path info/exclude)"

加入：

1
# 只属于我在这个仓库中的本地文件
2
notes-local/
3
review-draft.md

如果当前仓库使用了 worktree，直接写死 .git/info/exclude 不一定稳妥。git rev-parse --git-path info/exclude 会返回当前仓库实际使用的 exclude 文件路径。

规则放在哪里，可以按下面的边界判断：

所有开发者都会生成的构建目录，应该写进项目 .gitignore；个人使用的编辑器临时文件，放进 .git/info/exclude；所有仓库都要忽略的 macOS .DS_Store，再考虑全局忽略文件。

如何查出究竟是哪条规则生效#

遇到“为什么这个文件没有出现在 git status 中”时，先运行：

1
git check-ignore -v -- path/to/file

输出通常会包含规则来源、行号、具体模式和目标路径，例如：

1
.trellis/.gitignore:8:.runtime/    .trellis/.runtime

这比只盯着根目录 .gitignore 猜测可靠得多。

如果目标文件已经被跟踪，默认情况下 git check-ignore 可能不会把它当作普通的 ignored 文件展示。这时可以加上 --no-index，只按工作区的忽略规则检查：

1
git check-ignore -v --no-index -- path/to/file

其他有用的排查命令：

1
# 查看被忽略的文件
2
git status --ignored
3

4
# 查看全局忽略文件配置及其来源
5
git config --show-origin --get core.excludesFile
6

7
# 查看当前仓库实际的 info/exclude 路径
8
git rev-parse --git-path info/exclude

几个容易误判的地方#

排查时按这个顺序看#

处理 Git 忽略问题时，我通常按下面的顺序判断：

1. 这个文件是否已经被跟踪？
2. 目标文件所在目录及父目录中，是否存在 .gitignore？
3. 规则中的 / 是相对于哪一份 .gitignore？
4. 是否有更靠近目标文件的规则或后出现的 ! 规则覆盖它？
5. 是否还有 .git/info/exclude 或全局 core.excludesFile 在生效？
6. 用 git check-ignore -v 查看 Git 给出的证据。

这样排查，通常很快就能定位规则的来源：它可能来自某一级目录的 .gitignore，也可能来自当前仓库的 .git/info/exclude 或用户级配置。

顺带一提，目录级忽略文件并不是 Git 2.x 才增加的能力。Git 的早期实现中，v0.99.2 已经出现了按目录读取 exclude 文件的支持，早于 Git 1.0.0。只是我最近才真正把它用起来。

参考：

• gitignore Documentation
• git-check-ignore Documentation
• git-ls-files: —exclude mechanism updates