锁定 GitHub 分支、标签与提交版本生成精准 Markdown PDF 手册

软件技术文档通常随版本迭代而频繁变更。如果直接从仓库的默认分支导出文档，很可能会不小心引入尚未正式发布的实验性特性或接口变动。通过 md2pdf，您可以精准锁定指定的 Git 分支、发布标签（Tag）或不可变的提交哈希（Commit SHA），生成与生产版本严格对应的 PDF 手册。

本文将解析 Git 引用锁定的工作机制、各类引用的适用场景，以及制作高可靠版本化文档的具体方法。

为什么技术文档必须进行 Git 引用锁定

在为企业私有化部署或长期支持（LTS）版本生成使用手册时，文档内容必须与用户正在运行的软件版本严密契合。

• 生产环境一致性：确保 PDF 手册只描述当前正式环境已上线的接口与配置，杜绝尚未发布的试验性内容。
• 审计与合规追溯：在安全审计或合规认证中，从特定提交哈希生成的不可变文档可作为系统真实状态的客观证据。
• 历史版本归档：无需在本地克隆庞大的旧版仓库代码，即可一键重现旧版软件的完整配套文档。

Supported Git Reference Types:
- Branch:  refs/heads/v2.1-maintenance
- Tag:     refs/tags/v2.1.0-lts
- Commit:  7f2b9a1d4e8c3b0f5a6d7e8c9b0a1f2e3d4c5b6a

针对正式手册使用发布标签（Tags）

发布标签标志着软件开发生命周期中的稳定里程碑。在 md2pdf 中输入带有标签的仓库链接或在界面中选择标签后，系统将仅调取该发布节点的快照数据。

1. 自动识别标签：解析仓库时，md2pdf 会自动列出所有语义化版本标签（如 v1.4.0、v2.0.0-rc1）。
2. 快照文件抓取：所有文档完全锁定在该版本发布时刻的内容，杜绝后续提交的潜在干扰。
3. 醒目版本标识：您可以在封面或页眉处印上版本标签，便于团队成员与读者快速核实文档适用范围。

锁定长期维护分支（Maintenance Branches）

当团队为旧版发布紧急安全补丁时，文档修正通常会先同步推送到专门的维护分支上。

通过指定如 support/3.x 或 v1-stable 等分支，md2pdf 能够直接拉取该维护分支上的最新文档。这样既能获取关键勘误，又避免了主分支不稳定代码的渗入。

使用提交哈希（SHA）获得不可篡改的归档版本

为了实现最高级别的可重现性，使用完整的 40 位 Git 提交哈希是最佳选择。与分支和可变标签不同，提交哈希在数学上是不可篡改的。

在 md2pdf 中指定 Commit SHA 后，系统将调取该精确时刻的 Git 树。即使项目作者之后强行覆盖历史或删除分支，您导出的 PDF 依然真实记录着该时刻的完整技术状态。

在 md2pdf 中切换引用的操作指南

在 md2pdf 中配置 Git 引用十分直观：

1. 在仓库输入框中粘贴目标仓库链接。
2. 展开引用选择下拉列表，查看现有的分支与标签。
3. 选择对应的标签、分支，或直接在输入框中填入提交哈希。
4. 浏览目录树并挑选文档，一键编译出排版精致、版本精准的技术 PDF 文件。