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?

Answer 1

Integrating a GitHub wiki into the main project is easier using a submodule. This method can also be used for GitHub pages.

Benefits - update the wiki as an outcome of a script from the main repo. It'll show up as a linked directory in the main repo rather than a regular directory.

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

Answer 2

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!

Answer 3

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

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.

Answer 4

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

Answer 5

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.

Answer 6

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