The Git version control system can be used to check out your Branchable site, and make any changes you desire. Of course, you could just use the web interface to modify your site, but working from a git clone of your site lets you use your favorite editor, work offline, and own your data. So here's how:

  1. Install git on your computer if you haven't already.

  2. Visit your site's "Branchable" tab to look up the command to git clone it via ssh. Run that command to check it out.

  3. But first, click on the "ssh keys" link, and in the form add the ssh keys for you and anyone else who can commit directly to the site. Note that being able to commit directly to the site is equivilant to being an administrator of the site -- only add keys you trust!

  4. Now you have a git repository checked out for your site. cd into the repository. Edit files. Run git commit and git push. Your changes will immediately show up on the web. That's really all there is to it.

bonus: the setup branch

We've recently added a feature that allows you to commit changes to the ikiwiki.setup file for your site, too. That file lives in a special branch of your site, the setup branch. When you go to Preferences -> Setup on the web and make changes, those changes are committed to the ikiwiki.setup file for you. But you can also change it by hand:

  1. Check out your site following the directions above.

  2. Now git checkout setup -- this moves you to the setup branch. You can see the ikiwiki.setup file there.

  3. Make whatever changes you want and git commit. Don't worry about breaking it, your changes will be validated when you push.

  4. git push origin setup -- and away it goes!

If it liked your changes, you'll see something like this, and the new configuration will be applied to your site:

Counting objects: 5, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 302 bytes, done.
Total 3 (delta 2), reused 0 (delta 0)
remote: Updating site to reflect setup changes...
remote: generating wrappers..
remote: successfully generated /home/b-ikiwiki-hosting/public_html/ikiwiki.cgi
remote: successfully generated /home/b-ikiwiki-hosting/source.git/hooks/post-update
remote: refreshing wiki..
remote: done
remote: From /home/b-ikiwiki-hosting/source
remote:    68e1640..a33c123  setup      -> origin/setup
To ssh://b-ikiwiki-hosting@ikiwiki-hosting.branchable.com/
   68e1640..a33c123  setup -> setup

Some changes are not safe, and will be rejected. When this happens it's best to git revert the change, or re-edit ikiwiki.setup and undo the change. The error message will tell you what it didn't like. For example:

Counting objects: 5, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 323 bytes, done.
Total 3 (delta 2), reused 0 (delta 0)
remote: the following settings cannot be changed:
remote:     srcdir
remote:     destdir
remote:     url
remote: the following plugins cannot be enabled/disabled:
remote:     openid
remote: error: rejecting change to setup branch
remote: 
remote: error: hook declined to update refs/heads/setup
To ssh://b-ikiwiki-hosting@ikiwiki-hosting.branchable.com/
 ! [remote rejected] setup -> setup (hook declined)
error: failed to push some refs to 'ssh://b-ikiwiki-hosting@ikiwiki-hosting.branchable.com/'

I think I did something wrong and now branchable has merging issues when it's trying to pull from the git repository. (Sorry, branchable was slow yesterday, something must have gone wrong when I started editing from the web interface).

When doing a git push now I get

remote: Pull is not possible because you have unmerged files.
remote: Please, fix them up in the work tree, and then use 'git add/rm <file>'
remote: as appropriate to mark resolution, or use 'git commit -a'.
remote: 'git pull --prune origin' failed:  at /usr/share/perl5/IkiWiki/Plugin/git.pm line 218.
Comment by Hugo Fri Nov 1 15:19:58 2013

Hugo, I've fixed the problem. There was somehow a git conflict on the page tags/machine:totosh.mdwn

I have never seen this happen with ikiwiki before; it's supposed to use locking to prevent such problems, so any details about what happened would be useful.

Comment by joeyh.name Fri Nov 1 16:10:43 2013

BTW, Hugo, I noticed something in your sidebar:

<!--\[[!pagestats style="list" pages="./tags/*" among="*"]]-->

While it's commented out at the html level, this does not prevent ikiwiki from expanding the directive. Which means that any change to any tag on your entire site causes the sidebar to change, and requires rebuiding every other page on your site. This obviously makes it slow, and I strongly recommend removing that from your sidebar.

Comment by joeyh.name Fri Nov 1 16:13:20 2013

Hi Joey, Thanks for looking into this so quickly. For the page, I was editing it, but it was slow I was not sure why. So I stopped editing locally and pushing and I started editing online directly to add a picture to that page. Then something went wrong and there was a merge conflict showing on the page directly between the version with the image and the version without IIRC. I don't know what exactly.

About the commented directive, thanks for noticing. I'm very new to ikiwiki so I just assumed it would stay like this, but I did not check. It makes sense though. I'll change it.

Comment by Hugo Fri Nov 1 18:22:17 2013