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 repository and keep everything in one place. However in the wiki repository everything is in the root directory and thus would clutter my main project.

What is the best way to handle this?

Earmuff

I went with the submodule. Thanks for the answers. – Earmuff

How's this going for you with the wiki as a submodule? I want to do something similar but haven't wrapped my head around the submodule business. How would this cope with branching and merging, as I'd like to have a "develop" branch of my code with the same for the wiki, so when I merge that with my master branch, it'd also merge the changes into the live wiki branch. – Antilogy

But what's the point of having it as submodule? Nobody else can modify or use it anyway. Can you use it anywhere outside the github? I mean you could have it in a separate directory as github repo and simply .gitignore that directory from main repo. – Saprolite

Answer 1

You want to add the wiki as a submodule. The same Wiki Git repository connected as a remote, but within a subdirectory with its own .git directory.

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

In the root of your main repository to add the wiki repository as a submodule in the wiki/ directory.

Malamud

Nowadays it's actually git://github.com/you/proj.wiki – Encasement

Does this allow your changes made in the wiki to be visible in the graphs tab? – Retroflexion

so now I cd proj.wiki and can I just start editing? then what do I do after I've edited what I want to? – Homozygous

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

Astoria

On my case I still need git push to get my wiki folders completely committed to the main project repo. – Girdler

not sure why, but git log wiki/ doesn't show history of the wiki with this technique. i don't understand why, because git log --all does show those changes... – Astoria

Answer 3

Now, in 2023, only 3 commands are needed:

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

This will create a link from the docs folder to your project's Wiki repository on Github. Don't use "git://", it's outdated! Use "https://" everywhere!

Bilge

Answer 4

You could either create a submodule with the wiki repo in it or do a regular fetch and switch branches back and forth.

Featureless

Answer 5

You could place a copy of a wiki repository into your main repository and work with them in parallel:

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

This method kind of combines the pros of submodules and subtrees suggested in other answers, but it doesn't complicate the workflow much: it allows you to have wiki files in your main repository, see them in pull requests and easily push them to or pull from the wiki.

To add a contents of an existing repository into another repository you'll need to remove the .git folder for a while (otherwise Git will add it as a submodule):

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

This is only a one-time issue, any future files can be added as usual.

Note that the .git folder of a wiki repository won't be included into your main repository.
This answer describes how to restore it after cloning such repository.

Borneo

@PeterMortensen What's wrong with syntax highlighting? At least it highlights strings... – Borneo