Git & Commit Message Reference Guide

This document contains detailed examples and rationales for the ai-superpower Git commit message standards.

The Core Philosophy

Commit messages describe topics and goals, not filenames and line edits. The Git UI already perfectly documents which files changed and what code was added or removed. The commit message's job is to explain why the change was made and what the high-level business or architectural intention was.

Formatting Rules Deep Dive

Subject line: Max ~72 characters, imperative mood ("Fix", "Add", "Remove" — not "Fixed", "Added").
Body: Optional. Use only when the intent or why is not obvious from the diff.
Never list filenames. Do not use "CHANGES:" headers or file-by-file breakdowns.
Translate technical changes into a high-level topic summarization.
No speculative outcomes. No "Expected:", "Result:", or "Impact:" sections.
Do not describe runtime behavior, incident narrative, or manual operations in the commit message body.
Do not summarize or quote the exact content of text/description changes. The diff shows the content; the message states the topic of the change.

✅ / ❌ Commit Message Patterns

High-level Topics vs. Technical Steps

❌ docs/ai-context.md: add homelab k3s target, domain pattern (Mentions filenames, reads like a technical log)
✅ document development environment and deployment context (Abstracts to the goal)

Bullet Points State Topics, Not Implementation

❌ use MC_HOST_minio env var for direct S3 auth (no mc alias set) (Describes the exact code change)
✅ configure direct S3 authentication for MinIO (Describes the architectural goal)

No Runtime/Status Narratives

❌ gitea failed on startup (Describes an incident, not the repo state change)
❌ Redis services cleaned up manually (Describes a manual ops task)
✅ disable external redis dependency (Describes what the commit actually does to the code)

No Quoting the Text Changes

❌ Remove "harmless" framing, add operational guidance: daily return to 0 expected (Quotes the diff directly)
✅ update operational expectations for Ghost Blocks panel (States the topic of the documentation update)

Body Length and Verbosity Example

❌ Too detailed — describes files, code references, and technical mechanics:

chore(minio): pin image to RELEASE.2025-10-15T17-29-55Z

Chart 5.4.0 bundles RELEASE.2024-12-18 which does not return Last-Modified
metadata on objects. Thanos compactor falls back to ULID creation time and
deletes valid blocks as stale partial uploads (>48h old).

Also add comment on thanos-sidecar image noting all Thanos containers
(compactor, blocks-exporter, init container, ghost cleanup job) share
this single image reference.

✅ Correct — states the high-level intent and reasoning clearly without itemizing files or specific code additions:

chore(minio): downgrade minio version to fix object metadata loss

The newer chart release causes valid block deletion by the compactor due
to missing Last-Modified metadata on objects. Version is pinned to an
older stable release to prevent data loss.

Also clarified shared image dependencies for Thanos services in documentation.

3.3 KiB Raw Blame History