Upgrading

A new version brings fixes and features, but by then you have changed the theme: your settings, content, words and maybe components. The safest way to upgrade is to let git combine the two.

Recommended: a theme branch

Set this up once, ideally before you start customising.

1. Commit the untouched theme on its own branch:

   git checkout -b theme
   # copy in the theme files exactly as downloaded, then
   git add -A && git commit -m "SwiftAgency 1.2.0"
   git checkout -b main

2. Build your site on main as usual.

3. When a new version comes out, update the theme branch with the new files and commit:

   git checkout theme
   # replace the files with the new version (keep the .git folder)
   git add -A && git commit -m "SwiftAgency 1.3.0"

4. Merge it into your site and resolve the conflicts:

   git checkout main
   git merge theme

   Conflicts only appear where both you and the theme changed the same lines. Everything else merges by itself.

5. Follow the version’s upgrade steps in the changelog, run npm install and npm run verify, and check the site in the browser.

Without git history

Compare the new version with yours file by file, starting with the files listed under “Changed” in the changelog. A diff tool such as git diff --no-index old-theme/ new-theme/ shows exactly what the theme changed, which you can then apply to your copy.

What usually conflicts

File	Why	Tip
src/config/site.ts	You set your details, the theme added a setting	Keep your values, add the new keys
src/i18n/ui/*.ts	You changed words, the theme added keys	Keep your words; npm run check lists new keys you still need
src/content/**	You replaced the demo content	Keep yours. Demo content changes can be ignored
package-lock.json	Dependencies changed on both sides	Take the theme’s version, then run npm install

Tip

Keep your own components in their own files instead of editing the theme’s where you can. A new file never conflicts.

Version history

Each release in the changelog lists what was added and changed, and ends with Upgrading from… steps when a release needs you to do something. Upgrade one version at a time if you are several behind.