commit-craft

1# Commit Craft
2 
3## Overview
4 
5Version-control history is documentation that outlives every summary. A commit is read far more
6often than it's written — during review, bisects, blame, and reverts months later. Sloppy history
7turns those into archaeology; disciplined history makes them a one-line answer.
8 
9**Core principle:** every commit should be a single, reversible, explainable unit of change.
10 
11## When this applies
12 
13Any time work reaches git: staging a commit, cutting a branch, or opening a PR. Skip it only for
14throwaway experiments you never intend to keep. It does not depend on any other plugin being
15installed.
16 
17## Permission gate (do this first)
18 
19- **Only commit, push, or open a PR when the user asks.** Finishing a code change is not implicit
20  permission to commit it — surface the diff and let them decide.
21- **Never commit directly to the default branch without asking.** If the current branch is `main`/
22  `master` and the user hasn't said otherwise, branch first (see naming below), then commit.
23- **Never use `--no-verify`, `--no-gpg-sign`, or skip hooks** unless the user explicitly asks. A
24  failing hook is a signal to fix, not to bypass.
25 
26## Commits
27 
28**Atomic.** One logical change per commit. Don't mix a refactor with a feature, or a formatting
29sweep with a bug fix — a reviewer (and a future `git revert`) should be able to take or drop the
30change as a whole. Split unrelated work into separate commits.
31 
32**Message format:**
33 
34```
35…