How to integrate a GitHub wiki into the main project

Question

I want keep all my source code and documentation in one single git repository. I already have the github pages integrated into my main project and now I want to do the same

Answer 1

I find this all pretty tedious - in my opinion, github wikis should be branches of the main repository, or at least it should be possible to make that an option.

Nevertheless, I believe the best solution is to simply move the wiki into the main repository, say in docs/ or wiki, using a subtree merge. For example, assuming your repository is you/proj, your wiki would be at: git://github.com/you/proj.wiki. Then to merge it in your main repo, you would do:

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/"

You can even keep the wiki working on the side to welcome public contributions there, but then vet them into your main documentation as you see fit. To merge the new changes in after review, you would do:

git pull -s subtree wiki master

Unfortunately, merging changes the other way is somewhat trickier, and anyways, you should probably do this as a one time thing, then close the wiki, or redirect to the repo source...

Furthermore, a major caveat of this approach is that git log wiki/Home.md (for example) doesn't actually show the history from the wiki page. The history is there, but somehow git-log fails to track it. This is a known limitation related to git subtrees. Another solution to fix this would be to do a filter-branch and a regular merge, one time, to keep history.

For me, the main advantage of having the wiki as part of the main source tree is that pull requests and changes can be coordinated across code and documentation. It also makes it trivially simple to ship documentation with your code instead of assuming people will just read it online...