在 CI 中处理文档

Posted 2023-03-30

【中文标题】在 CI 中处理文档

【英文标题】：dealing with documentation in CI

【发布时间】：2021-11-25 09:38:37

【问题描述】：

我们最近迁移到了 Git。我们的新仓库为 350MB，其中约 215MB (61%) 是名为 Documentation 的目录。除此之外，repo 还包含源代码和构建过程（TFS Build）用来生成安装程序的少数 WiX 项目。

主要用户（开发人员）不需要文档目录（它充满了半手工制作的 pdf 文件和其他打包到安装程序中的东西）。只有最终/CI 构建使用Documentation 目录。

我正在寻找有关如何在某处以这样的方式move out 文档的建议：

不妨碍开发人员（即 git clone 只需提取 ~135MB+ 的压缩数据） 保持构建过程简单，不会干扰正常的 CI 过程

我的一个想法是将文档移动到单独的存储库中并将其作为 Git 子模块导入。好像有点不方便，tbh...

【参考方案1】：

我的一个想法是将文档移动到单独的存储库中并将其作为 Git 子模块导入。

就是这样：

git filter-repo 可以处理拆分部分。参见例如“Detach (move) subdirectory into separate Git repository”。 请注意，它会重写主存储库的历史记录，因此请确保每个人都知道此迁移。 子模块可以track the latest commits from a branch，因此您的CI 流程可以通过git submodule update --remote 构建最新的文档修订版。

OP 在 cmets 中添加：

将文档移动到子模块的问题是，如果有其他子模块（开发人员需要它们）——他们将开始使用git clone --recurse-submodules，这也将克隆docs，这使得这种移动有点毫无意义。

它不必“也克隆docs”。

你可以exclude submodules when cloning your main repository

git clone -recurse-submodules=":(exclude)docs"

然后开发者可以声明子模块docsnot active。

git config submodule.docs.active false

所述子模块不会被克隆或更新。

【讨论】：

将文档移动到子模块的问题是，如果有其他子模块（并且开发人员需要它们）——他们将开始使用git clone --recurse-submodules，这也会克隆文档，从而使这个移出有点无意义。

@C.M.您实际上可以使用子模块，而无需克隆/更新该特定子模块 (docs)：请参阅上面我编辑的答案。

像魅力一样工作。谢谢！