使用指南

.gitignore：模板组合、匹配规则与不生效的原因

理解 Git 忽略模式的路径范围、否定规则和优先级，正确区分未跟踪与已跟踪文件。

JTools 维护者 · 更新于 2026-10-17

.gitignore 告诉 Git 哪些未跟踪文件无需纳入版本管理。通常在项目根目录放置一份，并根据语言、构建工具、编辑器和操作系统选择模板。它不会删除文件，也不会停止跟踪已经提交的文件。

模板应与项目实际情况匹配。例如 Node 项目可以组合 Node、VisualStudioCode 和 macOS，但是否提交编辑器共享配置、依赖锁文件或构建产物仍由团队决定。生成器保留选择顺序；想让某个模板的规则后生效，可移除后重新添加。

同一 .gitignore 内，最后一条匹配规则决定是否忽略。*.log 后接 !important.log 会保留 important.log，再添加 *.log 又会将它忽略，因此不能随意排序或去重。已忽略的父目录不会被 Git 继续遍历；若想在 cache 中保留 keep.txt，可先忽略 cache/* 再写 !cache/keep.txt，而不是直接忽略 cache/。

用 git check-ignore -v 路径 查看未跟踪文件匹配到的规则，用 git ls-files -- 路径 判断文件是否已被跟踪。确需取消跟踪时，先检查工作区和团队需求，再针对具体文件使用 git rm --cached -- 路径 并提交变更。该操作不会清除历史，也不应对整个仓库盲目执行。

忽略本地 .env 时可以显式保留不含秘密的 .env.example。已经提交过的密钥不会因增加 .gitignore 而从历史中消失，应撤销或轮换泄露凭据，并单独评估历史清理。