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 with the github wiki.

I know that github wikis are plain git repositories. My plan is to add the wiki as a remote to my main repo and keep everything in one place. However in the wiki repo everything is in the root directory and thus would clutter my main project.

Has anyone tried this before? What is the best way to handle this?

Answer 1

You want to add the wiki as a submodule. Same Wiki git repo connected as a remote, but within a subdirectory with its own .git dir.

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

In the root of your main repo to add the wiki repo as a submodule in the wiki/ dir.

Answer 2

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...