【鸿蒙 PC三方库构建系统】.gitignore 解读：告诉 Git 哪些文件"别管我"

欢迎大家加入开源鸿蒙PC社区

项目地址：https://atomgit.com/oh-tpc/pc_sha

前言

你有没有这样的经历：git status 一敲，满屏的 .DS_Store、构建日志、临时文件，真正改了的源码反而淹没在一堆无关文件里？

.gitignore 就是解决这个问题的。它相当于给 Git 列了一份"黑名单"——名单上的文件，Git 直接无视，不追踪、不提示、不提交。

SHA 库适配项目的 .gitignore 虽然只有十几行，但每一条都有明确的意图。这篇文章就逐行拆解，讲清楚每条规则忽略了什么、为什么忽略，以及背后的思路。

---

先看完整内容

# Build logs
*-lycium_build.log
last_error

# Temporary files
*.tmp
*.temp

# OS files
.DS_Store
Thumbs.db

# IDE files
.vscode/
.idea/
*.swp
*.swo
*~

一共 4 组规则，12 条有效规则（不算注释和空行）。下面逐组讲解。

---

第一组：Build logs — 构建日志

# Build logs
*-lycium_build.log
last_error

*-lycium_build.log

忽略了什么：所有以 -lycium_build.log 结尾的文件。

实际匹配的文件（项目中真实存在的）：

sha-3ee0d88fc4f629b2e084f1b4cbf22cd3597542fb-arm64-v8a-lycium_build.log
sha-3ee0d88fc4f629b2e084f1b4cbf22cd3597542fb-armeabi-v7a-lycium_build.log

通俗理解：Lycium 构建系统每次编译都会生成日志文件，文件名格式是 包名-版本号-架构-lycium_build.log。这些日志动辄几十 KB，内容是编译过程的详细输出，对调试有用，但绝对不应该提交到 Git 仓库。

为什么忽略：

• 体积大：每个日志文件 40~50KB，两个架构就接近 100KB
• 每次构建都变：只要重新编译，日志内容就会更新，频繁产生无意义的 diff
• 可以重新生成：重新跑一遍构建就能得到，不是不可替代的资料
• 包含机器相关路径：日志里可能有本机 SDK 路径等信息，不同开发者路径不同，合并时必然冲突

通配符解析：

*                    ← 匹配任意字符（文件名前半部分）
-lycium_build.log    ← 固定后缀

* 是 Git 忽略规则中最常用的通配符，相当于"不管前面叫什么名字，只要后缀对上就忽略"。

last_error

忽略了什么：名为 last_error 的文件。

实际匹配的文件：项目根目录下的 last_error 文件。

通俗理解：这是 Lycium 构建系统在构建失败时写入错误信息的文件。构建成功后它可能还在，但内容已经没意义了。

为什么忽略：

• 临时性质：只在构建出错时有意义，属于"用完即弃"的文件
• 机器相关：不同人构建出的错误信息不同
• 可以重新生成：再跑一遍构建就能得到

---

第二组：Temporary files — 临时文件

# Temporary files
*.tmp
*.temp

*.tmp 和 *.temp

忽略了什么：所有以 .tmp 或 .temp 为扩展名的文件。

通俗理解：很多程序在处理数据时会先写一个临时文件，处理完再重命名为正式文件。如果中途崩溃或被中断，临时文件就留了下来。这些文件没有任何保留价值。

为什么忽略：

• 垃圾文件：正常流程中不应该存在，是异常中断的残留
• 内容不可控：可能是半写完的数据，内容不完整
• 不同程序格式不同：各种工具都可能产生 .tmp 文件，格式不统一

可能产生临时文件的场景：

• CMake 配置中断
• patch 命令中断
• 文本编辑器崩溃
• 脚本执行中途被 Ctrl+C

---

第三组：OS files — 操作系统自动生成的文件

# OS files
.DS_Store
Thumbs.db

.DS_Store

忽略了什么：macOS 系统自动生成的目录信息文件。

通俗理解：你在 macOS 的 Finder 里打开一个文件夹，系统会偷偷在文件夹里创建一个 .DS_Store 文件，记住你窗口的大小、图标排列方式、最近打开的位置等信息。这是 macOS 的"习惯"，你阻止不了。

为什么忽略：

• 纯系统文件：和项目代码毫无关系
• 每次打开文件夹都可能变：Finder 一打开就可能更新，产生无意义的变更
• 不同机器内容不同：每个人的文件夹视图设置不同，合并必冲突
• 可能泄露路径信息：.DS_Store 中可能包含本机目录结构

这是 macOS 开发中最经典的 gitignore 规则，几乎所有项目都会加。

Thumbs.db

忽略了什么：Windows 系统自动生成的缩略图缓存文件。

通俗理解：Windows 资源管理器在显示图片时会自动生成 Thumbs.db，缓存图片的缩略图，下次打开文件夹时能更快显示预览。

为什么忽略：

