How to Version Control a Ghost Theme with Git

The Ghost blogging platform has come a long way since its inception, but the development team is still cranking out major updates roughly every other month. I've been struggling to find a development workflow that allows me to customize Ghost without worrying about breaking it when I update to the latest version. I also wanted an environment that allows me to develop and test locally before pushing to a production environment.

Because Ghost is run as a service and not static pages, version control becomes a bit challenging. Using git makes the most sense, but the trick is versioning the right files. You are most likely concerned with only tracking changes of the website design. Otherwise, if you are actually modifying the core Ghost files, you probably don't need advice from some random blog :)

I also had difficulty deciding on theme for my blog. Although I liked a few, it seemed that every theme had a feature or two missing that I really wanted to. So, I decided that I would need to choose one and start editing it.

With that in mind, there are a few rules for how we are going to version control our Ghost blog:

  • We will be using Git and the repo will be on GitHub
  • Git will only track theme changes (the items in \content\themes folder)

And here is the method I settled on:

  • Fork an existing theme on GitHub
  • Setup a local development environment of Ghost by cloning forked theme from above
  • Make changes locally and them push back to GitHub
  • Clone custom theme in production environment

Development

This is your local machine running your operating system of choice. I"m on Windows, so if you are running Mac/Linux, your commands may be slightly different, but the idea is the same. First, download the latest version of Ghost. The easiest way to do this is to download the .zip from Ghost. Alternatively, you can get Ghost using Git by the following the instructions here. After you have downloaded the zip file, extract the contents. In Windows Explorer, navigate to the base directory of "Ghost\" (it should have folders "content", "core", etc) and hold shift and right-click and click "Open command window here". Now type:

npm install --production

This will install all the node.js dependencies required to run Ghost. And because Ghost is a service, we must run it using this command:

npm start

Now open a web browser and go to: http://localhost:2368. You should see ghost up and running.

Keep the command window open since it shows whether Ghost is running and displays live logging.

Custom Theme

The next step is to start customizing a theme. While you could create one from scratch, it is much easier to edit an existing theme. The default Ghost install comes with the Casper theme, which isn't a bad start, but just know there are countless other themes to choose from as well. Once you have decided on a theme, go to the GitHub of theme (assuming it has one) and "fork" it, which will create a copy ready for tracking in your account. If you don't have a GitHub account, now would be the time to fix that. Here is the link for the Casper theme. In my case, I forked the Vapor theme

Now, still on your development machine, navigate to Ghost\content\themes and open up a command window. You need to clone (copy) your custom theme that you just forked with the following command (enter your unique address from GitHub):

git clone https://github.com/7200rpm/VaporCustom.git

Now you have the theme on your development machine and can freely make edits. Note that you need to restart Ghost anytime you add themes. So just Ctrl-C to kill Ghost and npm start again to start it back up. I find that Notepad++ is the easiest method to edit files. Once you are satisfied with how the site looks, it's time to push these changes back to GitHub.

git add .
git commit -m "initial commit"
git push

Production

Now it's time to setup the production environment. There are numerous ways to setup a production system, so I'll only cover my particular setup. I use a VPS through DigitalOcean. They have a 1-click install for Ghost, which means you can have a complete Ghost setup in under 5 minutes. If you decide to go somewhere else to setup a VM, you will need to setup Ghost similar to the development process described above.

Once you have Ghost setup, you need to clone your custom theme to your production system. So, SSH into your VPS using something like PuTTY and navigate to the themes directory root@Ghost:/var/www/ghost/content/themes/VaporCustom# and type in the command:

git clone https://github.com/7200rpm/VaporCustom.git

Restart Ghost and your custom theme should now be available on your production system.

The Workflow

Now, further development works like this:

  • Edit theme files on local Ghost environment
  • Push theme changes to GitHub

    git add .
    git commit -m "initial commit"
    git push
    
  • On production server, pull changes (clone will copy entire theme; pull will only get changes)

    git pull
    

Now, by using git only on the theme, your design is separated from the ghost architecture.

Another note is that your content is also separate from your design. So, any updates to the theme will not affect your blog posts, thankfully.

Brandon Brown

Read more posts by this author.