Octopress and Github Pages work great together to host a small site in a way that feels very developer friendly. The documentation for Initial Setup and Deploying to Github Pages do a great job of walking through the process of getting started. However, there’s not much documentation to be found about working with collaborators, or setting up development on a shiny new machine.

NOTE : The process described here works for “user pages” and “organization pages” on Github. The process will be somewhat different for “project pages” since project pages are driven from the gh-pages branch instead of master.

In working with Rob on the OkcRuby site, we kept running into issues when we’d try to deploy a change. We could get around the problem by force pushing, but that didn’t seem like a good long term path. Here’s a process that we’ve found to work. The code examples are assuming that you want to collaborate on OkcRuby, which you should…

The most important thing to know is that you should never work directly in the master branch, but in the source branch. Octopress automates the process of getting changes into the master branch, so making changes directly there can really mess things up. It’s best to not even keep a local master branch.

To checkout the repo with only the source branch you can add -b source to the git clone command:

git clone git@github.com:okcruby/okcruby.github.io.git -b source okcruby.github.io

Then you need to setup the _deploy directory:

mkdir _deploy
cd _deploy
git init
git remote add -t master -f origin git@github.com:okcruby/okcruby.github.io.git

The _deploy directory is managed by Octopress and is populated during the deployment process. _deploy is set to track the master branch of the main Github repo, and Octopress will manage the process of keeping the local branch in sync with the remote. You should never work in or commit to the _deploy directory.

Anytime that you want to make changes to the site you should first make sure that you’re on the source branch, and then pull from the Github repo (from the source branch).

git checkout source
git pull --rebase

Then make your changes and commit (again with the source branch). Then to deploy you can run:

rake generate
rake deploy

Also don’t forget to push your source changes.

git push

Thanks to Wei Shi for publishing info about the fix for the _deploy directory and to Rob ‘DataChomp’ Sullivan for helping me test this process.