git-workflow-and-versioning

Use the format type: short description, where type is feat, fix, refactor, test, docs, or chore. Add a body explaining why the change was made, not what changed, since the diff already shows the what.

Trunk-based development keeps main always deployable with short-lived feature branches merged within 1-3 days. Long-lived branches accumulate merge risk and conflicts, and DORA research links trunk-based workflows to high-performing engineering teams.

Use git worktree add to create separate directories, each checked out to its own branch. Agents work in isolation without branch switching, and failed experiments are removed with git worktree remove.

Target around 100 lines per commit or PR. Changes near 300 lines are acceptable for a single logical change, but anything approaching 1000 lines should be split into smaller, separately reviewable commits.

Commit generated files only when the project expects them, such as package-lock.json or Prisma migrations. Never commit build output, .env files, or node_modules, and maintain a .gitignore covering these exclusions.

Use git bisect start, mark the current commit bad and a known-good commit good, then test each midpoint checkout until git narrows down the offending commit. git log --grep and git blame also help trace changes.