use-git-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Agent Commit

When this skill is loaded, immediately run

git-agent commit

. Do not ask the user what to do. Do not show a menu.

加载此技能后，立即运行

git-agent commit

。不要询问用户操作，不要显示菜单。

Steps

步骤

Intent — derive a one-sentence intent from the conversation. If no signal exists, run
```
git diff --stat
```
to understand what changed, then form the intent from that.
Commit — run:
```
git-agent commit --intent "..."
```
No provider flags on the first attempt.
On auth error (401 / missing key) — retry once with
```
--free
```
:
```
git-agent commit --intent "..." --free
```
If
--free
also fails — guide the user to create
```
~/.config/git-agent/config.yml
```
:
yaml
```
base_url: https://api.openai.com/v1
api_key: sk-...
model: gpt-4o
```
Other supported providers: Cloudflare Workers AI, local Ollama.

意图——从对话中提炼出一句式的意图。如果没有相关信号，运行
```
git diff --stat
```
来了解变更内容，再据此形成意图。
提交——运行：
```
git-agent commit --intent "..."
```
首次尝试时不使用提供商标志。
遇到认证错误（401 / 缺失密钥）时——添加
```
--free
```
参数重试一次：
```
git-agent commit --intent "..." --free
```
如果
--free
也失败——引导用户创建
```
~/.config/git-agent/config.yml
```
文件：
yaml
```
base_url: https://api.openai.com/v1
api_key: sk-...
model: gpt-4o
```
其他支持的提供商：Cloudflare Workers AI、本地Ollama。

Useful flags

实用标志

Flag	When to use
`--dry-run`	User wants to preview the message without committing
`--no-stage`	User has already staged specific files and doesn't want auto-staging
`--amend`	User wants to rewrite the most recent commit message
`--intent "..."`	Always set — keeps generated messages focused
`--co-author "Name <email>"`	Attribute a co-author (repeatable); skipped if `no_model_co_author` is set in config
`--trailer "Key: Value"`	Add an arbitrary git trailer (repeatable)
`--no-attribution`	Omit the default `Co-Authored-By: Git Agent` trailer
`--max-diff-lines N`	Cap diff size sent to the model (0 = no limit)

--amend

and

--no-stage

are mutually exclusive.

标志	使用场景
`--dry-run`	用户想要预览提交信息而不实际提交
`--no-stage`	用户已暂存特定文件，不希望自动暂存
`--amend`	用户想要重写最近一次的提交信息
`--intent "..."`	始终需要设置——确保生成的信息聚焦主题
`--co-author "Name <email>"`	添加协作者（可重复使用）；若配置中设置了 `no_model_co_author` 则会跳过
`--trailer "Key: Value"`	添加任意的Git尾部信息（可重复使用）
`--no-attribution`	省略默认的 `Co-Authored-By: Git Agent` 尾部信息
`--max-diff-lines N`	限制发送给模型的diff行数（0表示无限制）

--amend

和

--no-stage

不能同时使用。

Multi-commit splitting

多提交拆分

git-agent automatically splits staged changes into multiple atomic commits (up to 5 groups) when the AI planner detects logically distinct changes. Each group is staged, committed, and hook-validated separately. No user action is needed — this is the default behavior.

当AI规划器检测到逻辑上独立的变更时，git-agent会自动将暂存的变更拆分为多个原子提交（最多5组）。每组会分别进行暂存、提交和钩子验证。无需用户操作——这是默认行为。

Auto-scope

自动范围

If no scopes are configured for the project, git-agent generates scopes from git history automatically before planning. Each scope is a structured object with a

name

and an optional

description

(used as LLM context during commit message generation). To trigger scope generation manually:

git-agent init --scope

如果项目未配置范围，git-agent会在规划前自动从Git历史记录中生成范围。每个范围是一个包含

name

和可选

description

的结构化对象（在生成提交信息时用作LLM的上下文）。要手动触发范围生成：

git-agent init --scope

。

Hook failures

钩子失败

If the commit is blocked (exit code

), retry with a more specific

--intent

git-agent commit --intent "update module path"

Hook exit codes:

= allow, non-zero = block.

如果提交被阻止（退出码

），使用更具体的

--intent

重试：

git-agent commit --intent "update module path"

钩子退出码：

= 允许，非0 = 阻止。

Commit format

提交格式

<type>(<scope>): <description>

- <Bullet one>
- <Bullet two>

<Explanation paragraph>

Co-Authored-By: Git Agent <noreply@git-agent.dev>

Title: lowercase, ≤50 chars, no period
Bullets: uppercase first letter, imperative mood, ≤72 chars per bullet; LLM generates as a JSON array — trailers never enter LLM context
Explanation: required, sentence case; lines >100 chars are wrapped to ~72 chars
Terminal output shows only the explanation paragraph (bullets appear in the git commit body but not in the CLI output)

<type>(<scope>): <description>

- <Bullet one>
- <Bullet two>

<Explanation paragraph>

Co-Authored-By: Git Agent <noreply@git-agent.dev>

标题：小写，≤50字符，无句号
项目符号：首字母大写，祈使语气，每个项目符号≤72字符；LLM会以JSON数组形式生成——尾部信息不会进入LLM上下文
说明：必填，句首大写；超过100字符的行将换行至约72字符
终端输出仅显示说明段落（项目符号会出现在Git提交正文中，但不会在CLI输出中显示）

Other commands

其他命令

Command	What it does
`git-agent init`	Initialize git-agent in a repo (generates scopes, .gitignore, installs hooks)
`git-agent init --scope`	Regenerate scopes only
`git-agent config show`	Show resolved provider configuration
`git-agent config set <key> <value>`	Set a config value (auto-selects scope)
`git-agent config get <key>`	Show a config value and its source scope
`git-agent completion <shell>`	Generate shell completions (bash/zsh/fish/powershell)
`git-agent version`	Print build version

命令	功能
`git-agent init`	在仓库中初始化git-agent（生成范围、.gitignore、安装钩子）
`git-agent init --scope`	仅重新生成范围
`git-agent config show`	显示已解析的提供商配置
`git-agent config set <key> <value>`	设置配置值（自动选择范围）
`git-agent config get <key>`	显示配置值及其来源范围
`git-agent completion <shell>`	生成Shell补全脚本（bash/zsh/fish/powershell）
`git-agent version`	打印构建版本

CLI reference

CLI参考

Full command reference (all flags, subcommands, config scopes, hook types): references/cli.md

完整的命令参考（所有标志、子命令、配置范围、钩子类型）：references/cli.md