鸿蒙三方库适配读懂 thirdparty/AES/.gitignore：哪些文件不该进 Git？

欢迎大家加入开源鸿蒙跨平台开发者社区

前言

.gitignore 是 Git 的「忽略清单」：列在里面的路径或模式，默认不会被 git add 进版本库。三方库适配目录里往往既有 需要长期保存的脚本和文档，也有 下载的源码包、本地编译目录、日志——若全部提交，仓库会膨胀，且容易产生 机器相关路径、二进制冲突。

本仓库的 .gitignore 做了两件重要取舍：

1. 压缩包：用 以 / 开头的模式 只忽略 仓库根目录 下的 .tar.gz / .tgz，不忽略 子目录（例如 output/）里的归档，方便把构建产物一并纳入版本管理。
2. 构建树：忽略 tiny-AES-c-*/ 和解压后的 *-build 等，避免把 lycium/cmake 生成的大量中间文件提交上去。

下面 按行说明 每一条规则在表达什么（.gitignore 里没有「字段」，有的是 模式 pattern；文中把每一行都当成一条规则来讲）。

---

文件全文（便于对照）

# 仅忽略根目录源码包与杂项归档；output/ 下构建产物需纳入版本库
/tiny-AES-c-*.tar.gz
/*.tar.gz
/*.tgz
*.zip
tiny-AES-c-*/
armeabi-v7a-build
arm64-v8a-build
*-build
*.log
last_error
*-lycium_build.log
download.log

---

逐条规则说明

第 1 行：注释 # ...

内容	含义
以 # 开头	Git 忽略注释行，不参与匹配。
文案大意	说明设计意图：根目录的源码包/杂包要忽略；output/ 下的产物 需要提交，所以不要写 output/ 进忽略列表。

---

/tiny-AES-c-*.tar.gz

要点	说明
行首 /	只相对 当前 .gitignore 所在目录（即 thirdparty/AES/ 根）匹配，不会匹配子目录里同名模式的文件。
tiny-AES-c-*.tar.gz	匹配 lycium HPKBUILD 下载的 上游源码包（如 tiny-AES-c-1.0.0.tar.gz）。
作用	避免把 体积大、可重新下载 的源码压缩包提交进 Git。

---

/*.tar.gz 与 /*.tgz

要点	说明
/*.tar.gz	忽略 本仓库根目录下任意名称 的 .tar.gz（例如你本地打的 arm64-v8a.tar.gz 测试包）。
/*.tgz	同上，针对 .tgz 后缀。
为何带 /	同样 只作用在 AES 目录根；不会忽略 output/AES/arm64-v8a.tar.gz 这类在子目录里的包，从而满足「output 要提交」的需求。

---

*.zip

要点	说明
行首没有 /	会在 任意层级 匹配以 .zip 结尾的文件。
作用	上游或工具若产生 zip 包，一般也不需要进库；若将来 必须在子目录提交某个 zip，需用 ! 反忽略或收窄规则。

---

tiny-AES-c-*/

要点	说明
匹配 目录	解压后的 tiny-AES-c-1.0.0/ 整棵源码树被忽略。
作用	解压目录体积大、且 prepare/build 会改其中文件；应由 各开发者本地 build_hpk.sh 生成，不纳入版本库。

---

armeabi-v7a-build 与 arm64-v8a-build

要点	说明
无 / 前缀	在 任意路径下，名为 armeabi-v7a-build 或 arm64-v8a-build 的目录/文件都会被忽略。
对应关系	与 HPKBUILD 里 cmake -B"$ARCH-build" 生成的目录名一致（如 arm64-v8a-build）。
作用	CMake 构建树文件多、可复现，不必提交。

---

*-build

要点	说明
通配符 *	任意前缀 + -build 的名字都会被匹配（例如未来若出现 x86_64-build）。
与上一行的关系	armeabi-v7a-build 等已被上一行覆盖；本行是 兜底，防止漏网的新架构构建目录。
注意	范围较宽：若某合法目录名恰好以 -build 结尾且需要提交，需单独用 ! 取消忽略（当前 AES 仓库无此需求）。

---

*.log

要点	说明
任意目录下	所有 .log 日志文件忽略。
典型文件	download.log、各架构 lycium 构建日志 等（下面还有更具体的规则与之配合）。

