# branch +list

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

列出仓库的所有分支，支持分页查询。

## 命令

```bash
# 列出当前仓库的分支
gitlink-cli branch +list

# 指定仓库并分页
gitlink-cli branch +list --owner Gitlink --repo forgeplus --page 1 --limit 10

# 输出为 JSON
gitlink-cli branch +list --format json

# 输出为 YAML
gitlink-cli branch +list --format yaml
```

## 参数

| 参数 | 必填 | 说明 |
|------|------|------|
| `--owner` | 否* | 仓库所有者（自动从 git remote 解析） |
| `--repo` | 否* | 仓库名称（自动从 git remote 解析） |
| `--page, -p` | 否 | 页码（默认 `1`） |
| `--limit, -l` | 否 | 每页条数（默认 `20`） |
| `--format` | 否 | 输出格式: `json`/`table`/`yaml` |
| `--debug` | 否 | 启用调试输出 |

> *如果在 GitLink 仓库目录下执行，`--owner` 和 `--repo` 可自动推断。

## API

```
GET /v1/{owner}/{repo}/branches?page=1&limit=20
```

**响应示例：**

```json
{
  "ok": true,
  "data": {
    "branches": [
      {
        "name": "master",
        "commit_id": "abc123...",
        "commit_message": "Initial commit",
        "committed_time": "2026-01-01T00:00:00Z",
        "is_default": true,
        "protected": false
      },
      {
        "name": "develop",
        "commit_id": "def456...",
        "commit_message": "Develop branch",
        "committed_time": "2026-01-02T00:00:00Z",
        "is_default": false,
        "protected": true
      }
    ],
    "total_count": 15
  },
  "meta": {
    "page": 1,
    "limit": 20,
    "total_count": 15
  }
}
```

## Workflow

1. **Resolve** owner and repo (from git remote or flags).
2. **Execute** `gitlink-cli branch +list`.
3. **Display** branches in the requested format.

> [!NOTE]
> This is a **Read Operation** — no confirmation needed.

## Use Cases

- **查看可用分支**：在创建 PR 前查看所有分支
- **检查分支保护状态**：查看哪些分支被保护
- **分支浏览**：探索仓库的分支结构
- **自动化脚本**：结合 JSON 格式输出进行批量操作

## Tips

- 使用 `--format json` 可以更好地解析分支信息
- 分支列表包含保护状态，可以快速识别受保护的分支
- 支持分页，适合分支较多的仓库

## References

- [branch +create](branch-create.md) — 创建分支
- [branch +protect](branch-protect.md) — 保护分支
- [gitlink-branch](../SKILL.md) — 分支操作总览
- [gitlink-shared](../../gitlink-shared/SKILL.md) — 认证和全局参数
