forked from Gitlink/gitlink-cli
175 lines
7.1 KiB
Markdown
175 lines
7.1 KiB
Markdown
---
|
||
name: gitlink-pr
|
||
version: 1.0.0
|
||
description: "Pull Request 管理：创建、查看、合并、关闭 PR，查看变更文件、Diff 和 patchset/version。当用户需要操作 GitLink PR 时触发。"
|
||
metadata:
|
||
requires:
|
||
bins: ["gitlink-cli"]
|
||
cliHelp: "gitlink-cli pr --help"
|
||
---
|
||
|
||
# gitlink-pr（Pull Request 操作）
|
||
|
||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
|
||
**CRITICAL — 所有 Shortcuts 在执行写入/删除操作前，务必先确认用户意图。**
|
||
|
||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。
|
||
|
||
## Shortcuts
|
||
|
||
| Shortcut | 说明 | 需要认证 |
|
||
|----------|------|----------|
|
||
| `pr +list` | PR 列表 | 否（公开项目） |
|
||
| `pr +create` | 创建 PR | 是 |
|
||
| `pr +view` | PR 详情 | 否（公开项目） |
|
||
| `pr +merge` | 合并 PR | 是 |
|
||
| `pr +refuse` | 拒绝并关闭 PR | 是 |
|
||
| `pr +reopen` | 重开已关闭的 PR | 是 |
|
||
| `pr +files` | 变更文件列表 | 否 |
|
||
| `pr +diff` | 查看变更文件和 diff 内容 | 否 |
|
||
| `pr +versions` | 查看 PR patchset/version 列表 | 否 |
|
||
| `pr +version-diff` | 查看指定 patchset/version diff | 否 |
|
||
| `pr +reviews` | 查看 PR 审查记录，支持状态过滤 | 否 |
|
||
| `pr +review` | 创建 PR 审查（支持 dry-run 预览） | 是 |
|
||
| `pr +comment` | 给 PR 添加评论 | 是 |
|
||
|
||
## 使用示例
|
||
|
||
```bash
|
||
# 列出 PR
|
||
gitlink-cli pr +list --owner Gitlink --repo forgeplus --state open
|
||
|
||
# 搜索并排序 PR
|
||
gitlink-cli pr +list --owner Gitlink --repo forgeplus --state merged --keyword release --sort-by updated_at --sort-direction desc
|
||
|
||
# 创建 PR（源分支必须有实际代码变更）
|
||
gitlink-cli pr +create --title "feat: 新增搜索功能" --head feature/search --base master --body "实现了全文搜索"
|
||
|
||
# 查看 PR 详情（使用 pull_request_number，即网页 URL 中的序号）
|
||
gitlink-cli pr +view --id 3
|
||
|
||
# 合并 PR（支持 merge/rebase/squash）
|
||
gitlink-cli pr +merge --id 3
|
||
gitlink-cli pr +merge --id 3 --method squash
|
||
|
||
# 拒绝 PR（拒绝合并并关闭）
|
||
gitlink-cli pr +refuse --id 3
|
||
|
||
# 重开已关闭的 PR
|
||
gitlink-cli pr +reopen --id 3
|
||
|
||
# 查看变更文件（含 diff 内容）
|
||
gitlink-cli pr +files --id 3
|
||
|
||
# 查看 PR patchset/version 列表
|
||
gitlink-cli pr +versions --id 3
|
||
|
||
# 查看指定 patchset/version diff
|
||
gitlink-cli pr +version-diff --id 3 --version-id 16040
|
||
gitlink-cli pr +version-diff --id 3 --version-id 16040 --file shortcuts/pr/pr.go
|
||
|
||
# 查看 PR 审查记录（支持按状态过滤）
|
||
gitlink-cli pr +reviews --id 3
|
||
gitlink-cli pr +reviews --id 3 --status approved
|
||
|
||
# 创建 PR 审查（common/approved/rejected，支持 --dry-run 预览）
|
||
gitlink-cli pr +review --id 3 --status approved --content "LGTM, ready to merge"
|
||
gitlink-cli pr +review --id 3 --status approved --content "LGTM" --dry-run
|
||
|
||
# 给 PR 添加评论
|
||
gitlink-cli pr +comment --id 3 --body "LGTM, ready to merge"
|
||
```
|
||
|
||
## 创建 PR 的完整流程
|
||
|
||
### 向他人仓库提 PR（Fork 流程，必须遵守）
|
||
|
||
```bash
|
||
# 1. Fork 目标仓库
|
||
gitlink-cli repo +fork --owner TargetOrg --repo target-repo
|
||
|
||
# 2. Clone 自己的 Fork
|
||
git clone https://www.gitlink.org.cn/MyUser/target-repo.git
|
||
cd target-repo
|
||
git remote add upstream https://www.gitlink.org.cn/TargetOrg/target-repo.git
|
||
|
||
# 3. 创建分支、修改、提交
|
||
git checkout -b fix/my-change
|
||
# ... 修改文件 ...
|
||
git add -A && git commit -m "fix: my change"
|
||
|
||
# 4. Push 到自己的 Fork（不是 upstream）
|
||
git push origin fix/my-change
|
||
|
||
# 5. 从 Fork 向主仓库提 PR
|
||
gitlink-cli pr +create --owner TargetOrg --repo target-repo \
|
||
--head MyUser:fix/my-change --base master \
|
||
--title "fix: my change"
|
||
```
|
||
|
||
> ⛔ **禁止直接往主仓库推分支再提 PR，即使有 admin 权限也不行。除非用户明确要求「直接 push」。**
|
||
|
||
### 在自己仓库直接提 PR（仅限用户明确要求时）
|
||
|
||
```bash
|
||
# 1. 创建分支
|
||
gitlink-cli branch +create --name feature-branch --from master
|
||
|
||
# 2. 在分支上创建/修改文件（content 必须 base64 编码）
|
||
gitlink-cli api POST /:owner/:repo/create_file --body '{
|
||
"filepath": "new-file.md",
|
||
"content": "<base64编码的内容>",
|
||
"branch": "feature-branch",
|
||
"message": "add new file"
|
||
}'
|
||
|
||
# 3. 创建 PR
|
||
gitlink-cli pr +create --title "feat: 新功能" --head feature-branch --base master
|
||
```
|
||
|
||
## Raw API 补充
|
||
|
||
```bash
|
||
# 创建文件（content 必须 base64 编码）
|
||
gitlink-cli api POST /:owner/:repo/create_file --body '{"filepath":"file.md","content":"<base64>","branch":"dev","message":"add file"}'
|
||
|
||
# 更新文件（需要先通过 sub_entries 获取文件 SHA）
|
||
gitlink-cli api GET /:owner/:repo/sub_entries --query 'filepath=file.md&ref=dev'
|
||
# 从 entries.sha 获取 SHA，然后：
|
||
gitlink-cli api PUT /:owner/:repo/update_file --body '{"filepath":"file.md","content":"<base64>","sha":"<sha>","branch":"dev","message":"update file"}'
|
||
|
||
# 检查是否可合并
|
||
gitlink-cli api POST /:owner/:repo/pulls/check_can_merge --body '{"head":"dev","base":"main"}'
|
||
|
||
# 创建 Review
|
||
gitlink-cli api POST /v1/:owner/:repo/pulls/:id/reviews --body '{"content":"LGTM","status":"approved"}'
|
||
|
||
# 查看 Review 列表（支持 status 过滤）
|
||
gitlink-cli api GET /v1/:owner/:repo/pulls/:id/reviews
|
||
gitlink-cli api GET /v1/:owner/:repo/pulls/:id/reviews?status=approved
|
||
|
||
# 获取可用分支
|
||
gitlink-cli api GET /:owner/:repo/pulls/get_branches
|
||
|
||
# 查看 PR patchset/version 列表（v1 API）
|
||
gitlink-cli api GET /v1/:owner/:repo/pulls/:id/versions
|
||
|
||
# 查看指定 patchset/version diff（可通过 filepath 过滤文件）
|
||
gitlink-cli api GET /v1/:owner/:repo/pulls/:id/versions/:version_id/diff
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
- ⛔ **GitLink 的 PR 操作必须用 `gitlink-cli pr`，不能用 `gh pr`。** `gh` 是 GitHub CLI，无法操作 GitLink 平台。详见 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 的「工具使用边界」章节。
|
||
- GitLink 的默认分支通常是 `master`（非 `main`），创建 PR 时注意 `--base` 参数
|
||
- 合并 PR 前建议先用 `pr +view` 确认状态
|
||
- **PR 创建要求源分支与目标分支有实际代码差异**，否则返回"分支内容相同，无需创建合并请求"
|
||
- PR 查看/合并/关闭/重开需要使用 `pull_request_number`（即网页 URL `/pulls/N` 中的序号，从 `pr +list` 返回）
|
||
- `pr +merge` 默认使用 merge 方式，可通过 `--method` 指定 rebase 或 squash
|
||
- `pr +diff` 实际调用 `/pulls/:id/files` 端点，返回变更文件列表和 diff 内容
|
||
- `pr +versions` / `pr +version-diff` 使用 v1 API，`--id` 为网页 URL `/pulls/N` 中的 PR 序号，`--version-id` 为 patchset/version id
|
||
- 同一个 PR 分支继续 push 新 commit 会生成新的 patchset/version；正常根据 review 修改代码时，应优先在原 PR 分支继续 push，不要关闭 PR 重开
|
||
- `pr +list` 的 `--state` 参数会映射为 GitLink API 的 `status` 筛选；需要查看所有 PR 时传 `--state all`
|
||
- PR 状态值：`pull_request_status` 0=open, 1=merged, 2=closed
|
||
- 关联已有 Issue 时，把 Issue 编号或 URL 写入 PR `--body`，或使用 `issue +comment` 留痕；不要用 Raw API 对 Issue 做不完整更新，否则可能清空 Issue 描述
|