git-commit-push-pr

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Commit, Push, and PR

Git 提交、推送及创建PR

Go from working tree changes to an open pull request in a single workflow. The key differentiator of this skill is PR descriptions that communicate value and intent proportional to the complexity of the change.

只需一个工作流，即可从工作区的代码变更直接过渡到创建好的PR。此技能的核心优势在于，生成的PR描述会根据变更的复杂程度，精准传达价值与意图。

Workflow

工作流

Step 1: Gather context

步骤1：收集上下文信息

Run these commands. Use

command git

to bypass aliases and RTK proxies.

bash

command git status
command git diff HEAD
command git branch --show-current
command git log --oneline -10
command git rev-parse --abbrev-ref origin/HEAD

The last command returns the remote default branch (e.g.,

origin/main

). Strip the

origin/

prefix to get the branch name. If the command fails or returns a bare

HEAD

, try:

bash

command gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'

If both fail, fall back to

main

If there are no changes, report that and stop.

运行以下命令。使用

command git

绕过别名和RTK代理工具。

bash

command git status
command git diff HEAD
command git branch --show-current
command git log --oneline -10
command git rev-parse --abbrev-ref origin/HEAD

最后一条命令会返回远程默认分支（例如

origin/main

）。去掉

origin/

前缀即可得到分支名称。如果该命令执行失败或返回空的

HEAD

，请尝试：

bash

command gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'

如果两个命令都失败，则默认使用

main

分支。

如果没有任何代码变更，请告知用户并终止流程。

Step 2: Determine conventions

步骤2：确定规范

Follow this priority order for commit messages and PR titles:

Repo conventions already in context -- If project instructions (AGENTS.md, CLAUDE.md, or similar) are loaded and specify conventions, follow those. Do not re-read these files; they are loaded at session start.
Recent commit history -- If no explicit convention exists, match the pattern visible in the last 10 commits.
Default: conventional commits --
```
type(scope): description
```
as the fallback.

提交信息及PR标题遵循以下优先级顺序：

仓库已有的上下文规范——如果已加载项目说明文档（如AGENTS.md、CLAUDE.md等）且其中指定了规范，请遵循这些规范。无需重新读取这些文件，它们会在会话启动时加载。
近期提交历史——如果没有明确的规范，请匹配最近10次提交的格式。
默认：约定式提交——如果以上都不满足，使用
```
type(scope): description
```
格式作为 fallback。

Step 3: Check for existing PR

步骤3：检查是否存在现有PR

Before committing, check whether a PR already exists for the current branch:

bash

command gh pr view --json url,title,state

Interpret the result:

If it returns PR data with
state: OPEN
, note the URL and continue to Step 4 (commit) and Step 5 (push). Then skip to Step 7 (existing PR flow) instead of creating a new PR.
If it returns PR data with a non-OPEN state (CLOSED, MERGED), treat this the same as "no PR exists" -- the previous PR is done and a new one is needed.
If it errors with "no pull requests found", no PR exists. Continue to Step 4 through Step 8 as normal.
If it errors for another reason (auth, network, repo config), report the error to the user and stop.

在提交之前，检查当前分支是否已存在对应的PR：

bash

command gh pr view --json url,title,state

根据结果进行处理：

如果返回的PR数据中
state: OPEN
，记录其URL，继续执行步骤4（提交）和步骤5（推送），然后跳过步骤6和8，直接执行步骤7（现有PR流程），无需创建新PR。
如果返回的PR数据状态为非OPEN（CLOSED、MERGED），则视为“无PR存在”——之前的PR已完成，需要创建新的PR。
如果报错提示“no pull requests found”，说明无PR存在，正常执行步骤4至步骤8。
如果因其他原因报错（权限、网络、仓库配置问题），请将错误信息告知用户并终止流程。

Step 4: Branch, stage, and commit

步骤4：创建分支、暂存并提交

If on
```
main
```
,
```
master
```
, or the resolved default branch from Step 1, create a descriptive feature branch first (
```
command git checkout -b <branch-name>
```
). Derive the branch name from the change content.
Before staging everything together, scan the changed files for naturally distinct concerns. If modified files clearly group into separate logical changes (e.g., a refactor in one set of files and a new feature in another), create separate commits for each group. Keep this lightweight -- group at the file level only (no
```
git add -p
```
), split only when obvious, and aim for two or three logical commits at most. If it's ambiguous, one commit is fine.
Stage relevant files by name. Avoid
```
git add -A
```
or
```
git add .
```
to prevent accidentally including sensitive files.
Commit following the conventions from Step 2. Use a heredoc for the message.

如果当前处于
```
main
```
、
```
master
```
或步骤1中确定的默认分支，请先创建一个描述性的功能分支（
```
command git checkout -b <branch-name>
```
）。分支名称应根据变更内容生成。
在一次性暂存所有变更之前，扫描变更文件，查看是否存在自然区分的关注点。如果修改的文件可以清晰地分组为独立的逻辑变更（例如，一组文件是重构内容，另一组是新功能），则为每组创建单独的提交。此操作应保持轻量化——仅按文件级别分组（不使用
```
git add -p
```
），仅在明显需要拆分时才拆分，最多拆分为2-3个逻辑提交。如果边界模糊，使用单个提交即可。
按文件名暂存相关文件。避免使用
```
git add -A
```
或
```
git add .
```
，以防意外包含敏感文件。
遵循步骤2确定的规范进行提交。使用 heredoc 格式编写提交信息。

Step 5: Push

步骤5：推送

bash

command git push -u origin HEAD

bash

command git push -u origin HEAD

Step 6: Write the PR description

步骤6：编写PR描述

Before writing, determine the base branch and gather the full branch scope. The working-tree diff from Step 1 only shows uncommitted changes at invocation time -- the PR description must cover all commits that will appear in the PR.

编写之前，先确定基准分支并收集完整的分支范围。步骤1中的工作区差异仅显示调用时的未提交变更——PR描述必须涵盖PR中会出现的所有提交。

Detect the base branch and remote

检测基准分支和远程仓库

Resolve the base branch and the remote that hosts it. In fork-based PRs the base repository may correspond to a remote other than

origin

(commonly

upstream

Use this fallback chain. Stop at the first that succeeds:

PR metadata (if an existing PR was found in Step 3):
bash
```
command gh pr view --json baseRefName,url
```
Extract
```
baseRefName
```
as the base branch name. The PR URL contains the base repository (
```
https://github.com/<owner>/<repo>/pull/...
```
). Determine which local remote corresponds to that repository:
bash
```
command git remote -v
```
Match the
```
owner/repo
```
from the PR URL against the fetch URLs. Use the matching remote as the base remote. If no remote matches, fall back to
```
origin
```
.

origin/HEAD
symbolic ref:

bash

command git symbolic-ref --quiet --short refs/remotes/origin/HEAD

Strip the

origin/

prefix from the result. Use

origin

as the base remote.

GitHub default branch metadata:

bash

command gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'

Use

origin

as the base remote.

Common branch names -- check
```
main
```
,
```
master
```
,
```
develop
```
,
```
trunk
```
in order. Use the first that exists on the remote:
bash
```
command git rev-parse --verify origin/<candidate>
```
Use
```
origin
```
as the base remote.

If none resolve, ask the user to specify the target branch. Use the platform's blocking question tool (

AskUserQuestion

in Claude Code,

request_user_input

in Codex,

ask_user

in Gemini). If no question tool is available, present the options and wait for the user's reply.

确定基准分支及其所在的远程仓库。在基于fork的PR中，基准仓库可能对应

origin

之外的远程仓库（通常是

upstream

）。

使用以下 fallback 链，直到第一个成功的方法：

PR元数据（如果步骤3中发现现有PR）：
bash
```
command gh pr view --json baseRefName,url
```
提取
```
baseRefName
```
作为基准分支名称。PR URL中包含基准仓库信息（
```
https://github.com/<owner>/<repo>/pull/...
```
）。确定哪个本地远程仓库对应该仓库：
bash
```
command git remote -v
```
将PR URL中的
```
owner/repo
```
与fetch URL进行匹配。使用匹配的远程仓库作为基准远程仓库。如果没有匹配的远程仓库， fallback 到
```
origin
```
。

origin/HEAD
符号引用：

bash

command git symbolic-ref --quiet --short refs/remotes/origin/HEAD

去掉结果中的

