Git Workflow

Mini CMS stores all content as files. This means git is your versioning system, your backup, and your undo button. It also means a careless git reset --hard or git checkout . can destroy every edit the site owner has made. Handle with care.

What is tracked in git

A Mini CMS project has two kinds of files that both belong in the repo:

Both should be committed. Content files are the site’s data — they are the equivalent of a database, except they live in the repo.

Rules for coding agents

1. Never discard content changes

Before any destructive git operation, check if _content/ has uncommitted changes:

git status _content/

If it does, commit those changes first. Content edits come from the site admin using the inline editor — they are user data, not code artifacts.

2. Commit content and code separately

Keep content commits separate from code changes when possible:

# Commit content that the admin has edited
git add _content/
git commit -m "Content update: home page and about page"

# Then commit your code changes
git add _views/ _static/ src/
git commit -m "Add new feature card partial"

This makes history readable and reverts safe — you can roll back a code change without losing content.

3. Never use these commands without thinking

# DANGEROUS — destroys all uncommitted content edits
git checkout .
git reset --hard
git clean -fd

# SAFER alternatives
git stash                    # saves everything, recoverable
git diff _content/           # inspect before deciding
git checkout -- _views/      # discard only code changes

4. Pull before pushing

If the site admin has been editing content while you work on code, their changes may be on the server but not in your working tree. Always pull and handle merges carefully:

git pull --rebase

Content files rarely conflict (different pages edit different files), but if they do, the admin’s version is almost always correct.

5. Use branches for structural changes

When changing view templates or route structure, work on a branch. If the changes affect which widgets exist or how content is organized, the branch can carry the migrated content files alongside the code changes:

git checkout -b feature/new-layout
# Edit views, move content files, test
git add .
git commit -m "Restructure home page layout"
git checkout main
git merge feature/new-layout

Uploads

The uploads/ directory contains media files managed by the CMS media library. Whether to track these in git depends on the project:

• Small sites: commit uploads. Simple, complete backups, works for deployment.
• Large sites: add uploads/ to .gitignore and handle media separately (rsync, object storage, etc.).

The key insight

In a traditional CMS, the database is a black box that git never sees. In Mini CMS, the database is the filesystem, and git sees everything. This is a feature: free versioning, free backups, free diff. But it means you must treat _content/ with the same respect you would give a production database.