如何將 GitHub wiki 集成到主項目中

Question

我想將所有源代碼和文檔保存在一個 git 存儲庫中。 我已經將 github 頁面集成到我的主項目中，現在我想對 github wiki 做同樣的事情。

我知道 github wiki 是普通的 git 存儲庫。 我的計划是將 wiki 作為遠程添加到我的主存儲庫中，並將所有內容放在一個地方。 然而，在 wiki 存儲庫中，所有內容都在根目錄中，因此會使我的主項目變得混亂。

有沒有人試過這個？ 處理這個問題的最佳方法是什么？

Answer 1

您想將 wiki 添加為子模塊。 相同的 Wiki git repo 作為遠程連接，但位於具有自己的 .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，或重定向到 repo 源...

此外，這種方法的一個主要警告是git log wiki/Home.md （例如）實際上並未顯示來自 wiki 頁面的歷史記錄。 歷史就在那里，但不知何故git-log無法跟蹤它。 這是與 git 子樹相關的已知限制。 解決此問題的另一種解決方案是進行一次filter-branch和常規合並，以保留歷史記錄。

對我來說，將 wiki 作為主要源代碼樹的一部分的主要優點是拉取請求和更改可以跨代碼和文檔進行協調。 它還使得隨代碼一起發送文檔變得非常簡單，而不是假設人們只會在線閱讀......

Answer 3

您可以創建一個包含 wiki 存儲庫的 子模塊，也可以執行常規獲取並來回切換分支。

Answer 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 文件，在拉取請求中查看它們並輕松地將它們推送到或從維基。

要將現有存儲庫的內容添加到另一個存儲庫中，您需要暫時刪除.git文件夾（否則 Git 會將其添加為子模塊）：

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

這只是一次性問題，以后的任何文件都可以照常添加。

請注意，wiki 存儲庫的.git文件夾不會包含在您的主存儲庫中。
這個答案描述了在克隆這樣的存儲庫后如何恢復它。