origin/

前缀。使用

origin

作为基准远程仓库。

GitHub默认分支元数据：

bash

command gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'

使用

origin

作为基准远程仓库。

常见分支名称——按顺序检查
```
main
```
、
```
master
```
、
```
develop
```
、
```
trunk
```
。使用第一个在远程仓库存在的分支：
bash
```
command git rev-parse --verify origin/<candidate>
```
使用
```
origin
```
作为基准远程仓库。

如果以上方法都无法确定，请询问用户指定目标分支。使用平台的阻塞式提问工具（Claude Code中的

AskUserQuestion

、Codex中的

request_user_input

、Gemini中的

ask_user

）。如果没有提问工具，请列出选项并等待用户回复。

Gather the branch scope

收集分支范围

Once the base branch and remote are known:

Verify the remote-tracking ref exists locally and fetch if needed:

bash

command git rev-parse --verify <base-remote>/<base-branch>

If this fails (ref missing or stale), fetch it:

bash

command git fetch --no-tags <base-remote> <base-branch>

Find the merge base:

bash

command git merge-base <base-remote>/<base-branch> HEAD

List all commits unique to this branch:

bash

command git log --oneline <merge-base>..HEAD

Get the full diff a reviewer will see:
bash
```
command git diff <merge-base>...HEAD
```

Use the full branch diff and commit list as the basis for the PR description -- not the working-tree diff from Step 1.

This is the most important step. The description must be adaptive -- its depth should match the complexity of the change. A one-line bugfix does not need a table of performance results. A large architectural change should not be a bullet list.

确定基准分支和远程仓库后：

验证本地是否存在远程跟踪引用，若不存在则拉取：
bash
```
command git rev-parse --verify <base-remote>/<base-branch>
```
如果失败（引用缺失或过期），则拉取：
bash
```
command git fetch --no-tags <base-remote> <base-branch>
```

找到合并基准：

bash

command git merge-base <base-remote>/<base-branch> HEAD

列出当前分支独有的所有提交：

bash

command git log --oneline <merge-base>..HEAD

获取评审者将看到的完整差异：
bash
```
command git diff <merge-base>...HEAD
```

使用完整的分支差异和提交列表作为PR描述的基础——而非步骤1中的工作区差异。

这是最重要的步骤。描述必须自适应——其深度应与变更的复杂程度匹配。一行代码的bug修复不需要性能结果表格；大型架构变更不应仅用项目符号列表描述。

Sizing the change

变更规模评估

Assess the PR along two axes before writing, based on the full branch diff:

Size: How many files changed? How large is the diff?
Complexity: Is this a straightforward change (rename, dependency bump, typo fix) or does it involve design decisions, trade-offs, new patterns, or cross-cutting concerns?

Use this to select the right description depth:

Change profile	Description approach
Small + simple (typo, config, dep bump)	1-2 sentences, no headers. Total body under ~300 characters.
Small + non-trivial (targeted bugfix, behavioral change)	Short "Problem / Fix" narrative, ~3-5 sentences. Enough for a reviewer to understand why without reading the diff. No headers needed unless there are two distinct concerns.
Medium feature or refactor	Summary paragraph, then a section explaining what changed and why. Call out design decisions.
Large or architecturally significant	Full narrative: problem context, approach chosen (and why), key decisions, migration notes or rollback considerations if relevant.
Performance improvement	Include before/after measurements if available. A markdown table is effective here.

Brevity matters for small changes. A 3-line bugfix with a 20-line PR description signals the author didn't calibrate. Match the weight of the description to the weight of the change. When in doubt, shorter is better -- reviewers can read the diff.

编写之前，根据完整的分支差异从两个维度评估PR：

大小：变更了多少文件？差异的规模有多大？
复杂度：这是一个简单的变更（重命名、依赖版本升级、拼写错误修复），还是涉及设计决策、权衡、新模式或跨领域问题？

根据评估结果选择合适的描述深度：

