Skip to content

pivoshenko/pivoshenko.ai / skills/git-commit

git-commit

Verified

Run git commit using Angular conventional commit format (header + footer only, no body). Use when the user asks to commit, create a commit, /git-commit, or save changes to git. Also trigger on "snapshot this", "save my work", "check in changes", "wrap up", "ship this locally", or whenever the user finishes a logical unit of work and the tree is dirty. Boundary with `git-pr-create`: this skill owns only the explicitly local framing - bare "ship this" / "ship it" / "send for review" means the work should leave the machine, which is `git-pr-create`'s flow. Stages relevant files and commits immediately without asking for confirmation.

Git Commit

Conventional commit. No confirm. No dry-run.

Flow

  1. Parallel: git status + git diff --staged
  2. Nothing staged -> stage relevant (paths > -A). Something already staged -> commit exactly the stage; mention leftover unstaged paths, don't add them. Never .env / creds / secrets
  3. Parallel: git diff --staged (if just staged) + git log --oneline -5
  4. Read diff -> one commit or many (see Atomic) -> write msg
    • Branch linked to an issue -> add the closing trailer. Read the link with git config --get branch.$(git branch --show-current).issue; git-issue-start records it there. Why -> the branch name carries no ticket id by default, so this is the only durable link between the work and the tracker
    • Many commits from one issue -> the trailer goes on the last one only. Why -> every commit carrying Closes #42 is noise on the issue timeline, and GitHub closes on the first merged one regardless
  5. Commit now. Many groups + already mass-staged -> git restore --staged . to unstage (modern idiom; git reset HEAD also fine), then stage+commit per group. Loop til clean
  6. Print hash + one-liner per commit

Atomic

Mixed concerns -> split. No mega-commit.

Group by:

  • Type - feat / fix / docs / refactor / test never share
  • Scope - diff modules/pkgs = diff commits
  • Logical unit - one thing per commit. Each builds + tests alone

Split signals:

  • 1 unrelated area

  • Behavior + format/rename mixed (format separate)
  • Summary needs "and" / "also" / "+"
  • Unsure -> ask user how to group

Msg Format

<header>

<footer>

header required. footer optional. No body, ever.

If the header can't carry the change, the commit isn't atomic -> split it (see Atomic). The "why" lives in the PR body, the issue, or the code comment - not here.

Header

<type>(<scope>): <short summary>
  • Type: build|chore|ci|docs|feat|fix|perf|refactor|test
  • Scope: optional. Affected area/module/pkg. Lowercase, kebab/short noun. One scope only - pick the dominant one, else omit
  • Summary: imperative present ("add" not "added"/"adds"), lowercase, no trailing .
  • Whole header ≤ 72 chars. Tighter is better; aim ≤ 50 for the summary itself
  • No ticket IDs in header (go in footer). No emoji. No [WIP]

Type Pick

Pick the most specific. Behavior change > non-behavior. User-visible > internal.

SemVer bump column is the canonical mapping used by cliff.toml across all repositories. feat!: / BREAKING CHANGE: footer always -> MAJOR regardless of type.

TypeSemVerUse whenExamples
featMINORNew user-visible capability or APInew endpoint, new CLI flag, new component, new public function
fixPATCHRestoring intended behavior after a defectcrash on null input, wrong calc, regression repair
perfPATCHSame behavior, measurably faster / lightercache hot path, drop O(n²) loop, lazy-load
refactorPATCHCode shape changes; behavior identicalrename, extract, inline, move file, dedupe - no API or output change
testnoneTest files onlyadd coverage, fix flake, rename test
docsnoneDocs / comments / README / changelog onlyprose edits, JSDoc, ADRs, doc-only typos
buildnoneBuild system, deps, lockfiles, packagingpackage.json deps, uv.lock, Dockerfile, bundler config
cinoneCI/CD pipeline configGH Actions workflow, release pipeline, branch protection scripts
chorenoneRepository maintenance with no code/build/CI/docs effect.gitignore, editor config, tooling configs not tied to build

Tiebreakers

  • Bug -> fix > refactor > chore
  • Perf -> perf > refactor
  • New feature ships with its tests -> single feat commit. Tests for existing code -> test
  • README typo -> docs. README rewrite that ships new product info -> still docs (no code)
  • Bumping a dep that fixes a bug here -> fix (your bug) or build (just the bump). Pick by user-visible effect
  • Lockfile-only churn from install -> build. Tooling config like biome.json formatting rules -> chore. CI workflow YAML -> ci
  • Renaming for clarity -> refactor. Renaming to land a new API -> part of the feat
  • Formatting / whitespace -> separate chore commit
  • Revert -> revert: prefix, never one of the above (see Revert)

Footer

Trailers only. One per line, Token: value, after a single blank line below the header. Order: breaking change -> deprecation -> refs.

Allowed tokens:

  • BREAKING CHANGE: <summary> - exact spelling (Angular spec). Detail + migration steps follow on subsequent lines, ≤ 5 lines
  • DEPRECATED: <what> - same shape; include upgrade path. ≤ 5 lines
  • Fixes #<n> / Closes #<n> / Resolves #<n> - issue auto-close. Multiple -> one per line or comma-separated. Auto-filled from branch.<name>.issue when set (see Flow step 4)
  • Refs: #<n> / See: <url> - non-closing references
BREAKING CHANGE: <summary>
<detail + migration>
Fixes #<n>
DEPRECATED: <what>
<detail + upgrade path>
Closes #<n>

Footer rules:

  • No Co-Authored-By: / "Generated with Claude" / tool-attribution trailers ever, unless user explicitly asks. Why -> standing user policy
  • No Signed-off-by: unless the repository's CONTRIBUTING requires DCO
  • No empty/placeholder trailers. No footer at all is fine
  • Breaking change without migration steps -> ask user before committing. Reviewers need the upgrade path

Revert

revert: + reverted header, then a single line: This reverts commit <SHA>.

Reason -> append to that same line only if non-obvious. Nothing else.

Rules

  • One logical change per commit. Else split
  • Never --no-verify / --no-gpg-sign unless asked. Why -> hooks catch real failures (lint, type, secret scan); skipping = shipping broken code
  • Pre-commit hook fail -> fix + re-stage + new commit. No amend. Why -> hook fail means the commit didn't happen; --amend would modify the previous (unrelated) commit and silently rewrite it
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall