引入

项目目录中经常有依赖目录、构建产物、编辑器配置和本地密钥。这些文件可能很大、不可复现,或者包含敏感信息,不应进入版本库。.gitignore 用来声明 Git 默认忽略哪些未跟踪文件。

正文

基本写法

node_modules/
.env
.env.*
!.env.example
*.log
.idea/
.vscode/
  • / 结尾通常表示目录。
  • * 表示通配内容。
  • ! 可以取消某条忽略规则。
  • .env.example 可以提交不含真实凭据的配置示例。

常见使用流程

创建或编辑项目根目录下的 .gitignore,然后检查忽略结果:

touch .gitignore
git status --ignored
git check-ignore -v node_modules/package.json

.gitignore 只对未跟踪文件生效。如果文件已经被提交,后来再写入忽略规则并不会自动移除它。需要先停止跟踪,但保留本地文件:

git rm --cached .env
git rm -r --cached node_modules
git commit -m "停止跟踪本地文件"

不要忽略什么

  • 不要忽略源代码、锁定文件和项目构建所需的配置。
  • 不要把真实密钥当作“本地文件”处理后继续留在 Git 历史中。
  • 不要只复制网上模板,应根据项目实际生成物和工具配置调整。

检查某个文件为什么被忽略:

git check-ignore -v path/to/file

如果文件被忽略但确实需要提交,可以使用 -f 强制添加:

git add -f path/to/file

规则匹配顺序

  • 项目根目录的 .gitignore 适用于整个仓库。
  • 子目录中的 .gitignore 可以补充更具体的规则。
  • .git/info/exclude 只对当前本地仓库生效,适合个人临时忽略规则。
  • 全局 excludes 文件适合编辑器生成的个人文件,不应代替项目 .gitignore
  • 后出现的规则通常可以覆盖前面的规则,但父目录已经被忽略时,子文件可能无法通过 ! 重新包含。

查看 Git 当前使用的全局忽略文件:

git config --get core.excludesfile

引出

忽略规则解决的是“哪些文件不进入版本控制”,不是权限控制,也不是秘密管理方案。密钥一旦进入远程历史,应立即撤销并轮换,再根据情况清理历史。