每个仓库里都有一份默默干活的配置——.gitignore：它告诉 Git 哪些文件不必纳入版本管理，构建产物、IDE 配置、系统杂项从此不再污染提交记录。IDE 按模板建工程时会自动带上它，而手动 git init 的仓库没有这个文件，需要在根目录自建并配置。这篇按语法规则、路径锚定、全局配置、通用模板、常见坑五部分整理，完整语法可查 官方 gitignore 文档。
1、匹配规则语法
.gitignore 的语法就是一组带通配符的路径模式，六个符号各司其职：
| 符号 | 含义 |
|---|---|
# |
注释行 |
/ 开头 |
锚定到 .gitignore 所在目录（通常是仓库根） |
/ 结尾 |
只匹配目录，不匹配同名文件 |
* |
通配符，匹配零个或多个任意字符 |
? |
匹配单个任意字符 |
[] |
匹配方括号中列出的任一字符，如 [ab] 匹配 a 或 b |
! |
反选：不忽略（继续跟踪）匹配到的文件 |
规则按行从上到下依次匹配，后面的规则可以覆盖前面——这正是 ! 例外生效的基础。
2、路径锚定与例外规则
前导斜杠的锚定语义是最容易混淆的点，两组写法的区别如下：
/build/ # 只忽略根目录下的 build 目录
build/ # 忽略任意层级名为 build 的目录
*.bat # 忽略所有 .bat 文件
"忽略某目录但保留其中某类文件"是高频需求，正确写法要用 /* 而不是 / 结尾：
/folder/*
!/folder/*.java
第一条忽略 folder 下所有条目，第二条把 Java 源文件捞回来。如果第一条写成 /folder/，第二条将失效——目录被整体忽略后，Git 根本不会再进入这个目录去逐个检查文件，例外规则自然无从谈起。这是官方文档明示的行为，也是实际配置中最常见的错误。
3、全局忽略配置
每个工程都写一遍系统杂项（.DS_Store、Thumbs.db）太重复，可以像配置全局别名那样定义一份全局 .gitignore：
git config --global core.excludesfile ~/.gitignore
之后用户目录下的 ~/.gitignore 对本机所有仓库生效，仓库内的 .gitignore 只需关注项目自身的产物，与全局规则取并集。
4、Android 通用模板
一份适用于 Android/Java 开发的通用模板如下：
# 构建产物
*.apk
*.ap_
*.dex
*.class
bin/
gen/
build/
# IDE 与构建工具
*.iml
.idea
.gradle
.navigation
captures/
output.json
# 系统杂项
Thumbs.db
.DS_Store
# NDK
obj/
.externalNativeBuild
不必死记硬背——github/gitignore 仓库收录了各语言各框架的官方模板，新建工程时按技术栈取一份再微调，比从零手写可靠。
5、已跟踪文件的大坑
.gitignore 只能忽略尚未被跟踪的文件；文件一旦已提交入库，再改 .gitignore 对它无效。
原因是忽略规则只在 Git 扫描未跟踪文件时生效，已入库的文件会继续被跟踪。排查与解法如下：
git check-ignore -v build/output.apk # 查看某文件命中了哪条规则
git rm -r --cached . # 取消跟踪（文件保留在磁盘）
git add . && git commit -m "应用忽略规则"
check-ignore -v 是排查"为什么没被忽略 / 为什么被忽略"的第一工具；rm --cached 只删索引不删本地文件，三步走完规则即对老文件生效。
6、总结
.gitignore 的要点可以压成四句：语法是 glob 加 ! 反选，前导 / 锚定根目录、结尾 / 只匹配目录；捞回例外文件必须用 目录/* 而非 目录/；系统杂项沉到 core.excludesfile 全局配置；已跟踪文件要先 git rm --cached 再谈忽略。对于新仓库，建议从 github/gitignore 取对应技术栈的模板起步，配合 git check-ignore -v 随时验证，忽略配置就再没有玄学的部分。