• 和 .DS_Store 同理：纯系统文件，与项目无关
• 二进制文件：无法查看内容，无法 diff
• 不同机器内容不同：取决于文件夹中有哪些图片

虽然项目主要在 macOS/Linux 上开发，但加上 Thumbs.db 是好习惯——万一有人用 Windows 打开过项目目录呢？

---

第四组：IDE files — 编辑器/IDE 产生的文件

# IDE files
.vscode/
.idea/
*.swp
*.swo
*~

.vscode/

忽略了什么：VS Code 编辑器的工作区配置目录。

通俗理解：用 VS Code 打开项目时，它会在项目里创建 .vscode/ 目录，存放工作区设置、调试配置、推荐插件等。这些是你个人的编辑器偏好，不是项目代码。

目录里可能有什么：

• settings.json：工作区设置（字体大小、格式化配置等）
• launch.json：调试配置
• extensions.json：推荐安装的插件
• tasks.json：任务配置

为什么忽略：

• 个人偏好：每个人的编辑器设置不同，你的字体大小别人不一定喜欢
• 路径相关：调试配置中可能包含本机绝对路径
• 频繁变动：改个设置就变，产生无意义的提交

例外情况：如果团队统一使用 VS Code，且希望共享某些配置（如调试配置），可以有选择地提交部分文件，但通常还是整体忽略更省心。

.idea/

忽略了什么：JetBrains 系列 IDE（如 CLion、IntelliJ）的项目配置目录。

通俗理解：和 .vscode/ 同理，JetBrains IDE 打开项目时自动创建的配置目录。

为什么忽略：理由和 .vscode/ 完全相同——个人偏好、路径相关、频繁变动。

*.swp 和 *.swo

忽略了什么：Vim/Vi 编辑器的交换文件。

通俗理解：Vim 在编辑文件时，会创建一个 .swp 后缀的交换文件作为"保险"。如果 Vim 崩溃或非正常退出，下次打开时可以用交换文件恢复未保存的修改。.swo 是当 .swp 已存在时创建的第二个交换文件。

举例：编辑 HPKBUILD 时，Vim 会创建 .HPKBUILD.swp。

为什么忽略：

• 临时性质：正常退出 Vim 后交换文件会被自动删除，只有异常退出才残留
• 二进制格式：无法直接查看和 diff
• 包含未保存的修改：可能和当前文件内容不一致

*~

忽略了什么：备份文件，文件名以 ~ 结尾。

通俗理解：很多 Linux/Mac 上的编辑器（如 Emacs、gedit）在保存文件时，会把修改前的版本备份一份，在文件名后面加个 ~。比如编辑 HPKBUILD 后，会出现 HPKBUILD~。

为什么忽略：

• 备份性质：只是修改前的旧版本，不是新内容
• 冗余：Git 本身就有版本控制功能，不需要编辑器再做备份
• 容易忘记清理：编辑器自动创建，人经常忘记删除

---

规则速查表

规则	忽略的对象	产生者	忽略理由
*-lycium_build.log	构建日志	Lycium 构建系统	可重新生成、体积大、机器相关
last_error	构建错误记录	Lycium 构建系统	临时文件、可重新生成
*.tmp	临时文件	各种工具	垃圾残留、内容不可控
*.temp	临时文件	各种工具	同上
.DS_Store	目录信息	macOS Finder	系统文件、机器相关
Thumbs.db	缩略图缓存	Windows 资源管理器	系统文件、二进制
.vscode/	编辑器配置	VS Code	个人偏好、路径相关
.idea/	编辑器配置	JetBrains IDE	个人偏好、路径相关
*.swp	交换文件	Vim	临时文件、二进制
*.swo	交换文件	Vim	临时文件、二进制
*~	备份文件	Emacs/gedit 等	冗余备份、Git 自带版本控制

---

实际效果验证

我们可以用 Git 命令验证 .gitignore 的实际效果：

# 查看被忽略的文件
git ls-files --others --ignored --exclude-standard

在 SHA 项目中，实际被忽略的文件有：

.DS_Store
last_error
sha-3ee0d88fc4f629b2e084f1b4cbf22cd3597542fb-arm64-v8a-lycium_build.log
sha-3ee0d88fc4f629b2e084f1b4cbf22cd3597542fb-armeabi-v7a-lycium_build.log

可以看到，构建日志和 last_error 确实被忽略了，.DS_Store 也在其中。而 HPKBUILD、HPKCHECK、hnp.json 等项目文件不受影响，正常被 Git 追踪。

---

没有被忽略但值得讨论的文件

对比项目目录，有些文件没有被 .gitignore 忽略，但也值得思考：

output/ 目录

output/
├── output/
│   ├── arm64-v8a/
│   │   ├── sha.hnp
│   │   └── sha_3ee0d88....tar.gz
│   └── armeabi-v7a/
│       ├── sha.hnp
│       └── sha_3ee0d88....tar.gz
└── usr/
    └── sha/
        ├── arm64-v8a/  (bin/, include/, lib/)
        └── armeabi-v7a/ (bin/, include/, lib/)