变更类型	描述方式
小型+简单（拼写错误、配置修改、依赖升级）	1-2句话，无标题。正文总长度约300字符以内。
小型+非平凡（针对性bug修复、行为变更）	简短的“问题/修复”叙述，约3-5句话。足够让评审者无需查看差异即可理解原因。除非有两个不同的关注点，否则不需要标题。
中型功能或重构	摘要段落，然后是解释变更内容和原因的章节。重点说明设计决策。
大型或架构级变更	完整叙述：问题背景、选择的方案（及原因）、关键决策、迁移说明或回滚注意事项（如有相关）。
性能优化	如果有数据，包含优化前后的测量结果。Markdown表格是有效的展示方式。

小型变更需简洁。一个3行代码的bug修复搭配20行的PR描述，说明作者没有根据变更规模调整描述长度。描述的篇幅应与变更的重要性匹配。如有疑问，尽量简短——评审者可以查看差异。

Writing principles

编写原则

Lead with value: The first sentence should tell the reviewer why this PR exists, not what files changed. "Fixes timeout errors during batch exports" beats "Updated export_handler.py and config.yaml".
No orphaned opening paragraphs: If the description uses
```
##
```
section headings anywhere, the opening summary must also be under a heading (e.g.,
```
## Summary
```
). An untitled paragraph followed by titled sections looks like a missing heading. For short descriptions with no sections, a bare paragraph is fine.
Describe the net result, not the journey: The PR description is about the end state -- what changed and why. Do not include work-product details like bugs found and fixed during development, intermediate failures, debugging steps, iteration history, or refactoring done along the way. Those are part of getting the work done, not part of the result. If a bug fix happened during development, the fix is already in the diff -- mentioning it in the description implies it's a separate concern the reviewer should evaluate, when really it's just part of the final implementation. Exception: include process details only when they are critical for a reviewer to understand a design choice (e.g., "tried approach X first but it caused Y, so went with Z instead").
Explain the non-obvious: If the diff is self-explanatory, don't narrate it. Spend description space on things the diff doesn't show: why this approach, what was considered and rejected, what the reviewer should pay attention to.
Use structure when it earns its keep: Headers, bullet lists, and tables are tools -- use them when they aid comprehension, not as mandatory template sections. An empty "## Breaking Changes" section adds noise.
Markdown tables for data: When there are before/after comparisons, performance numbers, or option trade-offs, a table communicates density well. Example:
markdown
```
| Metric | Before | After |
|--------|--------|-------|
| p95 latency | 340ms | 120ms |
| Memory (peak) | 2.1GB | 1.4GB |
```
No empty sections: If a section (like "Breaking Changes" or "Migration Guide") doesn't apply, omit it entirely. Do not include it with "N/A" or "None".
Test plan -- only when it adds value: Include a test plan section when the testing approach is non-obvious: edge cases the reviewer might not think of, verification steps for behavior that's hard to see in the diff, or scenarios that require specific setup. Omit it for straightforward changes where the tests are self-explanatory or where "run the tests" is the only useful guidance. A test plan for "verify the typo is fixed" is noise.

以价值为导向：第一句话应告诉评审者为什么需要这个PR，而不是变更了哪些文件。“修复批量导出时的超时错误”比“更新了export_handler.py和config.yaml”更好。
避免无标题的开篇段落：如果描述中使用了
```
##
```
章节标题，开篇摘要也应放在标题下（例如
```
## 摘要
```
）。无标题段落后跟有标题的章节，看起来像是缺失了标题。对于没有章节的简短描述，使用无标题段落即可。
描述最终结果，而非过程：PR描述应关注最终状态——变更了什么以及为什么。不要包含工作过程中的细节，比如开发过程中发现并修复的bug、中间的失败、调试步骤、迭代历史或重构过程。这些是完成工作的过程，而非结果的一部分。如果开发过程中修复了一个bug，该修复已包含在差异中——在描述中提及它，会让评审者误以为这是一个需要单独评估的独立关注点，但实际上它只是最终实现的一部分。例外情况：只有当过程细节对评审者理解设计选择至关重要时才包含（例如“最初尝试了方案X，但它导致了问题Y，因此选择了方案Z”）。
解释非显而易见的内容：如果差异本身已经很清晰，无需赘述。将描述的篇幅用于差异无法展示的内容：为什么选择此方案、考虑过并否决了哪些方案、评审者应关注什么。
必要时使用结构化格式：标题、项目符号列表和表格是工具——只有当它们有助于理解时才使用，不要作为强制的模板章节。空的“## 破坏性变更”章节会增加噪音。
用Markdown表格展示数据：当需要展示优化前后的对比、性能数据或方案权衡时，表格是高效的展示方式。示例：
markdown
```
| 指标 | 优化前 | 优化后 |
|--------|--------|-------|
| p95延迟 | 340ms | 120ms |
| 内存峰值 | 2.1GB | 1.4GB |
```
不要包含空章节：如果某个章节（如“破坏性变更”或“迁移指南”）不适用，请完全省略。不要用“N/A”或“无”填充。
测试计划——仅在有价值时添加：当测试方法非显而易见时，添加测试计划章节：评审者可能想不到的边缘情况、差异中难以看到的行为验证步骤、或需要特定设置的场景。对于简单变更，若测试本身已清晰明了，或“运行测试”是唯一有用的指导，则省略该章节。为“验证拼写错误已修复”编写测试计划是多余的。

