gh-draft-pr

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Draft PR with GitHub CLI

利用GitHub CLI创建草稿PR

When to Use

适用场景

Apply when the user wants a command to create a draft pull request with the GitHub CLI (

gh

), using the repository's PR template and improving the description using branch commits and/or chat context.

当用户需要一条命令，通过GitHub CLI（

gh

）创建草稿拉取请求（PR），同时利用仓库的PR模板，并结合分支提交记录和/或对话上下文完善PR描述时，适用本流程。

Workflow

工作流程

0. Which repository?

0. 选择对应仓库？

In a multi-root workspace, if it's unclear which project to create the PR for, ask the user first (e.g. list workspace folder names). Run all git/gh commands from that project's root.

在多根工作区中，如果不清楚要为哪个项目创建PR，请先询问用户（例如，列出工作区文件夹名称）。所有git/gh命令都要在该项目的根目录下执行。

1. Locate PR template

1. 定位PR模板

From the chosen repo root, look for a pull request template:

```
.github/pull_request_template.md
```
```
.github/PULL_REQUEST_TEMPLATE.md
```
(or
```
.MD
```
)

If none exists, use a minimal body (summary + how to test). If you asked which project to use, use the template from the chosen repo.

从选定的仓库根目录出发，查找拉取请求模板：

```
.github/pull_request_template.md
```
```
.github/PULL_REQUEST_TEMPLATE.md
```
（或
```
.MD
```
格式）

如果不存在模板，则使用极简正文（摘要 + 测试方法）。如果之前询问过用户要使用哪个项目，则使用该选定仓库的模板。

2. Gather branch and commit context

2. 收集分支与提交上下文

From the repo root:

bash

git rev-parse --show-toplevel
git branch --show-current
git log origin/main..HEAD --oneline

从仓库根目录执行以下命令：

bash

git rev-parse --show-toplevel
git branch --show-current
git log origin/main..HEAD --oneline

or: git log main..HEAD --oneline if origin/main doesn't exist

或者：如果origin/main不存在，使用 git log main..HEAD --oneline


Use the default branch (`main` or `master`) that the PR would target. Prefer `origin/main` / `origin/master` when available.

**Extract ticket from branch name** (e.g. `PROJ-194-ui-mismatch` → `PROJ-194`, `feature/CR-123` → `CR-123`) for "Closes" / "Related Ticket" in the template. Match first `PREFIX-NUMBER` (uppercase letters + hyphen + digits).


使用PR将目标合并的默认分支（`main`或`master`）。如果可用，优先使用`origin/main` / `origin/master`。

**从分支名称提取工单编号**（例如 `PROJ-194-ui-mismatch` → `PROJ-194`，`feature/CR-123` → `CR-123`），用于模板中的“Closes” / “相关工单”字段。匹配第一个`前缀-数字`格式的内容（大写字母 + 连字符 + 数字）。

3. Fill the template

3. 填充模板

Summary / What & Why: Use bullet points (one point per change or theme), derived from commit messages and recent chat (what was implemented or fixed). Do not use a single paragraph.
Related Ticket / Closes: Use the ticket ID from the branch; link to Jira if the template uses
```
https://acme.atlassian.net/browse/XXX
```
.
How to Test: From commits, file changes, and chat (routes, endpoints, flags, expected behavior). Leave placeholders if unknown.
Checklists: Leave checkboxes as-is (unchecked) unless chat or commits clearly indicate something is done.
Screenshots / Additional notes: Leave placeholders or brief notes if chat provides them.

Remove template placeholders when you fill a section: If you wrote actual content for a section (e.g. Summary, How to Test), delete that section’s instruction/pointer lines from the template (e.g. "> Provide a concise explanation...", "> Briefly describe how you tested..."). Only keep placeholder text (e.g. "> [screenshot.png]", "> Any reviewer notes...") in sections you did not fill with details.

Keep the same section headers and structure as the template so the body is valid for the repo.

摘要 / 内容与原因：使用项目符号（每个变更或主题对应一个要点），内容来自提交信息和近期对话（已实现或修复的内容）。不要使用单个段落。
相关工单 / 关闭工单：使用从分支名称提取的工单编号；如果模板使用
```
https://acme.atlassian.net/browse/XXX
```
格式，则链接到Jira工单。
测试方法：从提交记录、文件变更和对话内容（路由、端点、标识、预期行为）中提取信息。如果信息未知，则留空占位符。
检查清单：保持复选框原样（未勾选），除非对话或提交记录明确表明某项已完成。
截图 / 附加说明：如果对话中提供了相关内容，则留空占位符或添加简短说明。

填充内容后移除模板占位符：如果为某个部分（例如摘要、测试方法）填写了实际内容，请删除该部分的说明/提示行（例如 "> 提供简洁说明...", "> 简要描述测试方法..."）。仅在未填充详细内容的部分保留占位符文本（例如 "> [screenshot.png]", "> 评审者备注..."）。

保留模板的章节标题和结构，确保PR正文符合仓库的规范。

4. Write body to a file and give the command

4. 将正文写入文件并生成命令

Write the filled body to a file in the repo root, e.g.
```
.pr-body-draft.md
```
(or
```
pr-draft-body.md
```
). Use a path that is gitignored or that the user can delete later.
Prefer a single, copy-pastable command that creates the draft PR.

Standard form:

bash

gh pr create --draft --title "Brief title from branch/commits" --body-file .pr-body-draft.md

