How do YOU develop software?

Want to do your part for software engineering research? Participate in the annual University of Victoria developer practices survey and help us to build a picture of how developers create software in 2013.

How do YOU develop software?.

20 hrs in Hacker News Top 10

Including a GitHub Wiki in a Repository as a Submodule

  • Problem

    • You are using GitHub to host your project and your using the GitHub Wiki to maintain your documentation. Now you want to create a release of your project including a current snapshot of the documentation. But because the documentation is separate from the code repo you have to somehow export the Wiki and then put that into the main repo each time you want to make a release. This is just plain messy and in the long term will probably lead to the documentation getting separated/lost or being duplicated in many places.
  • Solution

    • Because the GitHub Wiki is itself a git repo we can include the Wiki in the main code repo as a submodule.
    • A submodule is conceptually a git repo inside another git repo, changes to each repo are independent, but the parent repo is linked to the child repo by a commit pointer.
  • Benefits

    • We get what we want above, namely a standard way of including documentation in a release
    • We can take full advantage of the GitHub Wiki being a git repo, allowing us to point our documentation submodule at any version/branch of the Wiki we choose
    • Editing of the documentation can be done on the GitHub website or by developers in their local copy when they pull the documentation submodule
  • Risks

    • Switching from a branch that includes the submodule to one that doesn’t can cause a few small issues which I note below.

This article describes how to include the GitHub Wiki as a submodule in a GitHub project (or any git repo for that matter).


Lets say we have a GitHub repo called “project” and we want to include the associated Wiki as submodule in a dir called “docs”. We want the following dir structure:

- parent
    - docs

Setup – Clone submodule into existing repo

This section deals with setting up a submodule for the first time.

Get the address of your Wiki repo, it will be something like this:

Add the Wiki repo as a submodule “docs” to a dir within the “project” local copy:

$ git submodule add docs

Commit the addition of the docs submodule to the parent repo:

$ git commit -m 'first commit with submodule docs'

Push the change to the remote server:

$ git push

Lets look at whats in “docs”

$ cd docs

If you look in the docs dir you’ll notice that its currently empty. You have to initialize the submodule and update it separately. Do the following:

$ cd..
$ git submodule init
$ git submodule update

The submodule is now setup and the docs dir should now have the Wiki docs in it.

Update the docs Submodule

One you have the submodule setup you can pretty much forget about it. However, if someone pushes changes to the parent repo that includes changes to the submodule you can pull them down as normal.

$git pull

This will pull down a new commit pointer for the submodule but it wont update the files in the submodule. Instead you need to merge the new submodule commit pointer (basically overwriting the existing submodule commit pointer)

$git merge origin/master

Now that the submodule pointer is pointing at the correct submodule commit you can do your submodule update

$ git submodule update

This will pull down the changes to the submodule up to the commit that came down in the parent pull

I know it seems like a lot but its actually pretty simple if you think about it, normally you will just use the following commands to pull and merge changes to the submodule:

$git pull
$git merge origin/"branch"
$git submodule update

Make changes to the docs submodule

If you want to make changes directly in the docs submodule for example manually editing the Wiki files or pulling down changes to the Wiki repo made by other developers. Its just like working with any repo except you do two commits, one in the submodule and one in the parent:

$ cd docs

Notice that docs is at a particular commit not on a branch, if you make changes you probably want to checkout the master or another branch.

$ git checkout master

Make your changes and commit as normal (note you are now committing to the submodule repo)

$ git commit -am "changed wiki files"

Now push to the remote, it is really really important that you remember to push submodule commits to the remote (see Gotcha 2).

$ git push

Now got back to the partent project and do another commit, that basically says I have updated the submodule which is in you, here is a pointer to the new version of the submodule

$ cd..
$ git commit -am "updated docs submodule"

Push the changes to the remote

$ git push

Cloning a project containing a submodule

If you are cloning a project that contains an existing submodule, all you need to do after cloning the repo as normal is to initialize the submodule:

$ git submodule init
$ git submodule update


  1. Once you have initialized a submodule in a branch, if you checkout a branch that does not contain that submodule, git will see the directory as un-tracked. This may happen until all branches have been updated to contain the submodule. Its not a major problem, just don’t commit that un-tracked directory and you should be ok until the submodule gets merged into the branch. See the link below on how to deal with this.
  2. If you commit changes to the submodule locally and don’t push those changes to the remote and then push commit and push changes to the parent the parent repo will now point at a Wiki repo commit that doesn’t exist on the remote. Luckily if its just documentation you probably wont break someone else’s local repo if you do this, but its still not a good idea.

