# pr +create

> **前置条件：** 先阅读 [`../../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。

创建一个 Pull Request。源分支必须与目标分支存在实际代码差异。

## 命令

```bash
# 基本创建
gitlink-cli pr +create --title "feat: 新增搜索功能" --head feature/search --base master

# 附带描述
gitlink-cli pr +create -t "fix: 修复登录问题" --head bugfix/login --base master -b "修复了 Token 过期后的重定向问题"

# 指定仓库
gitlink-cli pr +create --owner myorg --repo myrepo --title "docs: 更新 README" --head docs-update --base master
```

## 参数

| 参数 | 必填 | 说明 |
|------|------|------|
| `--title` / `-t` | 是 | PR 标题 |
| `--head` | 是 | 源分支（包含变更的分支） |
| `--base` | 否 | 目标分支（默认 `master`） |
| `--body` / `-b` | 否 | PR 描述 |

## API

```
POST /{owner}/{repo}/pulls
Body: { "title": "...", "head": "...", "base": "...", "body": "..." }
```

## Workflow

> [!CAUTION]
> This is a **Write Operation** -- confirm user intent before executing.

创建 PR 的完整流程（从零开始）：

### Step 1: 创建分支

```bash
gitlink-cli branch +create --name feature-branch --from master
```

### Step 2: 在分支上创建文件（content 必须 base64 编码）

```bash
# 生成 base64 内容
CONTENT=$(echo -n "文件内容" | base64)

# 通过 Raw API 创建文件
gitlink-cli api POST /:owner/:repo/create_file --body '{
  "filepath": "path/to/new-file.md",
  "content": "'$CONTENT'",
  "branch": "feature-branch",
  "message": "add new file"
}'
```

### Step 3: 创建 PR

```bash
gitlink-cli pr +create --title "feat: 新功能" --head feature-branch --base master --body "添加了新文件"
```

### 更新已有文件的流程

如需修改已有文件而非创建新文件：

```bash
# Step 2a: 获取文件 SHA
gitlink-cli api GET /:owner/:repo/sub_entries --query 'filepath=path/to/file.md&ref=feature-branch'
# 从返回的 entries.sha 获取 SHA 值

# Step 2b: 更新文件（content 必须 base64 编码）
CONTENT=$(echo -n "更新后的内容" | base64)
gitlink-cli api PUT /:owner/:repo/update_file --body '{
  "filepath": "path/to/file.md",
  "content": "'$CONTENT'",
  "sha": "<从 sub_entries 获取的 sha>",
  "branch": "feature-branch",
  "message": "update file"
}'
```

## 注意事项

- **源分支与目标分支必须有实际代码差异**，否则 API 返回 "分支内容相同，无需创建合并请求"
- GitLink 默认主分支为 `master`（非 `main`），`--base` 默认值为 `master`
- `create_file` 的 `content` 字段**必须 base64 编码**，不编码会返回 "文件已存在" 错误
- 创建成功后返回的 `pull_request_number` 用于后续 view/merge/close 操作
- 关联已有 Issue 时，把 Issue 编号或 URL 写入 PR `--body`，或用 `issue +comment` 在 Issue 下补充 PR 链接；不要为了关联 PR 直接用 Raw API 更新 Issue 描述

## References

- [gitlink-shared SKILL.md](../../gitlink-shared/SKILL.md) -- 认证与全局参数、文件操作 API
- [gitlink-pr SKILL.md](../SKILL.md) -- PR 操作总览