As announced previously, I’ve recently converted my blog over to Octopress. This was not without a few stumbling blocks on Windows using Posh-Git. I’ve also recently started to suspect some issues with Posh-Git now that I am using it on a daily basis.
In this post, I am documenting the procedure for future installs on Windows; and, maybe I can help someone else who runs across the same issues.
Ruby on Windows? No, Yari on Windows
This is my first exposure to Ruby. I know, I’ve been closed off to anything non-.NET since, well, .NET in 2002. With that the first steps to getting ruby installed. A few quick searches yielded some issues with Windows and Ruby and Octopress, until I ran across Robert Anderson’s Octopress install.
They key point to this type of installing is this golden snippet:
Use yari instead of RVM/rbenv
Scott Muc has written yari which lets you switch between Windows Ruby versions.
Once all dependencies are fixed up, it’s onto following the setup guide over at Octopress:
> rake setup_github_pages
Now, I am going to use GitHub Pages for my static blog hosting. Those are the instructions I am going to focus on here and below.
The next step is to call the task to setup your repo for GitHub deployments. Just take a quick gander a what it does, as listed on the Octopress install guide:
- Ask for and store your Github Pages repository url.
- Rename the remote pointing to imathis/octopress from ‘origin’ to ‘octopress’
- Add your Github Pages repository as the default origin remote.
- Switch the active branch from master to source.
- Configure your blog’s url according to your repository.
- Setup a master branch in the _deploy directory for deployment.
If that sounds like a lot, wait until you see what actually does happen below. So, we’ll run it and look at the output:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
Btw, kudos to the developers of Octopress to put this much output in the build processes – makes things much easier to debug than the vast majority of scripts you run.
But doh! We have our first stumbling blocks. We have a number of errors to work out here, three exactly.
line 7 is an extremely common problem when working git. Unfortunately though,
the common fixes doesn’t seem to work with any Posh-Git install I’ve used to date.
Before we get to that though, let’s take a look at the ruby task to see exactly what is going on before we jump to any conclusions.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59
Let’s step through what this task does to our repo:
Ok, no problem. We are renaming origin. But what you don’t know is with Posh-Git, when you rename origin, it seems creates an empty origin! So, when the next system command executes:
1 2 3 4
We get our first error,
fatal: remote origin already exists.
Ok, back on task of what the
RakeFile is doing to move forward.
1 2 3 4 5 6 7 8 9 10 11
Interesting. I haven’t seen this in my git-ninja code before. A quick Google and we come up with this SO answer on how to setup master to track a remote branch:
You can do the following (assuming you are checked out on master and want to push to a remote branch master):
Set up the ‘remote’ if you don’t have it already
# git remote add origin ssh://…
Now configure master to know to track:
# git config branch.master.remote origin
# git config branch.master.merge refs/heads/master
# git push origin master
So now we have master tracking a remote branch and on
line 29, we’ve renamed master to a new branch
source (which also switches us to
source for future commands).
1 2 3 4 5 6 7 8 9 10 11 12
Ah, we are create a new directory (
_deploy by default Octopress config) and by calling
git init we create a new bank repo! This was not clear to me as to why at first, until I got things
working. You’ll see why in a bit.
And look here, on
line 46, we have our 2nd error in the output. It would seem this
is a parsing typo on Windows machines. So, we never get this index.html file! No biggie,
we’ll be replacing that very shortly anyways.
Let’s move forward.
This is my first Ruby playground, so I am not exactly sure what this line does. I would say we create a branch called gh-pages, but that is for GitHub Projects (for corporate accounts), not our GitHub Pages that we using here.
I suspect the
unless branch == 'master' is what prevents this line from running on my installation.
1 2 3 4 5 6 7 8 9 10
Finally we are at the end. Let’s see, back on
line 48 we are sitting in a new directory
_deploy with a new clean
git init. So, on
line 50 we add a remote for origin…
And get our 3rd and final error, that we have already seen before.
fatal: remote origin already exists
As I mentioned earlier, this is most likely because Posh-Git already creates an origin and never leaves an empty remote.
I’ve seen this fatal: remote origin already exists
error all too often and it usually means you already have an origin and cannot add another one. Usually
git on Linux allows you to fix with a set of simple and meaningful commands:
1 2 3 4 5
But this has never worked for me using Posh-Git. When trying to remove origin with Posh-Git, you get a new and blocking error:
Searching online basically leads you to a dead end in that this normally works using other versions of git. I did stumble upon
a related SO question about remotes using
set-url, which lead me to come up with this solution:
1 2 3 4
As you can see, the
rake setup_github_pages has renamed our origin to octopress. But Posh-Git seemed to have created
another empty origin and it won’t the script add one. Let’s fix that:
1 2 3 4 5 6
There we go. Let’s
setup_github_pages script again, shall we?
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
Well crap. We still get that
fatal: remote origin already exists on
line 17 error after all we did!
Ah, but remember what I said earlier about a directory called
_deploy? They are making a new repo
and setting up the
So, we have to set that
origin ourselves again.
1 2 3
This is just checking to see what was there and as we suspected the
git remote add origin command in the task did not work.
You may also notice that when you change directories to the
_deploy new repo, we are on
master now of a different repo.
We were previously on `source’ branch of the root repo from the previous scripts.
So let’s fix that up.
1 2 3 4 5 6
There we go. All fixed up and ready to continue. Make sure to change directories
cd .. to backup to where you were
At this point, it is not necessary to run the
rake setup_github_pages again because the script continues even with
errors, as we’ve seen above. The last part of the script seems to modify the
RakeFile. We’ll leave that for another
topic as we want to keep hacking on our new blog to get it up.
To the keen observer, you may notice that we have two branches of the same repo:
The first part of Octopress’ instructions for github actually branches what you cloned from Octopress’ github
into a source branch. Ok, check.
But recall that we created a sub-directory called _deploy and we git init a new clean repo there. It was
already set to master, and finally we made its origin the same as our original source.
What this means is now you will have two branches with completely different code. Your source branch is what
you will work from, commit to and push up. While the Octopress ruby framework will handle the generation of the
static site and deployments to the master branch.
The last piece to remember is that GitHub Pages will only use the master branch to serve your static site.
Sweet! Our website (aka master branch) will be nice and clean based on this _deploy directory, whereas
our source branch will be the work committed.
This runs without issue.
Aw shit, it would seem we still have some issues because this task generates errors:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
We got two errors to sort out. Let’s take a look at the first one.
fatal: No remote repository specified. Please, specify either a URL or a remote name from which new revisions should be fetched.
Humm, this sounds like a
git pull was issued. Let’s take a look at the ruby commands for this. Again, thanks to
the great output from the developers, a quick search in the
RakeFile finds this code.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
Ah hah, there marked on lines 5 and 6 is the
git pull for the
_deploy directory. Smart, they are pulling down any
changes you may have made manually to your static pages. For example, using GitHub’s edit file feature to edit a file
directly in the browser.
I wonder why that didn’t work because as you recall, we setup the
origin correctly. Let’s figure out why.
1 2 3
Wha… We already set this before. What happened? Well, I can tell you that it is because I re-ran the
rake setup_github_pages a 2nd and 3rd time. If you recall from the setup_github_pages take, it doesn’t care if you have
an existing deployment directory or not – it blows out and creates it again!
So, just go add the origin again. facepalm
1 2 3 4 5 6 7
Before we continue, let’s take a quick look at that second error. Scrolling down to
line 18 in the same ruby
task above we see a
git push origin master being executed.
Because we had no
origin set correctly, this would cause yet another error. We got that fixed already though with
git remote set-url --add command.
Let’s try to deploy again now that we fixed the
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49
Humm, a few warnings about no tracking information for the remote branch, which we renamed to be
if you recall from earlier. I think this is normal because we haven’t pushed
source up yet.
git push origin source
Now, let’s see if we can fix the tracking information for our
source branch by pushing our changes up.
1 2 3
Seems like we are good here.
Let’s head over to our GitHub Page and see what’s there in the repo. What’s this? My master is a nice and clean static site? Sweet!
And lookie here, the
source branch has the source!
I’m sticking a fork in her and calling it… These may be normal warnings with the way the remote tracking is handled as I don’t have a lot of experience with that part of git.
It’s all downhill from here
If you have stuck with me this long, I have some good news – you’re done! Time to start blogging!
You can read the rest of the deployment guide from here as they have some useful tips. Also, make sure to commit your work (they mention this too).
My last piece of advice after you get the hang of things and create a few test posts is to look into these commands.
1 2 3
You’ve already run
rake generate; but, take a look at the other two.
rake watch is nice to auto-generate files as you change them.
rake preview is even better! It will watch for and auto-generate your site; but, more so it runs a very lightweight
tiny webserver (much less tiny than IIS!) in the background where you can open a browser and hit refresh to your heart’s
I advise everyone to do that to keep the number of commits down because once you have a few 100 pages, that generate and deploy is going to take a long while. Might as well get into the habit early!
PS: I am thinking of renting a Macbook Pro because of the time lost with stuff like this under Windows. Argh…