gitlink-cli/skills/gitlink-branch/references/branch-list.md

branch +list

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

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

命令

# 列出当前仓库的分支
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

响应示例：

{
  "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 +protect — 保护分支
• gitlink-branch — 分支操作总览
• gitlink-shared — 认证和全局参数