---

last_error

要点	说明
匹配名为 last_error 的文件	build_hpk.sh 在失败时可能写入该文件。
作用	属于 本地构建状态，不应进库。

---

*-lycium_build.log

要点	说明
后缀匹配	如 AES-1.0.0-arm64-v8a-lycium_build.log。
作用	lycium 按包名/版本/架构 生成的构建日志，体积与内容随机器变化，忽略即可。

---

download.log

要点	说明
精确文件名	wget 下载时 build_hpk.sh 可能产生的日志。
与 *.log 的关系	已被 *.log 覆盖也无妨；单独列出是为了 一眼看出 下载日志也被刻意排除。

---

刻意「没有」忽略的内容（帮助理解）

以下类型 当前未出现在 .gitignore 中，因此 会被 Git 正常跟踪（若已 git add）：

• docs/ 下的技术博客与说明。
• HPKBUILD、HPKCHECK、README_zh.md、README.OpenSource、SHA512SUM、hnp.json、LICENSE 等适配元数据。
• output/ 目录及其中的 预置构建产物（与注释中的产品策略一致）。

若你本地还有 未列出的临时文件（如编辑器 Untitled），可视需要 追加规则 或 用全局 gitignore 处理个人习惯文件。

---

总结

• .gitignore 用 模式 告诉 Git 不要跟踪哪些路径；本文件针对 AES 适配目录 定制，核心是：忽略可再生的源码包与构建树、忽略日志与错误戳，同时不把 output/ 整体排除。
• 行首 / 表示 只匹配本目录根，这是 /*.tar.gz 与 output/ 里 tar 包可提交 的关键技巧。
• tiny-AES-c-*/ 与 *-build 覆盖 解压源码 与 CMake 输出；*.log 等清理 构建与下载痕迹。
• 升级 pkgver 或改 构建目录命名 时，记得检查 .gitignore 是否仍覆盖新的临时产物，必要时增删一行即可。

如需对照 实际构建流程，可结合 鸿蒙PC tiny-AES-c三方库适配实践.md 与 HPKBUILD 中的 builddir、packagename 理解 为何忽略 tiny-AES-c-*。

---

实战案例：如何修改 .gitignore

场景一：新增架构支持

假设要支持 x86_64 架构，需要添加对应的构建目录：

# 现有规则
armeabi-v7a-build
arm64-v8a-build
*-build

# 新增（如果 *-build 不够明确）
x86_64-build

说明： 由于已有 *-build 规则，实际上 x86_64-build 会自动被忽略。但显式写出可以提高可读性。

场景二：保留特定日志文件

如果需要提交某个重要的日志文件（如基准测试结果）：

# 忽略所有日志
*.log

# 但保留基准测试结果
!benchmark_results.log

注意： ! 表示反忽略，必须放在忽略规则之后。

场景三：忽略 IDE 配置文件

如果团队成员使用不同的 IDE：

# IDE 配置
.vscode/
.idea/
*.swp
*.swo
*~
.DS_Store

场景四：临时测试文件

# 临时测试
test_temp/
tmp_*.c
debug_*.log

---

.gitignore 模式语法详解

基础语法

模式	含义	示例
*	匹配任意字符（除 /）	*.log 匹配所有 .log 文件
?	匹配单个字符	test?.c 匹配 test1.c, testA.c
[]	匹配字符范围	*[0-9].log 匹配数字结尾的日志
**	匹配任意层级目录	**/test 匹配任何位置的 test 目录

路径相关

模式	含义	示例
/foo	仅匹配根目录下的 foo	/tiny-AES-c-*.tar.gz
foo/	仅匹配目录	build/ 忽略所有 build 目录
foo/**/bar	foo 下任意层级的 bar	test/**/output

否定模式

模式	含义	示例
!foo	不忽略 foo	!important.log 保留该文件

---

常见问题与解决方案

Q1: 为什么 output/ 下的 tar.gz 没被忽略？

