最近在整理自己的ELN,想用 Git 来给它做版本管理。库里的内容会不断增加,而真正希望被 Git 追踪的其实只有各种 Markdown 文稿。于是研究了一下 “.gitignore”的写法,把白名单和黑名单两种模式整理如下,方便以后直接复用。
先说一个最核心的点:“.gitignore”文件本质上是一份"黑名单",里面列的都是一条条要忽略的东西。我们常说的"白名单",其实是"先忽略全部、再逐条放行"模拟出来的。
还有一个很容易踩的坑:如果一个目录被忽略了,Git 就不会进入这个目录,里面的文件即使想保留也无法被重新包含进来。所以在白名单模式里,通常第一步就得先把目录放行。
白名单模式:只追踪所有层级的 Markdown 文件
适用场景:文件夹以后还会继续增加,但我只关心所有目录下的 .md 文件,其他文件一律不管;同时希望 Git 能进入未来新增的子目录去找 Markdown。
# ===== 白名单:只追踪所有层级的 Markdown =====
# 1. 先忽略所有文件和目录
*
# 2. 保留 .gitignore 自身(可选;不想追踪可删)
!.gitignore
# 3. 放行所有目录,让 Git 能进入未来新增的文件夹
!*/
# 4. 放行所有层级的 Markdown 文件
!*.md
!**/*.md
效果:文件只追踪markdown文件,而不追踪附件内容。
这里的关键是 !*/:它并不是"追踪文件夹",而是允许 Git 去遍历目录。Git 不会真正追踪空目录,所以不用担心它会凭空留下空文件夹。
黑名单模式:排除明确不需要的目录和文件
适用场景:你明确知道要忽略哪些目录或文件类型。
需要提醒的是,不推荐用黑名单来实现"只关注 Markdown",因为以后每新增一种非 Markdown 类型,都要回来补一条规则。
# ===== 黑名单:排除明确不需要的内容 =====
# 常见目录
node_modules/
dist/
build/
coverage/
.cache/
.idea/
.vscode/
# 常见非 Markdown 文件
*.log
*.tmp
*.bak
*.png
*.jpg
*.jpeg
*.gif
*.pdf
*.zip
# 系统文件
.DS_Store
Thumbs.db
黑名单模式有一个天然局限:
# 这样会忽略所有目录,包括目录里的 Markdown
*/
也就是说,不能靠"忽略所有文件夹"再保留文件夹内的 Markdown。想保留目录里的 Markdown,就必须用白名单的思路,先把目录放行。
四、三种模式速查表
| 需求 | 推荐模式 | 核心规则 |
|---|---|---|
| 只追踪所有层级 Markdown | 白名单 A | * + !*/ + !*.md |
| 排除明确目录/文件 | 黑名单 | 列出 node_modules/、*.log 等 |
| 排除所有文件夹但保留其中 Markdown | 不要用黑名单 | 用白名单 A |
五、让规则生效:清理已跟踪的文件
要记住,.gitignore 只对未跟踪的文件生效。如果之前已经跟踪了现在不想跟踪的文件,需要把它们从索引里移除,但保留本地文件:
git rm -r --cached .
git add .
git commit -m "chore: only track markdown files"
--cached 不会删除工作区的文件,只会清理 Git 索引,所以本地文件是安全的。
六、验证与排查
查看当前实际被追踪的文件:
git ls-files
查看被忽略的文件:
git status --ignored
排查某个文件为什么被忽略:
git check-ignore -v docs/guide.md
小结
- 如果目标是"未来新增文件夹也要自动只关注其中的 Markdown":用白名单模式 A。
- 如果目标是"只看根目录 Markdown,子目录 Markdown 全部不要":用白名单模式 B。
- 黑名单模式只适合排除明确已知的目录和文件类型,不适合实现"只关注 Markdown"这种白名单需求。