Numbering and references

编号与引用

Never prefix list items with
#
in PR descriptions. GitHub interprets

#1

#2

, etc. as issue/PR references and auto-links them. Instead of:

markdown

undefined

在PR描述中，永远不要用
#
作为列表项的前缀。GitHub会将

#1

、

#2

等解析为issue/PR引用并自动链接。不要这样写：

markdown

undefined

Changes

变更内容

#1. Updated the parser #2. Fixed the validation


Write:

```markdown

#1. 更新了解析器 #2. 修复了验证逻辑


应这样写：

```markdown

Changes

变更内容

Updated the parser
Fixed the validation


When referencing actual GitHub issues or PRs, use the full format: `org/repo#123` or the full URL. Never use bare `#123` unless you have verified it refers to the correct issue in the current repository.

更新了解析器
修复了验证逻辑


当引用GitHub的issue或PR时，使用完整格式：`org/repo#123`或完整URL。除非已验证它指向当前仓库中的正确issue，否则不要使用裸的`#123`。

Compound Engineering badge

Compound Engineering徽章

Append a badge footer to the PR description, separated by a

---

rule. Do not add one if the description already contains a Compound Engineering badge (e.g., added by another skill like ce-work).

markdown

---

[![Compound Engineering v[VERSION]](https://img.shields.io/badge/Compound_Engineering-v[VERSION]-6366f1)](https://github.com/EveryInc/compound-engineering-plugin)
🤖 Generated with [MODEL] ([CONTEXT] context, [THINKING]) via [HARNESS](HARNESS_URL)

Fill in at PR creation time:

Placeholder	Value	Example
`[MODEL]`	Model name	Claude Opus 4.6, GPT-5.4
`[CONTEXT]`	Context window (if known)	200K, 1M
`[THINKING]`	Thinking level (if known)	extended thinking
`[HARNESS]`	Tool running you	Claude Code, Codex, Gemini CLI
`[HARNESS_URL]`	Link to that tool	`https://claude.com/claude-code`
`[VERSION]`	`plugin.json` -> `version`	2.40.0

在PR描述末尾添加徽章页脚，用

---

分隔。如果描述中已包含Compound Engineering徽章（例如由其他技能如ce-work添加），则无需重复添加。

markdown

---

[![Compound Engineering v[VERSION]](https://img.shields.io/badge/Compound_Engineering-v[VERSION]-6366f1)](https://github.com/EveryInc/compound-engineering-plugin)
🤖 Generated with [MODEL] ([CONTEXT] context, [THINKING]) via [HARNESS](HARNESS_URL)

创建PR时填充以下占位符：

占位符	取值	示例
`[MODEL]`	模型名称	Claude Opus 4.6, GPT-5.4
`[CONTEXT]`	上下文窗口大小（如果已知）	200K, 1M
`[THINKING]`	思考级别（如果已知）	extended thinking
`[HARNESS]`	运行你的工具	Claude Code, Codex, Gemini CLI
`[HARNESS_URL]`	工具链接	`https://claude.com/claude-code`
`[VERSION]`	`plugin.json` 中的 `version` 字段	2.40.0

Step 7: Create or update the PR

步骤7：创建或更新PR

New PR (no existing PR from Step 3)

新PR（步骤3中未发现现有PR）

bash

command gh pr create --title "the pr title" --body "$(cat <<'EOF'
PR description here

---

[![Compound Engineering v[VERSION]](https://img.shields.io/badge/Compound_Engineering-v[VERSION]-6366f1)](https://github.com/EveryInc/compound-engineering-plugin)
🤖 Generated with [MODEL] ([CONTEXT] context, [THINKING]) via [HARNESS](HARNESS_URL)
EOF
)"

Keep the PR title under 72 characters. The title follows the same convention as commit messages (Step 2).

bash

command gh pr create --title "the pr title" --body "$(cat <<'EOF'
PR描述内容

---

[![Compound Engineering v[VERSION]](https://img.shields.io/badge/Compound_Engineering-v[VERSION]-6366f1)](https://github.com/EveryInc/compound-engineering-plugin)
🤖 Generated with [MODEL] ([CONTEXT] context, [THINKING]) via [HARNESS](HARNESS_URL)
EOF
)"

PR标题长度应控制在72字符以内。标题遵循与提交信息相同的规范（步骤2）。

Existing PR (found in Step 3)

现有PR（步骤3中发现）

The new commits are already on the PR from the push in Step 5. Report the PR URL, then ask the user whether they want the PR description updated to reflect the new changes. Use the platform's blocking question tool (

AskUserQuestion

in Claude Code,

request_user_input

in Codex,

ask_user

in Gemini). If no question tool is available, present the option and wait for the user's reply before proceeding.

If yes -- write a new description following the same principles in Step 6 (size the full PR, not just the new commits), including the Compound Engineering badge unless one is already present in the existing description. Apply it:
bash
```
command gh pr edit --body "$(cat <<'EOF'
Updated description here
EOF
)"
```
If no -- done. The push was all that was needed.

步骤5中的推送操作已将新提交同步到现有PR中。告知用户PR的URL，然后询问用户是否需要更新PR描述以反映新的变更。使用平台的阻塞式提问工具（Claude Code中的

AskUserQuestion

、Codex中的

request_user_input

、Gemini中的

ask_user

）。如果没有提问工具，请列出选项并等待用户回复后再继续。

如果用户回答是——按照步骤6中的原则编写新描述（基于完整PR的规模，而非仅新提交），除非现有描述中已包含Compound Engineering徽章，否则需添加该徽章。执行以下命令更新：
bash
```
command gh pr edit --body "$(cat <<'EOF'
更新后的描述内容
EOF
)"
```
如果用户回答否——流程完成，仅推送操作即可。

Step 8: Report

步骤8：结果反馈

Output the PR URL so the user can navigate to it directly.

输出PR的URL，方便用户直接访问。

Important: Use

command git

and

command gh

重要提示：使用

command git

和

command gh

Always invoke git as

command git

and gh as

command gh

in shell commands. This bypasses shell aliases and tools like RTK (Rust Token Killer) that proxy commands.

在shell命令中，始终以

command git

和

command gh

的形式调用git和gh工具。这可以绕过shell别名和RTK（Rust Token Killer）等代理工具。

git-commit-push-pr

Original

Translation

Git Commit, Push, and PR

Git 提交、推送及创建PR

Workflow

工作流

Step 1: Gather context

步骤1：收集上下文信息

Step 2: Determine conventions

步骤2：确定规范

Step 3: Check for existing PR

步骤3：检查是否存在现有PR

Step 4: Branch, stage, and commit

步骤4：创建分支、暂存并提交

Step 5: Push

步骤5：推送

Step 6: Write the PR description

步骤6：编写PR描述

Detect the base branch and remote

检测基准分支和远程仓库

Gather the branch scope

收集分支范围

Sizing the change

变更规模评估

Writing principles

编写原则

Numbering and references

编号与引用

Changes

变更内容

Changes

变更内容

Compound Engineering badge

Compound Engineering徽章

Step 7: Create or update the PR

步骤7：创建或更新PR

New PR (no existing PR from Step 3)

新PR（步骤3中未发现现有PR）

Existing PR (found in Step 3)

现有PR（步骤3中发现）

Step 8: Report

步骤8：结果反馈

Important: Use command git and command gh

重要提示：使用command git和command gh

Important: Use
`command git`
and
`command gh`

重要提示：使用
`command git`
和
`command gh`