A: 因为规则是 /*.tar.gz（带前导 /），只匹配根目录。如果写成 *.tar.gz（无 /），则会忽略所有层级的 tar.gz。

验证方法：

# 测试某个文件是否被忽略
git check-ignore -v output/AES/arm64-v8a.tar.gz

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

Q2: 如何忽略除某个文件外的所有文件？

A: 使用否定模式：

# 忽略所有 .log
*.log

# 但保留 important.log
!important.log

注意顺序： 否定规则必须放在忽略规则之后。

Q3: 为什么 .gitignore 对已跟踪的文件无效？

A: .gitignore 只对 未跟踪 的文件生效。如果文件已被 Git 跟踪，需要先移除：

# 从 Git 中移除但保留本地文件
git rm --cached somefile.log

# 然后提交
git commit -m "Stop tracking somefile.log"

Q4: 如何处理全局忽略？

A: 可以配置全局 gitignore：

# 设置全局 gitignore 文件
git config --global core.excludesfile ~/.gitignore_global

# 编辑全局忽略规则
echo "*.swp" >> ~/.gitignore_global
echo ".DS_Store" >> ~/.gitignore_global

建议： 个人编辑器相关文件放在全局 gitignore，项目相关文件放在项目 .gitignore。

---

与构建系统的配合

与 HPKBUILD 的关系

HPKBUILD 变量	对应 .gitignore 规则	原因
packagename	/*.tar.gz	源码包可重新下载
builddir	tiny-AES-c-*/	解压目录可重新生成
ARCH-build	*-build	CMake 构建树可重新生成

与构建日志的关系

日志文件	是否忽略	原因
download.log	是	下载过程日志，可重现
*-lycium_build.log	是	构建过程日志，可重现
last_error	是	临时错误标记
benchmark.log	可选	如果是基准测试结果，可能需要保留

---

验证与测试

检查文件是否被忽略

# 检查单个文件
git check-ignore -v tiny-AES-c-1.0.0.tar.gz

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

# 列出被忽略的文件（详细）
git ls-files --others --ignored --exclude-standard

测试 .gitignore 规则

# 创建测试文件
touch test_ignore.log

# 检查是否被忽略
git check-ignore test_ignore.log && echo "Ignored" || echo "Not ignored"

# 清理测试文件
rm test_ignore.log

调试复杂规则

# 使用 git add -n 模拟添加
git add -n .

# 查看哪些文件会被添加
git status

---

最佳实践总结

1. 分层管理

项目根目录 .gitignore
    ↓
thirdparty/AES/.gitignore (本文件)
    ↓
全局 ~/.gitignore_global

原则：

• 项目级：与构建相关的临时文件
• 全局级：个人编辑器和系统文件

2. 注释说明

# 构建产物 - 可重新生成
*-build/

# 源码包 - 可重新下载
/*.tar.gz

# 日志文件 - 构建过程记录
*.log

# IDE 配置 - 个人偏好
.vscode/

3. 定期清理

# 查看被忽略的大文件
git ls-files --others --ignored --exclude-standard | xargs du -sh | sort -hr | head -20

# 清理构建产物
git clean -Xfd  # 删除所有被忽略的文件

4. 团队协作

在团队中统一 .gitignore 规范：

• 使用相同的编辑器配置忽略规则
• 约定哪些日志需要提交
• 定期审查和更新规则

---

扩展阅读

Git 忽略机制原理

Git 检查忽略规则的顺序：

1. .gitignore 文件（当前目录）
2. 父目录的 .gitignore（向上递归）
3. .git/info/exclude 文件
4. core.excludesfile 配置（全局）

优先级： 后面的规则可以覆盖前面的规则。

常见陷阱

1. 空目录无法提交

   • Git 不跟踪空目录
   • 解决：添加 .gitkeep 文件

2. 已跟踪文件不受影响

   • 需要先 git rm --cached
   • 再修改 .gitignore

3. 顺序敏感

   • 否定规则必须在忽略规则之后
   • 更具体的规则应放在前面

---

实际应用示例

示例一：清理工作区

# 查看将被删除的文件
git clean -Xfd --dry-run

# 实际删除（谨慎使用）
git clean -Xfd

示例二：找回被忽略的文件

# 如果误删了被忽略的文件
# 可以从构建过程重新生成

# 重新下载源码包
./build.sh AES

示例三：临时修改规则

# 临时不忽略某个文件（用于调试）
git add -f some_ignored_file.log

# 或修改 .gitignore 后立即生效
# 无需重启 Git

---