Git Commit

---
name: git-commit
description: Commit work the right way by gathering full repo state, respecting the project's commitlint/pre-commit/branch rules, staging only understood files, and writing a conventional-commit message whose body explains why. Use when committing, branching, or pushing changes.
argument-hint: "(optional) ticket/issue ref, scope, or what to commit"
---

Turn a set of changes into a clean, conventional commit (and push, if asked). Work from the actual repo state and the project's own rules, never from assumptions about what the change "probably" is.

## Hard rules: never break these

- **No co-authors, ever.** Never add a `Co-Authored-By:` trailer. Never mention Claude, Claude Code, or any AI in a commit message, body, or branch name. The message must read as if a human engineer wrote it.
- **Commit only when asked.** Do not commit mid-task, opportunistically, or "to be safe." Wait for an explicit instruction to commit. One commit per request unless the user asks for more.
- **Confirm before `git commit` and `git push`.** State exactly what you're about to commit (files + message) or push (branch + remote) and get a yes first. These are not reversible-for-free; treat them as outward-facing.
- **Never `git add -A` or `git add .`.** Stage files explicitly by path, and only files you've inspected and understood.
- **Never commit ignored or generated content.** No `node_modules`, build output, `.env`/secrets/keys, lockfile churn you didn't intend, or generated artifacts (plans, reports, analyses, summaries, scratch notes). Source-code changes only; anything else needs an explicit ask.

## Step 1: Gather full context

Build a complete picture before touching anything. Run these (read-only) and actually read the output:

- `git status`: what's modified, staged, untracked.
- `git diff` (unstaged) and `git diff --staged` (staged): the actual changes, line by line.
- `git branch --show-current` and `git branch -a`: where you are and what exists.
- `git log --oneline -15`: the repo's established message and scope style; match it.
- `git status --ignored`: confirm nothing sensitive or generated is sneaking in, and that `.gitignore` already covers `node_modules`, build dirs, env files, etc.

If something is untracked that *should* be ignored (secrets, env, build output, dependencies), flag it and suggest a `.gitignore` entry rather than committing it.

## Step 2: Discover and honor the project's rules

Repos enforce their own conventions; find and obey them before writing anything:

- **Commit-message linting**: look for `commitlint.config.{js,cjs,mjs,ts}`, `.commitlintrc*`, a `commitlint` key in `package.json`, or equivalents in other ecosystems. Read the allowed types/scopes and subject limits and conform exactly.
- **Pre-commit / hooks**: check `.pre-commit-config.yaml`, `.husky/`, `.git/hooks/`, `lefthook.yml`, or framework equivalents. The commit must pass these. Don't bypass with `--no-verify`; if a hook fails, fix the cause (formatting, lint, tests) and report it.
- **Branch-name rules**: some repos lint branch names too (in commitlint config, hooks, or CONTRIBUTING). Conform.
- **Contributor docs**: skim `CONTRIBUTING*` and any PR/commit template for additional expectations.

When the repo's rules conflict with the defaults below, the repo wins.

## Step 3: Stage logically

- Group **related** changes into one commit; split **unrelated** changes into separate commits. A commit should be one coherent idea.
- Stage by explicit path (`git add path/to/file`), reviewing each. Use `git add -p` to split mixed files into logical hunks.
- Leave out incidental churn, debug leftovers, and anything from the "never commit" list.

## Step 4: Branch (when needed)

If the work doesn't belong on the current branch (e.g. you're on `main`/`master` or a release branch), create one off the up-to-date main branch. Naming convention:

| Prefix      | When to use                                     |
| ----------- | ----------------------------------------------- |
| `feat/`     | New feature                                     |
| `fix/`      | Bug fix                                         |
| `chore/`    | Maintenance, dependencies, config               |
| `docs/`     | Documentation only                              |
| `refactor/` | Code change that isn't a fix or feature         |
| `test/`     | Adding or updating tests                        |

Use short, kebab-case descriptions: `feat/task-dependency-api`, `fix/refresh-token-expiry`, `docs/update-contributing`, `chore/upgrade-prisma`. Honor any stricter rule found in Step 2.

## Step 5: Write the commit message

**Subject line**: `type(scope): summary`

- Use a Conventional Commits type: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert` (or whatever the repo's commitlint permits).
- Scope is optional but helps: `feat(auth): …`.
- Imperative mood, lowercase after the colon, no trailing period. Keep it **≤ 72 characters** (aim for ~50).
- Mark breaking changes with `!`: `feat(api)!: drop v1 token endpoint`.

**Body: explain *why*, not *what*.** The diff already shows what changed; the body exists for future code archaeology. Wrap at ~72 columns. Cover, in prose:

- **Why this change was needed**: the motivation, the trigger, the constraint.
- **The problem it solves**: the business or technical pain being addressed.
- Include a terse *what* only when the change is non-obvious from the diff.

**Footer**

- Reference tickets/issues exactly as the project does. Inline in the subject when natural (`fix(auth): handle token expiry (#42)`) and/or as footers: `Closes #42`, `Refs JIRA-1234`, `ClickUp: CU-abc`.
- If the user mentions any Jira/issue/ClickUp/tracker ID, it **must** appear in the commit.
- Breaking changes get a `BREAKING CHANGE: <description>` footer.

Template (adapt, don't pad with empty sections):

```
type(scope): concise imperative subject (#123)

Why: the motivation or constraint that prompted this change, and the
problem it solves, written for someone reading `git blame` in a year.

[Only if non-obvious] What: the key technical move that makes it work.

Closes #123
```

## Step 6: Commit and push (with confirmation)

1. Show the user the staged files and the exact message, and confirm.
2. On approval, commit. Pass multiline messages with repeated `-m` flags or a heredoc; **never** embed an AI/co-author trailer.
3. Let pre-commit hooks run. If they reformat or fail, surface it, fix the cause, and re-stage; don't `--no-verify`.
4. Push only when explicitly asked, and confirm the branch and remote first. If the branch is new, set upstream (`git push -u origin <branch>`).

Report what landed: the commit hash/subject and, if pushed, where.