Export Outlook Rules to Gmail Filters

I live in Outlook, I know its terribly unfashionable in the age of thin clients and the cloud but I just can’t give it up, for what I need it just works. I recently wrote this small tool to help me export rules that I define in outlook so that I can import them into Gmail as filters and have then run on the server rather than on the client. You can grab the code from GitHub by clicking here (Code) or download it below.

UPDATE – 9/7/2013
– Version 0.0.2 is current stable version
– 1500+ downloads on GitHub – Thank you.
– Added support for some new rule types see GitHub


0.0.2 – supports more rule types (Stable version)
0.0.1 – only supports from move-to-folder rules

– See instructions here

Stack Overflow FCSD 2012 Poster

Still catching up with posts after moving my blog. This is a poster I created for our presentation at Future of Collaborative Software Development Workshop 2012 which was held February in Seattle co-located with CSCW 2012 (Poster) (Paper).

Tagged , , ,

Git + LaTeX + TeXnicCenter

Using Git and LaTeX can be fun to get up and running, but its even more fun if you want to use an editor like TeXnicCenter.

The main problem in using TeXnicCenter and attempting to collaborate with others over git is what to do with TeXnicCenter project and Latex build files. By default these files will be put in the directory where your tex files are which will cause problems when you go to push your changes. You can add all the files to .gitignore but that is a bit of a pain. Instead create a sub directory (lets call it “projectFiles”) and copy all the build files into it. Then in TeXnicCenter open Build -> “Define Output Profiles” and add the following to the latex compile command line arguments “-aux-directory=projectFiles” Now when you compile Latex all the build files will be put in this directory.

If you are using projects in TeXnicCenter then you will have one further .tcp file in the root directory. This is the project settings file. You can manually move this to the “projectFiles” directory also but make sure to update the path to the MainFile to reference the parent directory. For example “../Main_file.tex”.

Also to get BixTeX to build you will have to specify where you moved the .aux file so open Build -> “Define Output Profiles” and add the following to the BibTex command line arguments “projectFilesPath\%tm” replacing projectFilesPath with the full path to the project files folder. Note if you have other arguments already in there you might to overwrite.

Now that we have all the build and project files organized we can simply add an entry to .gitignore to instruct it to ignore the “projectFiles” directory.

Get updates changes from Git

git fetch origin
git merge origin/master

Push you changes

git commit -am 'comment'
git push origin master

Tagged ,

Blog Moved

Normal service is resumed, which means I’ll probably be back here in a year or so😉

VS 2010 Disabling script debugging

This is an update to my previous post about disabling script debugging in VS 2008. To disable script debugging in VS 2010 add the following registry key using the command prompt (note your just updating the VS version number);

reg add HKLM\SOFTWARE\Microsoft\VisualStudio\10.0\AD7Metrics\Engine\{F200A7E7-DEA5-11D0-B854-00A0244A1DE2} /v ProgramProvider /d {4FF9DEF4-8922-4D02-9379-3FFA64D1D639} /f


Default config of IIS 7 does not include ASP or ASP.Net?

When installing IIS onto vista or windows 7 in “Turn Windows features on or off” dialogue you might for example click on the root tree “Internet Information Servcies” to indicate your wish to install all sub components and features, however clicking on the root of the tree is not enough as you actually have to drill down to find the web development sub tree open that and then select the leaf nodes for (and ASP if you need it).

Really non intuitive tree control, i understand that it is giving me a recommended configuration rather than installing everything which very few users will need, but i think the design of the control is not obvious.

Visual Studio – multiple instances of development web server

In Visual Studio (2005, 2008 & 2010), if you have multiple web projects in a solution a separate instance of the development web server “Cassini” is launched for each web project when debugging. If you are only debugging a single web project all these instances are probably unnecessary. Setting a single startup project in the solution properties menu does not solve this issue, instead you have to explicitly stop each web project from launching a server instance. This is done through the properties grid in the properties window (View -> Properties Window) for the web project not through the Properties menu (right click on web project -> properties) (someone please give me  a good reason why there are 2 properties menus).

In the properties grid for the project you want to exclude, simply change the “Always Start When Debugging” property to False. This prevents a server instance being created for that web project, rinse and repeat for other projects you don’t care about.


Get every new post delivered to your Inbox.

Join 75 other followers

%d bloggers like this: