4

I'd like to manage the GitHub wiki for my project at the same time as I'm developing the code. For example:

Branches

  • master (stable versions)
    • develop (development of next version)
    • Others... (Possible other dev / feature branches)

Ideally, I'd like the wiki to be contained in a subfolder (e.g. /wiki) of the project. Then when I'm making changes to the code I can also update the wiki as the same time (code + documentation change). It'd also mean that all my development code and documentation would be self-contained in the "develop" branch until I merge with the "master" branch. Hopefully, even if via a manual process, the GitHub wiki would then be updated after the merge with master to reflect the changes.

I've taken a look at Git's submodule feature, but from what I understand that usually points at a single revision. I'd like to somehow follow my code development so branching and merging would work as normal.

Peter Mortensen
  • 30,738
  • 21
  • 105
  • 131
Mister Dai
  • 796
  • 1
  • 6
  • 19
  • Did ever get it working? I have a [similar problem](http://stackoverflow.com/q/17021163/819272) with BitBucket. All the solutions with a wiki subrepo are ultimately doomed, I fear. What should be fixed is that the GitHub/BitBucket Wiki is a pointer to a particular commit on the main repo, not a separate repo. – TemplateRex Jun 10 '13 at 11:37
  • Never got this working and moved onto something else since so didn't need to investigate any further. At one point I was using a script to deploy my wiki changes to github when building my project, that worked well enough and meant I didn't have to worry about branches and submodules etc... – Mister Dai Jul 05 '13 at 09:34

2 Answers2

1

As explained in "True nature of submodules", you can make modifications and updates within a submodule, as long as you commit also the parent repo in order to record the new state of your "wiki" sub-repo.

Community
  • 1
  • 1
VonC
  • 1,262,500
  • 529
  • 4,410
  • 5,250
  • Thanks, that explains it better than the other information I found. How does it cope with branching / merging though? Can I have a "development" branch of the wiki in my "development" branch of the repository and then easily cope with merges to master? – Mister Dai Aug 01 '12 at 19:43
  • @MisterDai each repo (the parent repo and the submodule(s) repo(s)) have their own set of branches, independent from one repo to another. You can change branches at anytime in a submodule, provided you take the time to go back to the parent repo and commit, in order to record the new state of your submodule. – VonC Aug 01 '12 at 21:45
1

If you intend to use Gollum to display and work on your GitHub wiki while it's on your local machine (you probably should), then you will have a trouble if you use submodules.

Gollum wants to do local commits to your local Git repository (but not pushes), but in a submodule .git is actually a file containing the local repository, not a true Git repository. This causes Gollum to break.

Submodules also have the problems that the versions aren't coupled to the parent repository, and they aren't completely de-coupled. It a nuisance to have the source code repository to want to push the new wiki version number (but not the wiki contents) every time you make a documentation change.

The solution I use is simply to clone the wiki repository into a directory inside the main project directory and add it to .gitignore. By using a consistent name for the directory across projects (e.g. github-wiki), the chance is minimized that the wiki won't be in .gitignore and gets accidentally uploaded into the main repository.

For consistency, his approach also works well for GitHub pages, although it's unnecessary as they don't experience the problem with Gollum.

Peter Mortensen
  • 30,738
  • 21
  • 105
  • 131
Philip Callender
  • 1,465
  • 1
  • 14
  • 21