output/ 目录包含编译产物和打包结果，理论上也是可重新生成的。当前 .gitignore 没有忽略它，所以 git status 会显示 output/ 为未追踪目录。

是否应该忽略：取决于项目策略。如果产物仅供本地验证，建议忽略；如果需要把产物提交到仓库供他人直接使用，则不忽略。对于 SHA 库适配项目，建议加上 output/ 到 .gitignore。

sha-3ee0d88.../ 源码目录

这是 git clone 下载的上游源码，也是可重新生成的。当前没有被忽略。

建议：加上 sha-*/ 到 .gitignore，避免意外提交大量上游源码。

---

.gitignore 的语法速查

理解了具体规则后，这里总结一下 .gitignore 的常用语法，方便以后自己写：

基本规则

语法	含义	示例	匹配
*	匹配任意字符	*.log	build.log、error.log
?	匹配单个字符	file?.txt	file1.txt、fileA.txt
[]	匹配括号内字符	file[123].txt	file1.txt、file2.txt
/	目录分隔符	build/	build/ 目录
#	注释	# 这是注释	无
!	取反（不忽略）	!important.log	保留 important.log

目录 vs 文件

build          # 忽略所有名为 build 的文件和目录
build/         # 只忽略名为 build 的目录
/build/        # 只忽略根目录下的 build 目录

区别很微妙但很重要：

• 不带 /：匹配任何位置的 build
• 末尾带 /：只匹配目录，不匹配同名文件
• 开头带 /：只从仓库根目录开始匹配

取反规则

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

# 但保留 important.log
!important.log

! 可以"挖坑"——先忽略一大类，再把其中个别文件捞回来。

---

常见问题

Q1：.gitignore 本身需要提交到 Git 吗？

需要。 .gitignore 是项目配置的一部分，应该提交到仓库，让所有协作者共享同一套忽略规则。否则别人 git add . 时会把构建日志、.DS_Store 等全提交上去。

Q2：文件已经被 Git 追踪了，再加 .gitignore 还有效吗？

无效。 .gitignore 只对未被追踪的文件生效。如果文件已经被 git add 过，即使加到 .gitignore 里，Git 仍然会继续追踪它的变更。

解决方法：先从 Git 中移除追踪（不删除文件）：

git rm --cached 文件名

然后再加到 .gitignore，最后提交。

Q3：全局 gitignore 和项目 gitignore 有什么区别？

类型	位置	作用范围	优先级
全局	~/.gitignore_global	当前用户所有仓库	低
项目	仓库根目录 .gitignore	当前仓库	高
目录	子目录中的 .gitignore	当前目录及子目录	最高

建议：个人偏好（如编辑器配置）放全局，项目相关（如构建产物）放项目。

Q4：为什么 output/ 没有被忽略？

当前 .gitignore 确实没有包含 output/。这可能是有意为之（需要提交产物），也可能是遗漏。对于大多数项目，构建产物应该被忽略。

Q5：.gitignore 的规则顺序有影响吗？

有影响。 后面的规则可以覆盖前面的。特别是 ! 取反规则：

# 先忽略所有 .log
*.log

# 再保留 important.log（后面的 ! 覆盖前面的 *）
!important.log

---

改进建议

基于当前项目的实际情况，建议在 .gitignore 中补充以下规则：

# Build output
output/
sha-*/

# Build logs (已有)
*-lycium_build.log
last_error

# Temporary files (已有)
*.tmp
*.temp

# OS files (已有)
.DS_Store
Thumbs.db

# IDE files (已有)
.vscode/
.idea/
*.swp
*.swo
*~

新增的两条：

• output/：忽略所有构建产物（HNP 包、tar.gz、安装目录）
• sha-*/：忽略 git clone 下载的上游源码目录

这样 git status 的输出会更干净，只显示真正需要关注的文件变更。

---

总结

.gitignore 的核心思想很简单：告诉 Git 哪些文件不需要管。但写好它需要理解三个原则：

三大原则

1. 可重新生成的不提交：构建日志、编译产物、下载的源码——重新跑一遍构建就能得到，不需要占仓库空间
2. 机器相关的不提交：系统文件（.DS_Store）、编辑器配置（.vscode/）、本机路径——不同人环境不同，提交必冲突
3. 临时垃圾不提交：交换文件（.swp）、备份文件（*~）、临时文件（.tmp）——正常流程中不该存在

SHA 项目的 .gitignore 评价

方面	评价
构建日志忽略	完备
临时文件忽略	完备
系统文件忽略	完备（覆盖 macOS 和 Windows）
编辑器文件忽略	完备（覆盖 VS Code、JetBrains、Vim、Emacs）
构建产物忽略	缺失（建议加 output/）
源码目录忽略	缺失（建议加 sha-*/）

整体来说，当前的 .gitignore 覆盖了最常见的忽略场景，质量不错。补充构建产物和源码目录的忽略规则后就更完善了。

---

文档版本: 1.0.0
最后更新: 2026-04-13