first-contributions 仓库实战指南：.gitignore 文件从入门到精通的完整解析
【免费下载链接】first-contributions🚀✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions
本文以开源项目 first-contributions（帮助初学者完成第一次开源贡献的教程仓库）为背景，系统讲解 Git 中.gitignore文件的作用、创建方法、匹配语法与常见运维操作。读完本文，你将掌握如何通过本地与全局.gitignore精确控制仓库的跟踪范围，避免临时文件、敏感配置与大型依赖被误提交，并能在文件已被跟踪后安全地将其移出版本控制。
.gitignore 是什么：Git 工作流中的"忽略清单"
.gitignore是 Git 工作流中一个不可或缺的组成部分。它是一个纯文本文件，告诉 Git 哪些文件与文件夹应当被忽略，从而避免不必要或敏感的数据被纳入仓库跟踪。Git 会根据该文件中的规则，在git status、git add等操作中自动跳过匹配的文件，使其不会出现在暂存区（index）与提交历史中。
在 first-contributions 仓库中，.gitignore位于仓库根目录（即 .gitignore），是理解该文件实际形态的最佳范例。它是一份大型、按用途分节组织的规则集，例如文件开头部分（.gitignore）就集中忽略了常见开发工具与系统文件：
.DS_Store; .idea/ .vs .vscode .env这些条目分别对应 macOS 系统文件、JetBrains 系列 IDE 配置目录、Visual Studio 配置、VS Code 配置以及环境变量文件，几乎覆盖了各类主流开发环境。
为什么需要 .gitignore：四类必须忽略的文件
某些文件不应该纳入版本控制，因为它们属于以下四类之一：
- 临时或系统生成的文件：缓存（cache）、构建产物（build）、日志（log）等，如
.cache/、*.log、编译输出的bin/、obj/目录； - 可重新安装的大型依赖：例如
node_modules（Node.js 依赖目录）、venv/（Python 虚拟环境），它们体积庞大且可通过包管理器一键恢复； - 个人或敏感配置文件：如 API 密钥、环境变量文件（
.env），一旦提交可能导致凭据泄露； - IDE 或编辑器专属文件：如
.vscode/、.idea/，这类配置仅对个别开发者有意义，提交后反而容易在不同环境间产生冲突。
忽略这些文件可以保持仓库干净、减少合并冲突，并防止安全风险。从 first-contributions 仓库的实际 .gitignore 中可以直观看到这四类规则的落地：第 290 行忽略node_modules/，第 93 行忽略*.log，第 21-24 行忽略[Dd]ebug/、[Rr]elease/等构建输出目录，第 1-5 行忽略.idea/、.vscode等 IDE 文件。
创建 .gitignore 文件的三个步骤
创建.gitignore非常简单：
- 在项目根目录下新建一个名为
.gitignore的文本文件（注意文件名以点开头，且没有扩展名）； - 将希望忽略的文件和文件夹逐行列出；
- 保存文件，之后
git add与git status会自动遵守其中的规则。
提示：
.gitignore也可以放在子目录中，此时规则仅对该子目录及其后代目录生效。最常见的做法是像 first-contributions 仓库一样放在项目根目录，统一管理整个仓库的忽略策略。
基本语法：三种核心匹配模式
.gitignore的每一行都是一条匹配规则，支持以下三种基础语法：
| 符号 | 作用 | 示例 |
|---|---|---|
* | 通配符，匹配任意多个文件 | *.log匹配所有.log结尾的文件 |
/ | 指定相对于.gitignore所在位置的路径 | build/匹配根目录下的build目录 |
# | 注释行 | # Ignore Mac system files |
在此基础上，结合仓库 .gitignore 中实际出现的模式，可以进一步理解这套语法的表现力：
node_modules/（.gitignore）：以斜杠结尾表示匹配目录及其全部内容；[Dd]ebug/、[Rr]elease/（.gitignore）：方括号字符类，可同时匹配大写与小写字母开头；**/[Pp]ackages/*（.gitignore）：双星号**匹配任意层级目录，配合字符类实现深层通配；!.vscode/settings.json（.gitignore）：感叹号!为否定规则，用于"排除被忽略"的文件，即先整体忽略.vscode/目录，再单独放行个别配置文件；~$*（.gitignore）：匹配以~$开头的 Office 临时文件。
这些进阶用法体现了.gitignore规则"先忽略、再放行"的灵活组合能力。
一个可直接复制的示例 .gitignore
以下示例摘自原文档，涵盖了上述四类文件的典型忽略规则：
# Ignore Mac system files .DS_Store # Ignore dependency folders node_modules/ venv/ # Ignore log and cache files *.log .cache/ # Ignore environment files .env # Ignore all text files *.txt注意示例末尾的*.txt：通配符规则会匹配项目中所有文本文件，实际使用时请根据项目情况谨慎决定是否真的需要忽略某一类通用文件类型。如果希望核对更完整的分场景模板，可直接阅读 first-contributions 仓库根目录的 .gitignore，其中按 .NET 构建产物、NuGet 包、Visual Studio 缓存、VS Code 配置、Python 缓存等类别分节组织，可作为编写大型项目忽略规则时的参考范本。
全局 .gitignore：让所有仓库共享忽略规则
如果某些文件（如操作系统产生的.DS_Store）在每一个仓库中都不希望被跟踪，可以创建全局.gitignore，让规则对所有仓库生效：
git config --global core.excludesfile ~/.gitignore_global执行后，Git 会将该路径注册为全局排除规则文件。之后编辑~/.gitignore_global的方式与编辑本地.gitignore完全相同，其中列出的所有文件与文件夹将在你机器上的每一个 Git 仓库中被忽略。
移除已被跟踪的文件：让 .gitignore 对已提交文件生效
.gitignore只对"尚未被跟踪"的文件生效。如果某个文件在加入.gitignore之前就已经被提交，Git 会继续跟踪它，此时需要主动将其从跟踪中移除。
取消跟踪单个文件（保留本地副本）：
git rm --cached filename--cached参数是关键：它只从 Git 索引（暂存区）中移除文件，而保留工作目录中的实际文件。
批量取消跟踪所有应被忽略的文件：
git rm -r --cached . git add . git commit -m "Updated .gitignore"git rm -r --cached .递归地将当前目录下所有已跟踪文件从索引移除；git add .重新暂存所有文件——此时.gitignore中的规则会生效，被忽略的文件不会再次加入；git commit -m "Updated .gitignore"提交这次变更，完成"去跟踪"。
在批量操作之前，建议先提交任何尚未提交的代码变更，避免干扰。这一步在首次为存量仓库补建.gitignore时尤其实用。
撤销误操作：
git add filename如果执行git rm --cached filename后反悔，重新执行git add filename即可将文件恢复为跟踪状态。
常见问题与进阶阅读
- 文件仍显示在
git status中？先确认文件是否已被跟踪（可用git ls-files查看）；已被跟踪的文件必须先按上文"移除已被跟踪的文件"处理，仅修改.gitignore不会生效。 - 忽略规则不生效？检查规则路径中的斜杠语义，以及是否被后文的
!否定规则重新放行。 .gitignore与.git/info/exclude的区别？前者随仓库提交、对所有协作者生效；后者仅对本地当前仓库生效，适合个人临时忽略。
本文属于 first-contributions 仓库 docs/additional-material/git_workflow_scenarios/additional-material.md 所汇总的进阶 Git 技巧系列之一，该索引还收录了 配置 Git、撤销提交、保持 Fork 与上游同步 等配套文档。想要完整走一遍 fork → clone → 修改 → Pull Request 的首次贡献流程，可回到 README.md 从基础教程开始；需要核对一份真实的大型忽略规则样例时，直接打开仓库根目录的 .gitignore 即可。
【免费下载链接】first-contributions🚀✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
