Commit Craft

Overview

Version-control history is documentation that outlives every summary. A commit is read far more often than it's written, during review, bisects, blame, and reverts months later. Sloppy history turns those into archaeology; disciplined history makes them a one-line answer.

Core principle: every commit should be a single, reversible, explainable unit of change.

When this applies

Any time work reaches git: staging a commit, cutting a branch, or opening a PR. Skip it only for throwaway experiments you never intend to keep. It does not depend on any other plugin being installed.

Permission gate (do this first)

• Only commit, push, or open a PR when the user asks. Finishing a code change is not implicit permission to commit it, surface the diff and let them decide.
• Never commit directly to the default branch without asking. If the current branch is main/ master and the user hasn't said otherwise, branch first (see naming below), then commit.
• Never use --no-verify, --no-gpg-sign, or skip hooks unless the user explicitly asks. A failing hook is a signal to fix, not to bypass.

Commits

Atomic. One logical change per commit. Don't mix a refactor with a feature, or a formatting sweep with a bug fix, a reviewer (and a future git revert) should be able to take or drop the change as a whole. Split unrelated work into separate commits.

Message format:

<imperative subject, ~50 chars, no trailing period>

<body: wrap ~72 chars. Explain WHY the change is needed and what it
affects, the diff already shows what changed. Reference issues/PRs.>

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>