是否应该将生成的文档存储在Git存储库中？

当您使用jsdocs之类的工具时，它会根据代码中的注释在代码库中生成静态HTML文件及其样式。

应该将这些文件检入Git存储库中，还是应该使用.gitignore忽略它们？

缺少任何特定需求时，不应检入使用版本控制中签入的其他文件通过构建工具生成，重新创建，构建或生成的任何文件。需要该文件时，可以从另一个文件（重新）构建该文件。源（通常是构建过程的某些方面）。

因此，应使用.gitignore忽略这些文件。

我的规则是，当我克隆存储库并按“构建”按钮时，一段时间后，所有内容都将构建。要针对生成的文档实现此目的，您有两种选择：要么由某人负责创建这些文档并将其放入git，要么在我的开发机器上准确记录我需要的软件，然后确保按“ build”按钮可在我的计算机上建立所有文档。

在生成文档的情况下，我对头文件所做的任何单个更改都应更改文档，因此在每个开发人员的计算机上执行此操作更好，因为我一直希望正确的文档，而不仅是在有人更新文档时。在其他情况下，生成某些东西可能很耗时，复杂，需要您仅拥有一个许可证的软件等。在这种情况下，让一个人负责将内容放入git会更好。

@Curt辛普森：把所有的软件需求文档是好了很多，比我在很多地方都看到了。

不应检入这些文件，因为已经存在生成它们的数据。您不想两次存储数据（DRY）。

如果您有CI系统，则可以制作该文档并将其存储，然后将其发布/发布到Web服务器。

将它们放在某个存储库（最好是自动生成的相同或不同的存储库）中的一个好处是，您可以看到对文档的所有更改。有时，这些差异要比源代码的差异更易于阅读（特别是如果您只关心规范更改，而不是实现之一）。

但是在大多数情况下，不需要将它们置于源代码管理中，如其他答案所述。

忽略了。您将希望使存储库的用户无论如何都能重建它们，并且消除了确保文档始终保持同步的复杂性。如果您希望将所有内容都放在一个地方而不需要构建任何东西，那么没有理由不将构建的工件捆绑在一起。但是，尽管由于那里的复杂性比大多数地方所造成的损害更大，但源存储库并不是真正适合这样做的好地方。

这取决于您的部署过程。但是将生成的文件提交到存储库是一个例外，应该尽可能避免。如果你能回答两个与下面的问题是，在你的文档检查可能是一个有效的选项：

• 文档是生产的要求吗？
• 您的部署系统是否缺少构建文档的必要工具？

如果满足这些条件，则可能是在使用旧系统或具有特殊安全性约束的系统进行部署。或者，您可以将生成的文件提交到release分支中，并使master分支保持干净。

这取决于。如果这些文档：

• 需要像一样成为存储库的一部分readme.md，那么最好将它们保留在git repo中。因为以自动化方式处理这些情况可能很棘手。

• 如果您没有像CI系统那样自动构建和更新它们的方法，并且打算让普通读者看到它，那么最好将它们保留在git repo中。

• 需要大量时间来构建它们，然后有理由保留它们。

• 旨在供一般读者看（如用户手册），并且花费大量时间来构建，而以前的文档变得无法访问（脱机），因此有理由将其保留在git repo中。

• 旨在向普通读者展示，并且必须显示其更改/演进的历史记录，可以更轻松地提交以前的文档版本，并构建/提交与以前的文档链接的新版本。有道理。

• 对于所有团队都有特定的公认原因，那么有理由将他们保留在git repo中。（我们不知道您的情况，您和您的团队知道）

在任何其他情况下，都应安全地忽略它。

但是，如果有理由将它们保留在git repo中，则可能表明您的团队面临着另一个更大的问题。（没有配置项系统或类似的，可怕的性能问题，在构建过程中面临停机等）

作为版本控制的原则，只有“主要对象”应该存储在存储库中，而不是“派生对象”。

该规则有例外：即，当存储库的使用者需要派生对象，并且可以合理地期望它们没有生成它们所需的工具时。其他考虑因素也在考虑之中，例如材料量是否繁琐？（让所有用户拥有工具对于项目来说会更好吗？）

一个极端的例子是一个项目，该项目实现了一种罕见的编程语言，其编译器是用该语言本身编写的（众所周知的示例包括Ocaml或Haskell）。如果只有编译器源代码在存储库中，则没有人可以构建它；否则，任何人都无法构建它。它们没有可在虚拟机上运行的编译器的编译版本，因此它们可以编译该编译器的源代码。而且，该语言的最新功能会立即在编译器源代码中使用，因此始终需要接近最新版本的编译器来构建它：单独获得一个月的编译器可执行文件不会编译当前代码，因为该代码使用了一个月前不存在的语言功能。在这种情况下，几乎可以肯定必须将编译器的编译版本检入到存储库中并保持最新状态。