Title: Short, imperative or descriptive (e.g. from first commit or branch name). Can use
```
--fill
```
to take title/body from commits, but then body is overridden by
```
--body-file
```
; so prefer an explicit
```
--title
```
that matches the work.
Body: Always use
```
--body-file
```
with the filled template file so the PR follows the repo template.

If the user prefers not to leave a file on disk, use stdin:

bash

gh pr create --draft --title "Brief title" --body-file -

Then show the filled body and tell them to paste it when the command prompts, or use a heredoc (e.g.

<< 'PRBODY' ... PRBODY

) in the same shell command.

将填充后的正文写入仓库根目录下的一个文件，例如
```
.pr-body-draft.md
```
（或
```
pr-draft-body.md
```
）。使用已被git忽略或用户后续可删除的路径。
优先提供单个可复制粘贴的命令来创建草稿PR。

标准格式：

bash

gh pr create --draft --title "来自分支/提交的简短标题" --body-file .pr-body-draft.md

标题：简短、祈使语气或描述性内容（例如来自第一个提交或分支名称）。可以使用
```
--fill
```
参数从提交记录中获取标题/正文，但
```
--body-file
```
会覆盖正文内容；因此优先使用与工作内容匹配的显式
```
--title
```
参数。
正文：始终使用
```
--body-file
```
参数搭配填充好的模板文件，确保PR遵循仓库的模板规范。

如果用户不希望在磁盘上留下文件，可以使用标准输入：

bash

gh pr create --draft --title "简短标题" --body-file -

然后展示填充后的正文，并告知用户在命令提示时粘贴内容，或者在同一个shell命令中使用here文档（例如

<< 'PRBODY' ... PRBODY

）。

5. Optional: base branch and repo

5. 可选：指定基础分支和仓库

If the PR should target a different base:

bash

gh pr create --draft --base develop --title "..." --body-file .pr-body-draft.md

gh

is not authenticated or repo is missing, remind the user to run

gh auth status

and push the branch first.

如果PR需要合并到不同的基础分支：

bash

gh pr create --draft --base develop --title "..." --body-file .pr-body-draft.md

如果

gh

未认证或仓库不存在，请提醒用户先运行

gh auth status

并推送分支。

Example

示例

User is on branch

PROJ-194-ui-mismatch-in-email-management

admin-dashboard

, with 3 commits. Template has "Summary", "Related Ticket (Closes PROJ-XX)", "How to Test", checklists.

Repo root:

admin-dashboard

, template:

.github/pull_request_template.md

Branch:
```
PROJ-194-ui-mismatch-in-email-management
```
, ticket:
```
PROJ-194
```
, commits: e.g. "feat(PROJ-194): add notification CC modals", "feat(PROJ-194): wire API for notification CC list".
Fill template: Summary as bullet points (e.g. "- Adds notification CC add/edit/delete modals", "- Adds standalone notification CC list section", "- Fixes modal description and avatar styling"); Closes PROJ-194; How to Test from chat or "Settings → Notification CC section".
Write body to
```
admin-dashboard/.pr-body-draft.md
```
.
Output:

bash

cd path/to/repo && gh pr create --draft --title "PROJ-194: UI mismatch in email management" --body-file .pr-body-draft.md

用户位于

admin-dashboard

仓库的

PROJ-194-ui-mismatch-in-email-management

分支，有3条提交记录。模板包含“摘要”、“相关工单（Closes PROJ-XX）”、“测试方法”和检查清单。

仓库根目录：

admin-dashboard

，模板：

.github/pull_request_template.md

。

分支：
```
PROJ-194-ui-mismatch-in-email-management
```
，工单编号：
```
PROJ-194
```
，提交记录例如："feat(PROJ-194): add notification CC modals"，"feat(PROJ-194): wire API for notification CC list"。
填充模板：摘要使用项目符号（例如 "- 添加通知抄送添加/编辑/删除模态框"，"- 添加独立的通知抄送列表区域"，"- 修复模态框描述和头像样式"）；Closes PROJ-194；测试方法来自对话或“设置 → 通知抄送区域”。
将正文写入
```
admin-dashboard/.pr-body-draft.md
```
。
输出命令：

bash

cd path/to/repo && gh pr create --draft --title "PROJ-194: 邮件管理中的UI不匹配问题修复" --body-file .pr-body-draft.md

Summary

总结

Template: Use the repo’s
```
.github/pull_request_template.md
```
(or variant).
Body: Fill it from branch commits + chat; keep section structure. Write the Summary as bullet points, not a paragraph. Remove template instruction/pointer lines in any section you filled; leave placeholders only in sections you did not fill.
Ticket: From branch name (e.g. PROJ-194, CR-123) for Closes/Related ticket.

Command:

gh pr create --draft --title "..." --body-file <path>

(or

--body-file -

and provide body separately).

Multi-repo: Ask which project if unclear; run commands from that repo root.

模板：使用仓库的
```
.github/pull_request_template.md
```
（或其变体）。
正文：结合分支提交记录和对话内容填充；保留章节结构。摘要使用项目符号，而非段落。删除已填充内容章节的模板说明/提示行；仅在未填充内容的章节保留占位符。
工单编号：从分支名称中提取（例如PROJ-194、CR-123），用于“Closes/相关工单”字段。

命令：

gh pr create --draft --title "..." --body-file <路径>

（或使用

--body-file -

并单独提供正文）。

多仓库场景：如果不确定，请询问用户；在选定仓库的根目录下执行命令。