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

Question

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

我知道 GitHub wiki 是普通的 Git 存储库。我的计划是将 wiki 作为远程添加到我的主存储库，并将所有内容保存在一个地方。然而，在 wiki 存储库中，所有内容都位于根目录中，因此会使我的主项目变得混乱。

处理这个问题的最佳方法是什么？

Answer 1

您想要将 wiki 添加为子模块。相同的 Wiki Git 存储库作为远程连接，但位于具有自己的 .git 目录的子目录中。

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

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

Answer 2

我觉得这一切都很乏味。在我看来，GitHub wiki 应该是主存储库的分支，或者至少应该可以使其成为一个选项。

尽管如此，我相信最好的解决方案是简单地将wiki移动到主存储库中，例如在docs/或wiki中，使用子树合并。例如，假设您的存储库是 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，或重定向到存储库源。 ..

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

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

Answer 3

现在，到 2023 年，只需要 3 个命令：

git clone https://github.com/youName/ProjectName.wiki docs
git submodule add https://github.com/youName/ProjectName.wiki docs
git submodule update --init

这将创建一个从 docs 文件夹到 Github 上项目的 Wiki 存储库的链接。不要使用“git://”，它已经过时了！到处使用“https://”！

Answer 4

您可以使用 wiki 存储库创建一个 子模块或者定期进行获取并来回切换分支。

Answer 5

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

git init
git remote add -m master origin [email protected]:<owner>/<repo>.git
git add .
git commit -m 'Initial commit'

cd wiki
git init
git remote add -m master origin [email protected]:<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 或从 wiki 拉取。

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

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

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

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

Answer 6

使用 子模块。此方法也可用于 GitHub 页面。

好处 - 作为主存储库脚本的结果更新 wiki。它将在主存储库中显示为链接目录，而不是常规目录。

cd your-project-repo

# clone your wiki
git clone https://github.com/username/your-project-repo.wiki.git
# go to your submodule i.e. wiki
cd your-project-repo.wiki
# make changes to wiki files
git commit -a -m "commit in submodule-wiki"
git push

# go back to your-project-repo
cd ..
git add your-project-repo.wiki/
# this commit message shows up in your-project-repo
git commit -m "Updated submodule"
git push