snowfluke/engineering-skills

git-commit

Use after completing a task when all verifications pass, to commit the work, or when cutting a GitHub release.

Quelltext ansehen

Verwendung

  1. Installationsbefehl kopieren und das Quellpaket vor der Installation in der eigenen Agentenumgebung prüfen.
  2. Benötigte Werkzeuge, Zugangsdaten und Hosts im Original prüfen.
  3. Eingabe und gewünschtes Ergebnis beschreiben und die Ausgabe mit den Quellen abgleichen.
npx skills add https://github.com/snowfluke/engineering-skills --skill git-commit

Vor dem Start

  • Die Installation umfasst weder Modellabo noch API-Kontingent oder Dateizugriffsrechte.
  • Sterne und Installationen zeigen Aktivität, keine unabhängige Qualitäts- oder Sicherheitsprüfung.
Originales Skill-Dokument

Aus dem Quell-Repository gerendert; Überschriften, Beispiele, Code, Tabellen, Links und Bilder bleiben erhalten.

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.

  1. Check what will be staged:
bash
   git status
   git diff --stat
  1. 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.

  1. 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__/)
  1. 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>(<scope>): <subject>

TypeUse when
featNew feature or behavior
fixBug fix
refactorCode change with no behavior change
testAdding or fixing tests
docsDocumentation changes only
choreBuild config, tooling, dependency updates
perfPerformance 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 `@<name>` or `@<digit>` 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
  1. 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.

  1. Repeat for the next logical commit if the working tree still has unstaged changes from a different intent. Return to step 3.
  1. Verify the commits:
bash
   git log --oneline -5
  1. 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 <commit> -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
  1. 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.

  1. 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 @<name>/@<digit> rule applies there too: never in release notes (use v4 or backticks).

  1. Verify after publish: the publish workflow run is green and the registry

shows the new version (npm view <pkg> 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 @<name> or @<digit> 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
aus demselben Repository

Weitere Skills

Alle Skills