Guide
What is a Git-based CMS?
A Git-based CMS stores your content as files in a Git repository and writes every change back as a commit. Your site builds from those files. There is no content database and no content API between the editor and the page.
Updated . Written by Andrew Chemerynskiy.
How the commit flow works
- The site keeps content in files. Markdown for pages and posts, YAML or JSON for structured data, images in a media folder. A static site generator or a framework reads them at build time.
- The CMS reads the same files through the Git host. It signs in to GitHub or GitLab as the editor or as an app, lists the collections it knows about, and renders a form, a visual editor or a chat over them.
- A save is a commit. The tool writes the changed file back with a commit message. Some tools commit straight to the main branch. Others open a branch and a pull request per draft, so a reviewer can look before it merges.
- The host rebuilds. Netlify, Vercel, Cloudflare Pages and GitHub Pages watch the repository. A new commit starts a build, and the change is live when the build finishes, usually in one to three minutes.
- History is the git log. Every change has an author, a time and a diff. Rolling back is a revert.
What that changes
- Nothing to host for the content. No database, no API server, no backups to schedule. The repository is the source of truth and the host already backs it up.
- Content and code move together. A redesign that renames a field ships in the same pull request as the content it changes. Branches work for content the way they work for code.
- Developers keep their editor. Anyone with a clone can edit the files directly. The CMS is a second door, not the only one.
- Publishing has a build step. A change is not live the second it is saved. For a marketing site that is fine. For a newsroom it is not.
- The repository is the limit. Thousands of entries and gigabytes of images make clones and builds slow. Git was made for code.
Git-based vs API-first headless CMS
| Git-based | API-first headless | |
|---|---|---|
| Where content lives | Files in your repository | The vendor's database |
| How the site reads it | At build time, from the files | Over an API, at build or request time |
| Who owns the data | You, in full, in plain files | You, through export tools and the API |
| History | The git log, every change, forever | Versioning per entry, retention per plan |
| Editors | Git account or a hosted sign-in, depending on the tool | Email invite, roles and workflows built in |
| Scale | Hundreds of entries, a few editors | Millions of entries, many editors, many apps |
| Price | Free to about $50 a month | Free tier, then hundreds a month by seats and usage |
| Examples | Decap CMS, TinaCMS, Keystatic, CMS Brew | Contentful, Sanity, Storyblok, Strapi |
About the term "Git-based headless CMS"
Both kinds are headless in the strict sense: the CMS has no front end and your site renders the content. People write "Git-based headless CMS" to say "headless, but the content is in my repo, not in your database". Some tools blur the line on purpose. TinaCMS and Keystatic add a typed content layer over the files so a React app can query them like an API. They are still Git-based: the files are the source of truth.
When to pick one
- The site already builds from files: Astro, Hugo, Eleventy, Jekyll, Next.js with Markdown, Nuxt Content, SvelteKit.
- A developer owns the repository and is happy to keep a config file or a schema.
- One to a handful of editors, and a few dozen to a few hundred entries.
- Content is pages, posts, a menu, a team list, a few product entries. Not a catalogue.
- You want history, rollback and no monthly bill for a database you do not need.
- Clients edit, and the tool you pick handles sign-in and guards for them. See the first entry in the ranking.
When not to
- Thousands of entries, or content that several apps read over an API.
- Many editors at once, with roles, approvals and scheduled publishing across a team.
- Changes that must be live in seconds, not after a build.
- Image-heavy sites with no plan for media outside the repository.
- Personalised or user-generated content. That is application data, not site content.
What to check before you choose
- Git host. GitHub is universal. GitLab, Bitbucket and Gitea are not. The FAQ has the table.
- Sign-in. Does the editor need a Git account, or does the tool invite by email? This decides whether a client can use it.
- Review flow. Straight to main, or a draft someone approves? Every profile lists this in its facts grid.
- Framework coupling. Some tools are framework-neutral. Others live inside Next.js, Nuxt or Jekyll.
- What the editor can touch. Markdown files only, or copy inside components too?
- Price and who pays it. Per site, per user, one-time, or free. The table on the ranking lists all 16.
Where to go next
- The ranking: all 16 tools, ordered, with one verdict and one catch each.
- The profiles: one page per tool with pros, cons, prices and alternatives.
- The FAQ: the Netlify CMS rename, the Static CMS status, build hooks, cost.
- Decap CMS if you edit Markdown alone. CMS Brew if clients edit.
