Updating a theme when a new update arrives

Using Ghost
1

Hi everyone,

I’m using a Ghost theme and have made quite a few custom changes to it over time.

A new version of the theme has now been released, and I’d like to update to it so I can benefit from the new features and fixes — but I don’t want to lose my existing customizations.

For example, I’ve changed the newsletter signup to use Ghost Portal, and I’ve changed the “Become a member” buttons to link to my /membership/ page. I’ve made several other small code changes as well.

My main problem is that manually checking and re-applying all these changes every time the theme is updated is time-consuming, and I’m worried I’ll eventually forget something. I do have notes documenting my changes, but I’d really like a more reliable way of managing this.

Ideally, I’d like a simple process where I can:

  • Keep my customized version of the theme.
  • Download the new official version when it’s released.
  • Compare the two versions and see exactly what has changed, including changes within existing files.
  • Apply the new updates while keeping my own customizations.
  • Repeat this entire process easily whenever a new version is released.

I’m not a developer, so I’m looking for something easy, and straightforward.

What would be the best approach for someone with limited coding/IT experience? Is there a recommended free tool or workflow for keeping a customized Ghost theme up to date without losing custom changes?

Thanks in advance!

3 Likes
2

I think the “normal” dev way of doing this is to use Git.

  • fork the the Ghost Theme git repo on github
  • “git clone” your fork locally
  • add the upstream (fork source) "git remote add upstream $github-fork-source-url
  • Add your changes - do one commit per change.
  • fetch upstream changes: git fetch upstream
  • rebase on the upstream changes: git rebase upstream/main

Maybe there is also some (Web)GUI for this somewhere. Probably you will have some issues on rebase if your changes conflict with upstream changes.

Probably AI chat can guid you through all the issues that arise.

3

Hi, this is a really common situation and the good news is there’s a solid, free workflow for it. It comes in two halves: first shrink the number of places where you’ve touched the theme, then manage what’s left with Git. Neither requires you to be a developer.

Part 1: move as many customizations as possible out of the theme files

Every change you make inside the theme is a change you’ll have to carry forward with each update. So before anything else, check which of your tweaks can live somewhere that survives a theme update untouched:

The newsletter signup you switched to Portal: most modern themes already support Portal natively, and a new theme version may well have made your patch unnecessary. Check the new version’s changelog for that first.

The “Become a member” links pointing to /membership/: if the theme exposes that as a setting (Ghost Admin > Design > Site-wide or theme settings), use it. If not, a small snippet in Code Injection (Settings > Code injection > Site footer) can rewrite those links with a few lines of JavaScript, and Code Injection survives every theme update. Same goes for CSS changes: put them in Site header inside a <style> block instead of editing the theme’s CSS.

After this pass you’ll usually find that only two or three real code changes remain. That’s a very different problem from “several small changes I might forget”.

Part 2: keep the rest under version control with GitHub Desktop

Git sounds intimidating but for this exact use case it’s a three-step routine, and GitHub Desktop (free) hides all the command-line stuff. The trick is to keep two branches: one that only ever contains the official theme as released, and one with your version on top of it. Set it up once:

  1. Create a folder, put the original version of the theme in it (the one you started from, before your edits), open it in GitHub Desktop and commit it. Call this branch upstream.
  2. Create a new branch from it called mine, paste your customized theme files over it, and commit. Git now knows exactly what you changed, file by file, line by line, and the diff view shows it to you. That’s your “notes” from now on, and it can never be incomplete because Git generated it.

Then, each time a new version comes out:

  1. Switch to upstream, paste the new official version over the folder, commit. The diff now shows you exactly what changed in the theme, inside every file.
  2. Switch to mine and choose “Merge upstream into mine”. Git carries the theme’s changes over and re-applies your customizations automatically.
  3. If Git and the theme author edited the same lines, GitHub Desktop flags a conflict and shows both versions side by side; you pick which one to keep. With two or three customizations this happens rarely and is a two-minute job.
  4. Zip the theme folder, upload it in Ghost Admin, done. Next release, repeat.

If you’d like a visual side-by-side comparison beyond what GitHub Desktop shows, Meld (Windows/Linux) and Kaleidoscope or Beyond Compare (Mac, paid) are good, but honestly the built-in diff is enough for this.

One extra tip: keep a short CUSTOMIZATIONS.md file inside your theme folder listing what you changed and why. It travels with the theme, it shows up in the Git diff, and future-you will thank present-you.

Hope that helps; happy to clarify any step if you get stuck.

3 Likes
4

This sounds like an excellent methodology @rlemon, thanks for laying it out. If I’m not mistaken I asked the same question several years ago here on the forum but nobody seemed to have a solution. But now we’ve got one. Thanks!

1 Like
5

What is the possibility of Ghost child themes?

6

Not on the table right now. Ghost has no theme inheritance the way WordPress has: a theme is one self-contained folder, and there’s no way to say “use theme X but override these files”. It’s been asked before, for example here: Is the child theme concept on the roadmap? (2020, never got an answer). Going back to 2018 the Ghost team’s own reply was: use Git. That’s still where things stand.

What Ghost gives you in place of child themes:

Custom settings in package.json, so a theme author can expose colours, layouts and toggles that users change in Admin instead of in code. Code Injection for CSS and small JS, which survives every update. And custom templates (custom-something.hbs) for per-page layouts.

So as a theme developer the trick is to build as much as you can into settings, so most people never need to touch the files. Anything beyond that, the Git workflow above is still the way.

7

Thanks for answering. That explains things well.

I have found that once I became used to code injection, I found it can do almost everything I might ever want to do with a child theme.