如何将 GitHub wiki 集成到主项目中答案

【问题标题】：How to integrate a GitHub wiki into the main project如何将 GitHub wiki 集成到主项目中
【发布时间】：2011-08-04 12:47:36
【问题描述】：

我想将我所有的源代码和文档保存在一个 git 存储库中。我已经将 github 页面集成到我的主项目中，现在我想对 github wiki 做同样的事情。

我知道 github wiki 是普通的 git 存储库。我的计划是将 wiki 作为远程添加到我的主存储库中，并将所有内容保存在一个地方。然而，在 wiki repo 中，所有内容都在根目录中，因此会弄乱我的主项目。

以前有人试过吗？处理这个问题的最佳方法是什么？

【问题讨论】：

我选择了子模块。感谢您的回答。
将 wiki 作为子模块的情况如何？我想做类似的事情，但还没有考虑子模块业务。这将如何处理分支和合并，因为我希望我的代码的“开发”分支与 wiki 相同，所以当我将它与我的主分支合并时，它也会将更改合并到实时 wiki 分支。
但是将它作为子模块有什么意义呢？无论如何，其他人都无法修改或使用它。你可以在 github 之外的任何地方使用它吗？我的意思是你可以将它作为 github repo 放在一个单独的目录中，然后简单地从主 repo 中 .gitignore 那个目录。

标签： git github wiki

【解决方案1】：

您想将 wiki 添加为 submodule。相同的 Wiki git repo 作为远程连接，但在具有自己的 .git 目录的子目录中。

git submodule add git://github.com/you/proj.wiki

在主仓库的根目录中将 wiki 仓库添加为 wiki/ 目录中的子模块。

【讨论】：

现在实际上是git://github.com/you/proj.wiki
这是否允许您在 wiki 中所做的更改在图表选项卡中可见？
所以现在我cd proj.wiki 可以开始编辑了吗？那么在我编辑完我想要的内容之后我该怎么办？

【解决方案2】：

我觉得这一切都非常乏味 - 在我看来，github wiki 应该是主存储库的分支，或者至少应该可以选择它。

尽管如此，我认为最好的解决方案是简单地将 wiki 移动到主存储库中，例如在 docs/ 或 wiki 中，使用 subtree merge。例如，假设您的存储库是 you/proj，那么您的 wiki 将位于：git://github.com/you/proj.wiki。然后将它合并到你的主仓库中，你会这样做：

git clone git://github.com/you/proj
cd proj
git remote add -f wiki git://github.com/you/proj.wiki
git merge -s ours --no-commit --allow-unrelated wiki/master
git read-tree --prefix=wiki/ -u wiki/master
git commit -m "Github wiki subtree merged in wiki/"

您甚至可以让 wiki 继续工作以欢迎那里的公共贡献，然后在您认为合适的情况下将它们审核到您的主要文档中。要在审核后合并新更改，您可以：

git pull -s subtree wiki master

不幸的是，以另一种方式合并更改有点棘手，无论如何，您可能应该一次性执行此操作，然后关闭 wiki，或重定向到 repo 源...

此外，这种方法的一个主要警告是git log wiki/Home.md（例如）实际上并没有显示来自 wiki 页面的历史记录。历史在那里，但不知何故git-log 无法跟踪它。这是一个与 git 子树相关的known limitation。解决此问题的另一种解决方案是执行 filter-branch 并定期合并一次，以保留历史记录。

对我来说，将 wiki 作为主要源代码树的一部分的主要优势是可以跨代码和文档协调拉取请求和更改。它还使得随代码一起发布文档变得非常简单，而不是假设人们只会在线阅读它......

【讨论】：

就我而言，我仍然需要git push 才能将我的 wiki 文件夹完全提交给主项目 repo。
不知道为什么，但git log wiki/ 没有使用这种技术显示 wiki 的历史。我不明白为什么，因为git log --all 确实显示了这些变化......

【解决方案3】：

您可以创建一个包含 wiki 存储库的 submodule，也可以定期获取并来回切换分支。

【讨论】：

【解决方案4】：

您可以将 wiki 存储库的副本放入您的主存储库并并行使用它们：

$ git init
$ git remote add -m master origin git@github.com:<owner>/<repo>.git
$ git add .
$ git commit -m 'Initial commit'
$
$ cd wiki
$ git init
$ git remote add -m master origin git@github.com:<owner>/<repo>.wiki.git
$ git add .
$ git commit -m 'Initial wiki commit'
$
$ git push -uf origin master
$ cd ..
$ git push -u origin master

这种方法有点结合了其他答案中建议的子模块和子树的优点，但不会使工作流程复杂化：它允许您在主存储库中拥有 wiki 文件，在拉取请求中查看它们并轻松将它们推送到或从 wiki 中提取。

要将现有存储库的内容添加到另一个存储库，您需要删除 .git 文件夹一段时间（否则 Git 会将其添加为子模块）：

$ mv wiki/.git/ wiki/.git__/ && git add wiki/* && mv wiki/.git__/ wiki/.git/

这只是一次性问题，以后的任何文件都可以照常添加。

请注意，wiki 存储库的.git 文件夹不会包含在您的主存储库中。
This answer 描述了如何在克隆此类存储库后恢复它。

【讨论】：