--- name: git-commit description: Use after completing a task when all verifications pass, to commit the work, or when cutting a GitHub release. Covers the verification gate, splitting into logical commits, staging, the house commit-message format (no Co-Authored-By trailers), and release tagging. --- # Skill: git-commit ## When to Use You have completed a task, all verifications have passed, and you need to commit the changes. ## Steps 1. **Run final verification. All checks must pass.** Use the project's own gate: type-check (if the language has one), tests, lint, and format. Read the project manifest / task runner for the exact commands (e.g. `package.json` scripts, `Makefile`, `justfile`, `cargo`, `go`, `mix`, `pytest`). Example (bun + TypeScript): ```bash bun run type-check bun test bun run lint bun run fmt ``` If any fails, stop and fix the issue before committing. 2. **Check what will be staged:** ```bash git status git diff --stat ``` 3. **Split into logical commits.** Before staging, scan the diff and group changes by intent. **Do not put unrelated changes into one commit.** A commit should answer a single "why." Common splits: - Bug fix vs version bump -> two commits - Source code change vs test additions for an unrelated module -> two commits - Refactor vs new feature -> two commits - Code change vs docs/CHANGELOG update for that same code -> can be one commit - Code change vs unrelated formatting noise -> two commits (or revert the noise) If the working tree has multiple intents, commit them in sequence: ```bash # Commit 1: the fix git add src/auth/session.ts tests/auth/session.test.ts git commit -m "fix(auth): handle expired refresh token gracefully" # Commit 2: the version bump (separate intent) git add package.json jsr.json git commit -m "chore: bump version to 5.4.2" ``` When uncertain whether two changes belong together, the test is: "Could someone want to revert one without the other?" If yes, split. 4. **Stage the relevant files for the current commit.** Be explicit. Do not use `git add -A` blindly: ```bash git add apps/api/src/modules/projects/ git add apps/api/src/db/migrations/0003_add_project_archive.sql # etc. ``` **Never stage:** - `.env` files - `*.pem` key files - Lockfile changes for unrelated packages (e.g. `bun.lock`, `package-lock.json`, `Cargo.lock`, `go.sum`, `poetry.lock`) - Build output (e.g. `dist/`, `.next/`, `target/`, `build/`, `__pycache__/`) 5. **Compose the commit message.** First check the project's own convention: `CONTRIBUTING.md`, a `commitlint.config.*` file, a commit-msg hook, and the style of `git log --oneline -20`. The project's convention wins. Where it says nothing, use Conventional Commits: Format: `(): ` | Type | Use when | | ---------- | ----------------------------------------- | | `feat` | New feature or behavior | | `fix` | Bug fix | | `refactor` | Code change with no behavior change | | `test` | Adding or fixing tests | | `docs` | Documentation changes only | | `chore` | Build config, tooling, dependency updates | | `perf` | Performance improvement | Scope: the module or layer changed (e.g., `auth`, `tasks`, `gantt`, `db`, `ci`) Subject rules: - Imperative mood: "add", "fix", "refactor", not "added" or "fixing" - **Max 80 characters for the entire first line** (`type(scope): subject [ID]` combined). A commit-msg hook (e.g. husky/commitlint) often enforces this for the subject line. - No period at end - Reference task ID when applicable: `[BE-S2-02]` - **Never write `@` or `@` anywhere in the message.** GitHub renders `@something` as a user mention and notifies whoever owns that handle. For version pins, write `v4` / `v5`, `major 4`, or wrap in backticks (`` `@4` ``). The same rule applies to commit bodies, PR titles, PR bodies, issue comments, and release notes. Body rules (for multi-line commits): - **Every line in the body is also capped at 80 characters.** Hard-wrap long sentences manually. - One blank line between subject and body. - One blank line between paragraphs in the body. **Before committing, write the message to a file and check every line:** ```bash awk 'length > 80 { print "TOO LONG (" length "): " $0 }' /tmp/commit-msg.txt git commit -F /tmp/commit-msg.txt ``` No output from `awk` means every line fits. For quick subject-only checks: ```bash echo -n "chore(auth): remove readme artifact and fix ErrorBoundary [FE-AUTH-06]" | wc -c # must be 80 or fewer ``` 6. **Create the commit:** ```bash git commit -m "feat(projects): add project creation endpoint [BE-S2-02]" ``` For multi-line commits (when the "why" is non-obvious): ```bash git commit -m "feat(tasks): enforce finish-to-start dependency [BE-S3-03] Task B's checkbox is disabled when its prerequisite (Task A) is not yet in completed status. Auto-unlock triggers after Task A completes, changing Task B from locked to ready." ``` **Do NOT add `Co-Authored-By` trailers.** Commits are authored solely by the developer. No AI attribution lines. 7. **Repeat for the next logical commit** if the working tree still has unstaged changes from a different intent. Return to step 3. 8. **Verify the commits:** ```bash git log --oneline -5 ``` 9. **Report to the user:** commit hashes and messages for every commit you made. ## Creating a GitHub Release When the commit is a release (`chore: release vX.Y.Z`) and the version bump has landed on the default branch, cut the release. 1. **Create the tag and release.** For most repos, the one-liner is fine: it creates the tag at the branch tip: ```bash gh release create vX.Y.Z --target main --title "vX.Y.Z" --notes-file notes.md ``` **Only if the project requires *signed* tags** (OpenSSF Best Practices Gold `version_tags_signed`, or an org supply-chain policy): `gh release create --target` makes an *unsigned* server-side tag, and `tag.gpgSign=true` does NOT help, because gh creates the tag server-side, bypassing local git signing. You must tag locally (which signs per config), push it, then create the release from the existing tag (no `--target`): ```bash git tag -s vX.Y.Z -m "vX.Y.Z" # signed (gpg or ssh-format key) git push origin vX.Y.Z gh release create vX.Y.Z --title "vX.Y.Z" --notes-file notes.md # no --target git verify-tag vX.Y.Z ``` 2. **The title is the version and nothing else:** `vX.Y.Z`. No tagline, no emoji, no "Release", no emoji, no summary. The body carries the detail. 3. **The body is written by the `release-notes` skill.** Invoke it rather than pasting the CHANGELOG section in: the changelog is the complete record for existing users, the notes are for someone deciding whether to adopt. State facts only: no marketing, no filler ("we're excited to", "huge improvements"), no slop. The `@`/`@` rule applies there too: never in release notes (use `v4` or backticks). 4. **Verify after publish:** the publish workflow run is green and the registry shows the new version (`npm view version`, JSR `meta.json`); signed release artifacts are attached if the project signs them. ## Checklist Before Done - [ ] Type-check passed (if the language has one) - [ ] Tests passed - [ ] Lint passed - [ ] Format passed - [ ] No `.env` files staged - [ ] No `*.pem` key files staged - [ ] Unrelated changes split into separate commits (one intent per commit) - [ ] Commit message follows Conventional Commits format - [ ] Scope matches the affected module - [ ] Subject uses imperative mood - [ ] Subject line is 80 characters or fewer (verified with `echo -n "..." | wc -c`) - [ ] Every body line is 80 characters or fewer - [ ] No `@` or `@` anywhere in subject or body (use `v5` or backticks for version pins) - [ ] Task ID referenced in subject when applicable ## Examples ```bash # Good feat(tasks): add dependency enforcement on task completion [BE-S3-03] fix(auth): handle expired refresh token gracefully test(projects): add service unit tests for template change [BE-S2-11] chore(ci): add coverage threshold check to CI workflow docs(onboarding): update setup steps for Docker dev environment chore: bump demo CDN pin from v4 to v5 # Bad update code fix bug WIP added the task thing chore: bump demo CDN pin from @4 to @5 # `@4`/`@5` become user mentions fix: do thing and also bump version # two intents: split into two commits ```