在 Git 仓库维护过程中，空目录的处理是一个看似微小却影响深远的技术决策。长期以来，许多开发者习惯使用 .gitkeep 文件作为占位符，确保空目录被纳入版本控制。然而，这种做法不仅增加了仓库的冗余文件，也模糊了目录结构的语义边界。本文将从原理出发，阐述为何应当用本地 .gitignore 替代 .gitkeep，并给出可落地的工程参数与配置模板。
.gitkeep 的历史定位与局限性
Git 的核心设计哲学是追踪文件内容而非目录本身。当一个目录为空或仅包含被忽略的文件时，Git 不会将其纳入版本记录。这种行为源自早期版本控制系统的优化思路，但在实际工程中，空目录往往承载着明确的结构意图 —— 例如 logs/、tmp/、build/ 或 dist/ 等目录，它们是项目架构的必要组成部分，只是暂时为空或将在构建时动态生成内容。
为了绕过这一限制，社区逐渐形成了 .gitkeep 约定：在一个空目录中创建一个名为 .gitkeep 的空文件，使该目录不再为空，从而被 Git 追踪。这种做法在技术上是可行的，但存在几个显著问题。首先，.gitkeep 并非 Git 的官方特性，而是约定俗成的命名惯例，没有任何特殊的行为绑定，团队新成员可能会困惑于这一文件的来源与作用。其次，当目录中需要真正忽略某些文件类型时（例如 logs/ 目录下的日志文件），.gitkeep 无法同时表达「保留目录」与「忽略内容」两层语义，开发者不得不额外配置全局或项目级的 .gitignore 规则。最后，随着项目演进，使用了大量 .gitkeep 的仓库会积累许多意义不明的空文件，增加仓库的视觉噪声与维护成本。
本地 .gitignore 的工作原理
与 .gitkeep 不同，.gitignore 是 Git 的原生特性，用于声明哪些文件应当被忽略。在每个子目录中放置一个本地 .gitignore 文件，可以实现更精细的版本控制语义。具体做法如下：在需要保留的空目录中创建 .gitignore 文件，内容包含两行规则 —— 第一行使用通配符 * 忽略该目录下所有文件，第二行使用负向模式 !.gitignore 排除该 .gitignore 本身不被忽略。这种写法既保证了目录被 Git 追踪，又确保了除 .gitignore 外的其他文件都不会被意外纳入版本控制。
从语义角度看，本地 .gitignore 清晰表达了开发者的意图：该目录的结构必须保留，但目录内的临时文件、构建产物或日志文件不应被追踪。这种双重语义是 .gitkeep 无法提供的。对于那些需要在后续阶段填充内容的目录（如预留的 plugins/ 或 config/ 目录），本地 .gitignore 同样适用，开发者只需在需要时取消相应文件的忽略规则即可。
工程实践参数与配置模板
在实际项目中应用这一模式时，需要遵循几个关键参数以确保一致性与可维护性。以下是推荐的配置模板，适用于大多数常见场景。
对于纯粹的空目录占位场景，如预留的 docs/assets/ 或 uploads/ 目录，本地 .gitignore 应写成：
# Ignore everything in this directory
*
# Except this file
!.gitignore
对于需要在目录中存放但忽略特定类型文件的场景，例如本地开发时的日志目录，可采用更细粒度的配置：
# Ignore all log files
*.log
# Keep the directory structure but ignore build outputs
/build/*
!/build/.gitignore
在团队层面，建议在项目的根目录 .gitignore 中添加一条全局规则，说明空目录的维护策略，确保所有贡献者理解这一约定。同时，在 CONTRIBUTING.md 或 README.md 中明确列出目录结构的说明，新成员在克隆仓库后即可了解各目录的用途与忽略规则。
迁移策略与注意事项
对于已有大量 .gitkeep 文件的仓库，迁移过程应当谨慎进行。首先，可以使用以下命令找出所有 .gitkeep 文件：find . -name '.gitkeep' -type f。然后，根据每个目录的实际需求，决定是直接删除 .gitkeep 并添加本地 .gitignore，还是在保留 .gitkeep 的同时添加 .gitignore 以实现更精细的忽略控制。需要注意的是，删除 .gitkeep 本身是一次 Git 提交，仓库历史会保留这一变更，因此迁移前应确保团队成员了解这一变更的意义。
另一个值得关注的点是 CI/CD 流程中的目录依赖。许多构建脚本假设某些目录存在（如 dist/ 或 output/），使用本地 .gitignore 可以确保这些目录在仓库克隆后始终存在，避免因目录缺失导致的构建失败。此外，某些静态分析工具或代码检查器可能会对空目录发出警告，本地 .gitignore 的存在消除了这类误报的可能性。
总结
用本地 .gitignore 替代 .gitkeep 不仅是技术层面的优化，更是版本控制实践的成熟标志。这种做法利用 Git 的原生特性表达更清晰的意图，提供了更灵活的忽略策略，并减少了仓库中的冗余文件。对于追求工程整洁性与可维护性的团队而言，这一模式值得在项目中全面推广。通过本文提供的配置模板与迁移参数，开发者可以快速上手并在实际项目中落地实施。
参考资料
- Adam Johnson, "Git: Don't create .gitkeep files, use .gitignore instead"
- Stack Overflow, "What are the differences between .gitignore and .gitkeep"