Upgrade Guide

Table of Contents

• Upgrading from Starter
  • Preparation
    • Adding Upstream
    • Handling Submodule
  • Fetch Updates
• Upgrade the Fork
• Major Version Upgrades

Upgrading from Starter

If your website was created using chirpy-starter, follow these steps to update your repository.

Preparation

The operations mentioned in this section only need to be performed once after cloning your repository locally.

Adding Upstream

git remote add chirpy https://github.com/cotes2020/chirpy-starter.git

Verify the remote was added successfully:

git remote -v

The output should include:

chirpy  https://github.com/cotes2020/chirpy-starter.git (fetch)
chirpy  https://github.com/cotes2020/chirpy-starter.git (push)

Handling Submodule

If your workflow does not require the submodule assets/lib, run command:

git config submodule.assets/lib.ignore all

This prevents the submodule from pulling files and taking up local disk space.

Fetch Updates

The following steps need to be performed for each update.

1. Fetch all tags from upstream:

   git fetch chirpy --tags

2. Merge the latest tag from upstream into your local branch. For example, to merge tag vX.Y.Z, run:

   git merge vX.Y.Z --squash --allow-unrelated-histories

3. If the list of conflicting files includes the submodule assets/lib:

   • If you do not want to use the submodule, execute:

     git restore --staged assets/lib

   • If you have already initialized and enabled the submodule, follow the output hint:

     hint:  - go to submodule (assets/lib), and either merge commit <submodule_commit_hash>
     

     Record the submodule_commit_hash and update the local submodule:

     git -C assets/lib merge <submodule_commit_hash>

4. Resolve any remaining file conflicts manually. Keep any custom modifications if needed.

5. Once conflicts are resolved, create a new commit to save the upgrade:

   git add . && git commit -m "chore: upgrade to X.Y.Z"

6. Update the local theme gems:

   bundle update

Upgrade the Fork

If you forked from the source project (there will be gemspec in the Gemfile of your site), merge the latest upstream tags into your Jekyll site to complete the upgrade. The merge may conflict with your local modifications. Be patient and careful when resolving these conflicts.

JS distribution files have been removed since v5.6.0, and Bootstrap CSS has been lean since v7.0.0. For future upgrades, compile the CSS/JS files yourself:

npm run build

Then add them to your repository files:

git add assets/js/dist _sass/vendors -f

Major Version Upgrades

When upgrading to a Major version, read the release notes for that version to understand any changes in project configuration.