It’s Clobbering Time

Remember that thing I said back at the end of 2012? That thing? That thing about the important detail that:

the _deploy/ subdirectory is itself a clone of the targeted github repository, with the gh-pages branch checked out.

It turns out this is really important detail.

Here’s why: For my first blogging act of the new year, I inadvertently destroyed my own blog.

I attempted to write a post from a computer other than the one out of which I had already worked all the octopress-compatibility kinks. In the hustle of dealing with rbenv and various other ruby-oriented dependencies, I forgot about the detail above.

And then when I ran rake deploy, I clobbered the live blog.

I may have been recovering from, or incapacitated by, New Years revelry at the time, it is not clear to me at the current moment. I believe I identified the disaster right after it happened, but immediately decided I did not have the time then to diagnose it, fix it, or even to attempt to rollback the state and repush to github. I vaguely remember considering that last option and deciding that even that was out of the question. (I think a pending trip to a Karaoke bar may have been involved in the decision-making process here.)

So, tonight I diagnosed and fixed the problem.

At first I was just going to let the matter lie undocumented, and pretend like it never happened.

But I realized that I may well again make the same mistake in the future, and that it behooved me to at least document the issue in my commit log for the blog source.

And after writing that commit log entry and pushing it, I decided that this story was in fact blog worthy; after all, what is the point of a blog if not to freely broadcast your mistakes? :)

So, directly from my commit message, here is the description of how I clobbered my own blog:

The easy way to sum it up is: The model employed by octopress when deploying to github is this: Your deploy/ subdirectory must contain a checkout of the target repo, the one with the gh-pages branch, and you must have that deploy/ subdirectory checked out and ready to go before running ‘rake deploy’.

If you do not have a _deploy/ subdirectory at all and you let ‘rake deploy’ create it for you but you also let ‘rake deploy’ attempt to push to github, and you are also managing the source itself on github, you will enter a world of pain where the rake invocation will push this root directory, presumably in the master branch (or in my case, blog.pnkfx.org branch) to the target repo in the gh-pages/ branch. Which will bust things terribly, especially if that causes the CNAME file to get deleted from the gh-pages/ branch of the target repo.

A note on self-reference

Also, a quick half shout-out, or maybe corrective note, to seamusbradley for pointing out some details about linking back to one’s own blog posts.

It is only a half shout-out because Seamus’s note is only useful, I think, if you have, like him, a customized setting for the root: in your _config.yml. That, or Seamus has confused himself and changed his root setting in order to accommodate other url’s that he observed, but those urls are in fact actually generated by settings for properties other than root.

Here’s the concrete details: I read (misread?) Seamus’s post at first as saying that a customized setting of root to /blog is a prerequisite for linking to your own posts. It seems to me that the relevant detail is what the permalink setting is, not the root. (But then again, I have not played with changing my root setting, apart from finding that when I did try changing it to /blog as Seamus suggested, it seems like doing so broke rake preview.)

In my case, the root and permalink for my _config.yml are set as follows:

root: /
permalink: /blog/:year/:month/:day/:title/

and I format links to my own posts, such as the one you are reading, like so: /blog/2013/01/08/resurrected-hello-again-world as you can see from looking at the source for the line above,

[`/blog/2013/01/08/resurrected-hello-again-world`](/blog/2013/01/08/resurrected-hello-again-world)

A bit of quoted self-reference is a good place to stop for the night.