Git 系列: 忽略文件.gitignore 使用教程与最佳实践

忽略文件（.gitignore）

在实际开发中，我们常常有一些文件不希望纳入 Git 管理，例如保存数据库密码的配置文件、自动生成的日志文件或编译过程中产生的临时文件。这类文件如果未被忽略，就会在每次执行 git status 时显示为未跟踪状态（Untracked files...），干扰我们对真正变动的关注。

为此，我们可以创建一个名为 .gitignore 的文件，列出要忽略的文件或目录模式。来看一个简单的 .gitignore 示例：

bash复制编辑$ cat .gitignore
*.[oa]
*~

• 第一行表示忽略所有以 .o 或 .a 结尾的文件，通常是编译生成的目标文件或静态库文件。
• 第二行表示忽略所有以波浪符（~）结尾的文件，这是像 Emacs 等文本编辑器保存临时副本时常用的命名方式。

除此之外，你还可以忽略如 log/、tmp/、*.pid 文件、自动生成的文档等。建议在创建新仓库时就编写好 .gitignore 文件，以防止误提交这类无用或敏感的文件。

.gitignore 文件的语法规范

.gitignore 文件的格式具有一定的规范性：

1. 空行或以 # 开头的行为注释，会被 Git 忽略。
2. 支持 glob 模式，可以递归匹配整个项目目录。
3. 以 / 开头的模式只作用于仓库的根目录。
4. 以 / 结尾的模式匹配目录。
5. 以 ! 开头的模式表示“例外”，即不忽略该文件或目录。

常用的匹配规则如下：

1. * 匹配零个或多个任意字符；
2. ? 匹配一个任意字符；
3. [abc] 匹配方括号中任意一个字符；
4. [0-9] 匹配 0 到 9 中的任意数字；
5. ** 匹配多级目录（如 a/**/z 可以匹配 a/z、a/b/z、a/b/c/z 等）。

更复杂的 .gitignore 示例

# 忽略所有的 .a 文件
*.a
​
# 但跟踪所有的 lib.a，即便你在前面忽略了 .a 文件
!lib.a
​
# 只忽略当前目录下的 TODO 文件，而不忽略 subdir/TODO
/TODO
​
# 忽略任何目录下名为 build 的文件夹
build/
​
# 忽略 doc/notes.txt，但不忽略 doc/server/arch.txt
doc/*.txt
​
# 忽略 doc/ 目录及其所有子目录下的 .pdf 文件
doc/**/*.pdf

GitHub 提供了丰富的 .gitignore 模板，覆盖数十种语言和工具，详见：github.com/github/gitignore

.gitignore 文件的位置与作用范围

通常，一个仓库只需要在根目录下维护一个 .gitignore 文件即可，它会递归作用于整个仓库。但实际上，每个子目录也可以拥有自己的 .gitignore 文件，仅作用于该目录及其子目录。

例如 Linux 内核项目就包含了超过 200 个 .gitignore 文件，用于精细控制每个子模块的忽略规则。

更多高级配置和优先级细节可通过命令 man gitignore 查看。

忽略规则的优先级

在同一项目中可能存在多个 .gitignore 文件，它们的生效顺序如下（优先级从高到低）：

1. Git 命令行中显式传入的忽略参数
2. 当前目录下的 .gitignore 文件
3. 父级目录中的 .gitignore 文件，递归向上查找
4. 仓库中的 $GIT_DIR/info/exclude 文件
5. 全局配置文件 core.excludesFile 中的规则（如 ~/.gitignore_global）

如何强制添加被 .gitignore 忽略的文件？

如果你需要强制将某个被 .gitignore 忽略的文件提交到仓库中，可以使用 -f 参数：

git add file.txt -f

实战用法

以下是 .gitignore 文件的使用方法：

创建 .gitignore 文件

在项目的根目录下创建一个名为 .gitignore 的文件。

touch .gitignore

编写忽略规则

根据实际需求编写规则。也可以直接从 GitHub 模板复制对应语言或框架的 .gitignore 文件（如 Node.js、Python、Go 等）。

可以使用对应的模板，而不用我们手动一个个定制，只有特殊的需要我们自己定制输入

https://github.com/github/gitignore 找到自己的语言和工具的即可粘贴复制模板即可。

# 忽略所有 .log 文件
*.log
​
# 忽略所有 .txt 文件，但包括 sample.txt
*.txt
!sample.txt
​
# 忽略某个特定文件或目录
myfolder/
myFile.txt
​
# 忽略所有 .pdf 文件
*.pdf
​
# 忽略编译生成的文件或文件夹
/build/
/dist/
​
# 忽略配置文件中的敏感信息
config.ini
​
# 忽略所有文件夹中的 .DS_Store 文件（仅适用于 macOS）
**/.DS_Store

将 .gitignore 文件加入到版本控制

一旦你创建并编辑好了 .gitignore 文件，确保将其添加到版本控制中：

git add .gitignore
git commit -m "Add .gitignore file to ignore specified patterns"

生效 .gitignore 规则

.gitignore 文件中指定的规则会在你运行 git add 或 git commit 时生效。这意味着被忽略的文件不会被添加到 Git 的暂存区或提交历史中。

检查 .gitignore 规则是否生效

你可以使用 git status 命令来检查文件是否被正确地忽略。被忽略的文件会显示为未跟踪状态。

git status

通过 .gitignore 文件，你可以更好地管理你的代码仓库，确保不会将不必要或敏感的文件纳入版本控制中。

注意：.gitignore 只能忽略未被 Git 跟踪的文件

.gitignore 文件只对尚未加入 Git 跟踪的文件起作用。如果某个文件已经被添加（git add）并提交（git commit），即便后来添加忽略规则，该文件仍然会被继续跟踪。

若要彻底忽略，需先取消对该文件的跟踪：

 git rm --cached 文件名

参考

[1] 所有配置文件可以直接在线浏览：https://github.com/github/gitignore

Ahmedabad