忽略文件

在项目中，有些文件不应该纳入 Git 版本控制，如编译产物、依赖包、本地配置文件、敏感信息等。.gitignore 文件定义了哪些文件应该被忽略。

.gitignore 语法规则

基本规则

# 这是注释（以 # 开头的行）

# 忽略特定文件
secret.txt
.env

# 忽略特定扩展名的所有文件
*.log
*.tmp
*.swp

# 忽略特定目录（推荐加 /）
node_modules/
dist/
build/
__pycache__/

# 忽略特定目录下的特定文件
logs/*.log

# 忽略所有子目录下的 .log 文件
**/*.log

匹配模式

模式	含义
*.log	任意目录下的 .log 文件
debug.log	任意目录下的 debug.log
/debug.log	只有根目录下的 debug.log
logs/	logs 目录（含其下所有内容）
logs/*.log	logs/ 目录下的 .log 文件（不含子目录）
logs/**/*.log	logs/ 目录及其所有子目录下的 .log 文件
**/logs	任意目录下名为 logs 的目录
doc/**	doc 目录下的所有内容

取反规则（!）

! 前缀表示不忽略（即使父目录被忽略，也不生效）：

# 忽略所有 .log 文件
*.log

# 但保留 important.log
!important.log

# 忽略 build 目录
build/

# 这条不生效！父目录 build/ 已被忽略，无法取反其中的文件
!build/release.log

注意：如果一个目录被忽略，其下的文件无法通过 ! 取反。

斜杠的含义

# 末尾无 /：忽略任意位置的同名文件或目录
logs            # 忽略所有名为 logs 的文件和目录

# 末尾有 /：只忽略目录
logs/           # 只忽略名为 logs 的目录

# 开头有 /：只匹配根目录
/config.js      # 只忽略根目录下的 config.js

全局 .gitignore

用于忽略系统或编辑器产生的文件，适用于所有仓库：

# 配置全局忽略文件
git config --global core.excludesFile ~/.gitignore_global

# 创建全局忽略文件
cat > ~/.gitignore_global << 'EOF'
# macOS
.DS_Store
.AppleDouble
.LSOverride

# Windows
Thumbs.db
ehthumbs.db
Desktop.ini

# Linux
*~

# 编辑器
.vscode/
.idea/
*.swp
*.swo
*.sublime-workspace

# 系统
*.log
EOF

.gitignore 模板推荐

gitignore.io 可以根据技术栈自动生成模板。

Node.js 项目

# 依赖
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*
.pnpm-debug.log*

# 构建产物
dist/
build/
.next/
.nuxt/
.output/

# 环境变量（敏感信息！）
.env
.env.local
.env.*.local

# 缓存
.cache/
.parcel-cache/

# 测试覆盖率
coverage/

# 系统文件
.DS_Store
Thumbs.db

Python 项目

# 字节码
__pycache__/
*.py[cod]
*$py.class
*.pyc

# 虚拟环境
venv/
env/
.venv/
.env/

# 分发/打包
build/
dist/
*.egg-info/
.eggs/

# 测试
.pytest_cache/
.coverage
htmlcov/

# Jupyter Notebook
.ipynb_checkpoints

# mypy
.mypy_cache/

Java 项目

# 编译产物
*.class
*.jar
*.war
*.ear
target/

# Maven
.mvn/
!.mvn/wrapper/maven-wrapper.jar

# Gradle
.gradle/
build/
!gradle/wrapper/gradle-wrapper.jar

# IDE
.idea/
*.iml
.eclipse
.settings/
.classpath
.project

# 系统
.DS_Store

已跟踪文件的忽略处理

如果文件已经被 Git 跟踪（已提交过），再添加到 .gitignore 不会自动忽略它。需要先取消跟踪：

# 取消跟踪单个文件（保留本地文件）
git rm --cached .env

# 取消跟踪目录
git rm -r --cached node_modules/

# 取消跟踪所有符合 .gitignore 的已跟踪文件
git rm -r --cached .
git add .
git commit -m "chore: 应用 .gitignore，移除不应跟踪的文件"

警告：git rm --cached 会从仓库中删除文件记录，其他人拉取后文件也会被删除（本地文件不受影响）。确保这是你期望的行为。

git check-ignore -v 调试忽略规则

当文件被意外忽略（或不被忽略）时，用此命令调试：

# 检查文件是否被忽略（及原因）
git check-ignore -v node_modules/lodash/index.js
# .gitignore:3:node_modules/  node_modules/lodash/index.js

# 检查多个文件
git check-ignore -v *.log config.js

# 查看所有被忽略的文件
git status --ignored

输出格式：<规则文件>:<行号>:<规则> <文件路径>

.gitkeep 保留空目录的约定

Git 不会跟踪空目录。有时需要在版本库中保留空目录结构（如 uploads/、logs/）：

# 创建 .gitkeep 文件（空文件，只是占位符）
touch uploads/.gitkeep
touch logs/.gitkeep

git add uploads/.gitkeep logs/.gitkeep
git commit -m "chore: 保留空目录结构"

在 .gitignore 中对这些目录的内容进行忽略，但保留 .gitkeep：

# 忽略 uploads 目录下的所有内容
uploads/*

# 但保留 .gitkeep 占位符
!uploads/.gitkeep

忽略规则优先级

Git 按以下顺序读取忽略规则（后者优先级更高）：

1. .git/info/exclude（仓库级，不提交）
2. 全局配置 core.excludesFile（~/.gitignore_global）
3. 目录树中各级 .gitignore（离文件越近，优先级越高）

常见问题

为什么 .gitignore 没生效？

最常见原因：文件已经被 Git 跟踪了。解决方案：

git rm --cached <file>
git commit -m "chore: 停止跟踪 <file>"

如何忽略已修改但不想提交的文件？

如果文件必须存在于仓库（如配置文件模板），但本地修改不想提交：

# 假设忽略本地对此文件的修改（不建议滥用）
git update-index --assume-unchanged config/local.conf

# 恢复跟踪
git update-index --no-assume-unchanged config/local.conf

总结

场景	处理方式
新文件不想跟踪	添加到 .gitignore
已跟踪文件想忽略	git rm --cached + 更新 .gitignore
调试忽略规则	git check-ignore -v <file>
保留空目录	创建 .gitkeep 文件
系统/编辑器文件	配置全局 .gitignore_global

.gitignore 是每个项目的必备配置，合理设置可以保持仓库整洁，防止敏感信息泄露。