Commit

Intro

commit is an AI command for turning staged Git changes into one intentional commit.

My Use

我用它处理已经整理好的改动：先确认暂存区边界，再检查 diff，最后生成一条清楚的 conventional commit message。它不是用来“一键提交所有东西”的，而是用来避免误提交、混合提交和含糊的提交信息。

When to Use / Not Use

适合

• 已经用 git add 暂存了本次要提交的文件
• 当前改动只有一个明确意图
• 希望提交信息保持 conventional commit 风格
• 希望 AI 在提交前帮忙检查 staged diff

不适合

• 工作区里混着多个不相关改动
• 还没决定哪些文件应该进入提交
• 需要 reset、rebase、amend、force push 等历史操作
• 只是想把所有未提交文件直接塞进一个 commit

Gotchas

• 默认边界应该是 staged files，不是整个 working tree
• 没有 staged files 时，不应该自动 git add .
• unstaged 或 untracked 文件只能提示，不能静默带入
• mixed intent 要先拆分，不要强行生成一个大 commit
• hook 失败后不应自动 --no-verify 重试
• commit message 不要包含 AI/Claude/Codex 签名

My Setup

# Commit Command

Create exactly one intentional Git commit from the current staged changes.

---

## Contract

- Treat the staged set as the default commit boundary.
- Never stage unstaged files unless the user explicitly asks or approves a proposed file set.
- Never include unrelated changes.
- Never rewrite history.
- Respect hooks by default.
- Follow the repository's existing commit style for wording and type choice, but omit emoji unless the user asks.

---

## Algorithm

**1. Inspect repository state.**
- Run `git status --short`.
- Run `git branch --show-current`.
- Stop if the repository is in a merge, rebase, cherry-pick, or conflict state.
- If message style is unclear, inspect recent commits with `git log -10 --oneline`.

**2. Determine the commit boundary.**
- Prefer the current staged files.
- If nothing is staged, stop and ask what should be staged.
- If staged changes mix unrelated intent, stop and suggest split commits.
- If unstaged or untracked files appear related, mention them but do not include them silently.

**3. Review staged changes.**
- Run `git diff --cached --stat`.
- Run `git diff --cached` to understand the staged intent before writing the message.
- Watch for secrets, private files, generated artifacts, large binaries, and accidental deletions.

**4. Generate the commit message.**
- Format: `<type>: <subject>`
- Infer the type from the primary intent.
- Keep the subject under 72 characters, imperative mood, no trailing period, no assistant signature.

  | Type | Meaning |
  |------|---------|
  | `feat` | new capability |
  | `fix` | bug fix |
  | `docs` | documentation or content |
  | `style` | formatting or visual-only change |
  | `refactor` | structure change without behavior change |
  | `perf` | performance improvement |
  | `test` | tests |
  | `chore` | maintenance |
  | `ci` | CI/CD |
  | `build` | build or dependency system |
  | `assets` | images, media, or other assets |
  | `revert` | revert a previous change |

**5. Commit.**
- Run `git commit -m "<message>"`.
- Use `--no-verify` only if explicitly requested.
- If hooks fail, summarize the failure and stop. Do not retry with `--no-verify` automatically.

**6. Report.**
- Show the commit hash and subject.
- Show the final `git status --short`.
- If changes remain, clearly state that they were not included.

Story

/commit 真正解决的问题不是少敲一条 git commit，而是把提交边界想清楚。好的提交应该让未来的自己一眼看懂：改了什么、为什么是一组、有没有把不该进来的东西带进去。

Minimal Example

git add _quarto.yml ai/commands/commit.qmd ai/commands/_prompts/commit.md
/commit

docs: add commit command page

References

• Conventional Commits
• Git commit