Key Takeaways
- A dedicated vendor branch is the single most important step you can take before touching a downloaded template.
- Keeping your customisations on a separate branch means every future update becomes a controlled
git mergeorgit rebase, not a manual file comparison. - CSS variable overrides and Sass partials that sit outside the vendor tree dramatically reduce merge conflicts.
- A repeatable upgrade checklist turns a potentially risky process into a routine task you can run in under two hours.
- The same strategy works whether you are maintaining one site or theming a single template for multiple clients.
Why Updates Break Customised Templates
Download version 7.0 of a template, unzip it, start editing files directly, and you create an invisible problem. Every change you make is mixed with the vendor’s original code inside the same working tree. Six months later, version 7.2 ships with a fix for a JavaScript plugin conflict. Without version control, you now have three options: overwrite your changes, diff hundreds of files by hand, or skip the update and accumulate security and compatibility debt.
The root cause is that most developers treat an HTML template like a finished product rather than an third-party dependency. Shift that mental model and the Git strategy becomes obvious: isolate the dependency, apply your work on top of it, and merge the dependency forward whenever the vendor ships a new version.
The Two-Branch Model for Vendor Code
The minimum viable structure uses two long-lived branches.
vendor/main: contains only the unmodified template files exactly as downloaded. No custom CSS, no client copy, no swapped images.main(ordevelop): branched fromvendor/mainat the point of first download, and contains every customisation you have ever made.
Initialise the repository before you open a single file in your editor:
git init my-project
cd my-project
cp -r ~/Downloads/canvas-7.0/* .
git add .
git commit -m "chore: add Canvas 7.0 vendor source"
git branch vendor/main
Your working branch
git checkout -b main
From this point, vendor/main is a pristine snapshot. You never commit your own work there. When the Canvas HTML Template ships version 7.1, you update vendor/main first, then merge or rebase main on top of it.
Structuring Customisations to Minimise Conflicts
A good branch model still produces painful conflicts if your custom code is scattered through vendor files. Own as few vendor-originated files as possible.
CSS and Sass overrides belong in a file you create, not in the vendor stylesheet. Canvas exposes its design tokens through CSS custom properties such as --cnvs-themecolor. Override them in a separate file loaded after the vendor bundle:
<!-- vendor bundle (never edit) -->
<link rel="stylesheet" href="css/style.css">
<!-- your overrides (fully owned by you) -->
<link rel="stylesheet" href="css/custom.css">
/ custom.css /
:root {
--cnvs-themecolor: #2563eb;
--cnvs-themecolor-rgb: 37, 99, 235;
}
.section-padding-custom {
padding-block: 5rem;
}
For Sass-based workflows, keep overrides in a _custom-variables.scss partial imported before the vendor entry point. The post on modernising your Bootstrap 5 Sass workflow with @use vs @import explains how to structure that import chain without touching vendor partials. If you are also running a Vite build, the guide on setting up Vite for a Bootstrap 5 HTML template shows how to point the entry file at your custom partial rather than the vendor one.
HTML pages are the trickiest files to manage because you will inevitably edit them heavily. Accept this and document which sections come from a vendor demo file. A comment at the top of each page helps during a merge:
<!-- Base: canvas/demos/landing.html @ v7.0
Custom sections: hero (lines 42-89), pricing (lines 201-260) -->
Applying a Vendor Update Step by Step
When a new template version is released, follow this sequence every time, without shortcuts.
- Download and extract the new release into a temporary directory. Do not extract over your project folder.
- Switch to
vendor/mainand copy in only the changed vendor files. The release notes for most templates list which files changed; use them. - Commit the vendor update with a message that includes the version number:
chore: update Canvas vendor source to 7.1. - Switch to
mainand merge the vendor branch:git merge vendor/main --no-ff. The--no-ffflag preserves the merge commit so the history stays readable. - Resolve conflicts file by file. Because your overrides live in files the vendor does not own, most conflicts will be in HTML pages. Resolve them with
git mergetoolor a visual diff tool such as VS Code’s built-in three-way merge editor. - Run your test suite and check the browser before committing the merge.
git checkout vendor/main
copy new vendor files in, then:
git add .
git commit -m "chore: update Canvas vendor source to 7.1"
git checkout main
git merge vendor/main --no-ff -m "chore: merge Canvas 7.1 into project"
resolve any conflicts, then:
git add .
git commit
Tagging Stable States Before Every Upgrade
Before you begin a merge, tag the current state of main. If the merge produces an unexpected regression, you can return to a known-good state immediately without hunting through the log.
git tag -a v7.0-stable -m "Stable build before Canvas 7.1 merge"
git push origin v7.0-stable
Store tags on the remote so any team member can check out the pre-upgrade state. This matters most in agency workflows where one template is used across several client projects. The post on theming one HTML template for multiple client brands with CSS variables covers how to extend this pattern when each client has its own branch forked from your shared main.
What to Do When Bootstrap Itself Updates
Template vendors do not always update on the same schedule as Bootstrap core. Canvas ships its own tested and pinned version of Bootstrap 5. Upgrading Bootstrap independently inside a vendor template means taking on compatibility risk the vendor has not validated.
The safe approach is to treat Bootstrap as part of the vendor bundle. If you need a specific Bootstrap fix before the template vendor ships it, create a third branch: vendor/bootstrap-patch. Apply the upstream Bootstrap fix there, cherry-pick only the relevant commit into main, and document it clearly. When the template vendor eventually ships their own tested update, you can drop the cherry-pick during the next merge.
Do not patch Bootstrap’s compiled CSS directly. Override the relevant rule in your custom.css file instead, so the patch survives any future vendor update cleanly.
Frequently Asked Questions
Yes. Even a single site will eventually need a vendor update, a security patch, or a Bootstrap compatibility fix. Without the vendor branch, each of those events requires manual diffing. The setup takes less than five minutes and only needs to be done once per project.
You can, and some teams prefer a linear history. The trade-off is that rebasing rewrites commit hashes, which can cause confusion on shared remotes. For projects with multiple contributors, a merge commit is clearer because it marks the exact point the vendor update was integrated. Use rebase only if you are the sole developer and understand the implications of force-pushing.
A major restructure, for example a move from a flat CSS folder to a Sass build system, is best handled as a fresh vendor/main commit that replaces all files rather than patches them. Commit the new structure as a single large commit, then merge into main. Git will show every file as conflicted, but the conflicts will be straightforward because you know exactly which files you own. Use git checkout --ours <file> for files you control entirely, and resolve manually for shared files.
For HTML templates, yes. Unlike npm packages, template vendor bundles such as Canvas’s plugins.min.js are not available from a registry, so they must be committed. This is a deliberate difference from a Node.js project where you would add node_modules to .gitignore. Commit the vendor bundle as part of the vendor/main branch and update it only when a new template version is released.
Create a parallel asset directory you own outright, for example images/custom/ alongside the vendor’s images/ folder. Reference your assets from that directory in your HTML. The vendor’s image directory can then be updated cleanly without touching your replacements. Large binary files benefit from Git LFS if repository size becomes a concern.
Looking for a production-ready Bootstrap 5 HTML template? Browse Canvas Template demos and find the perfect starting point for your next project.
If you’re building with the Canvas HTML Template and want to ship production-ready Bootstrap 5 layouts faster, try Canvas Builder free — the visual builder that exports clean Canvas-ready markup in minutes.
Skip the setup and build it free
Spin up a complete Bootstrap 5 site, blog included, with Canvas Builder. No coding, no cost.
Canvas Team
Tutorials and tips for building beautiful Bootstrap 5 websites with the Canvas HTML Template and Canvas Builder.
More from the Canvas Blog