feat(branch): add lifecycle shortcuts

This commit is contained in:
wangyue789 2026-06-17 10:09:51 +08:00
parent 71ca2bb683
commit 16b9ebefdc
6 changed files with 363 additions and 2 deletions

View File

@ -439,6 +439,10 @@ gitlink-cli pr +review --owner Gitlink --repo forgeplus -i 42 --status approved
```bash
# List branches
gitlink-cli branch +list --owner Gitlink --repo forgeplus
gitlink-cli branch +list --owner Gitlink --repo forgeplus --keyword fix --state deleted
# List all branches without pagination
gitlink-cli branch +all --owner Gitlink --repo forgeplus
# Create a branch
gitlink-cli branch +create --name feature/new-feature
@ -451,6 +455,10 @@ gitlink-cli branch +protect --name main
# Remove branch protection
gitlink-cli branch +unprotect --name main
# Set default branch or restore a deleted branch (preview first)
gitlink-cli branch +set-default --owner Gitlink --repo forgeplus --name main --dry-run
gitlink-cli branch +restore --owner Gitlink --repo forgeplus --id 7 --name feature/old --dry-run
```
### Release Management

View File

@ -444,6 +444,25 @@ gitlink-cli pr +review --owner Gitlink --repo forgeplus -i 42 --status approved
gitlink-cli pr +review --owner Gitlink --repo forgeplus -i 42 --status approved -c "LGTM"
```
### 分支管理
```bash
# 列出分支,支持关键词和删除分支过滤
gitlink-cli branch +list --owner Gitlink --repo forgeplus
gitlink-cli branch +list --owner Gitlink --repo forgeplus --keyword fix --state deleted
# 无分页列出全部分支
gitlink-cli branch +all --owner Gitlink --repo forgeplus
# 创建 / 删除分支
gitlink-cli branch +create --owner Gitlink --repo forgeplus --name feature/new-feature
gitlink-cli branch +delete --owner Gitlink --repo forgeplus --name feature/old-feature
# 设置默认分支或恢复已删除分支(先 dry-run 预览)
gitlink-cli branch +set-default --owner Gitlink --repo forgeplus --name main --dry-run
gitlink-cli branch +restore --owner Gitlink --repo forgeplus --id 7 --name feature/old --dry-run
```
### 发布管理
```bash

View File

@ -0,0 +1,28 @@
# Branch Lifecycle Shortcuts
## Background
GitLink OpenAPI exposes branch lifecycle capabilities that were not fully reachable from `gitlink-cli`: keyword/state branch listing, no-pagination listing, default branch switching, and deleted branch restoration.
## What Changed
Extended the `branch` shortcut group with documented OpenAPI coverage:
- `branch +list --keyword --state` maps to `GET /api/v1/{owner}/{repo}/branches.json` query parameters.
- `branch +all` maps to `GET /api/v1/{owner}/{repo}/branches/all.json`.
- `branch +set-default --name` maps to `PATCH /api/v1/{owner}/{repo}/branches/update_default_branch.json?name=...`.
- `branch +restore --id --name` maps to `POST /api/v1/{owner}/{repo}/branches/restore.json` with `branch_id` and `branch_name`.
Write operations support `--dry-run` so users and Agents can inspect the exact request before changing branch state.
## Validation
```bash
git diff --check
GOPROXY=https://goproxy.cn,direct go test ./shortcuts/branch ./shortcuts
go vet ./shortcuts/branch ./shortcuts
go run . branch +set-default --help
go run . branch +restore --help
GOPROXY=https://goproxy.cn,direct go test ./...
go vet ./...
```

View File

@ -3,6 +3,8 @@ package branch
import (
"fmt"
"net/url"
"strconv"
"strings"
"github.com/gitlink-org/gitlink-cli/internal/i18n"
"github.com/gitlink-org/gitlink-cli/shortcuts/common"
@ -17,6 +19,8 @@ func Shortcuts(translators ...*i18n.Translator) []*common.Shortcut {
Flags: []common.Flag{
{Name: "page", Short: "p", Usage: tr.T("flag.page"), Default: "1"},
{Name: "limit", Short: "l", Usage: tr.T("flag.limit"), Default: "20"},
{Name: "keyword", Short: "k", Usage: "Filter branches by keyword"},
{Name: "state", Short: "s", Usage: "Branch state: all, deleted, or empty for active branches"},
},
Run: func(ctx *common.RuntimeContext) error {
if err := ctx.ResolveOwnerRepo(); err != nil {
@ -25,6 +29,15 @@ func Shortcuts(translators ...*i18n.Translator) []*common.Shortcut {
q := url.Values{}
q.Set("page", ctx.Arg("page"))
q.Set("limit", ctx.Arg("limit"))
if keyword := strings.TrimSpace(ctx.Arg("keyword")); keyword != "" {
q.Set("keyword", keyword)
}
if state := strings.TrimSpace(ctx.Arg("state")); state != "" {
if err := validateBranchState(state); err != nil {
return err
}
q.Set("state", state)
}
env, err := ctx.CallAPIWithQuery("GET", "/v1"+ctx.RepoPath()+"/branches", q)
if err != nil {
return err
@ -32,6 +45,20 @@ func Shortcuts(translators ...*i18n.Translator) []*common.Shortcut {
return ctx.Output(env)
},
},
{
Name: "all",
Description: "List all branches without pagination",
Run: func(ctx *common.RuntimeContext) error {
if err := ctx.ResolveOwnerRepo(); err != nil {
return err
}
env, err := ctx.CallAPI("GET", "/v1"+ctx.RepoPath()+"/branches/all", nil)
if err != nil {
return err
}
return ctx.Output(env)
},
},
{
Name: "create",
Description: tr.T("cmd.branch.create.short"),
@ -119,6 +146,25 @@ func Shortcuts(translators ...*i18n.Translator) []*common.Shortcut {
return ctx.Output(env)
},
},
{
Name: "set-default",
Description: "Set repository default branch",
Flags: []common.Flag{
{Name: "name", Short: "n", Usage: tr.T("flag.branch.name"), Required: true},
{Name: "dry-run", Usage: "Preview the request without changing the default branch", Bool: true, Default: "false"},
},
Run: runSetDefault,
},
{
Name: "restore",
Description: "Restore a deleted branch",
Flags: []common.Flag{
{Name: "id", Short: "i", Usage: "Deleted branch ID", Required: true},
{Name: "name", Short: "n", Usage: tr.T("flag.branch.name"), Required: true},
{Name: "dry-run", Usage: "Preview the request without restoring the branch", Bool: true, Default: "false"},
},
Run: runRestore,
},
}
}
@ -128,3 +174,81 @@ func shortcutTranslator(translators ...*i18n.Translator) *i18n.Translator {
}
return i18n.Default()
}
func runSetDefault(ctx *common.RuntimeContext) error {
if err := ctx.ResolveOwnerRepo(); err != nil {
return err
}
name, err := ctx.RequireArg("name")
if err != nil {
return err
}
path := "/v1" + ctx.RepoPath() + "/branches/update_default_branch"
query := url.Values{}
query.Set("name", name)
if ctx.Arg("dry-run") == "true" {
return ctx.OutputData(map[string]interface{}{
"dry_run": true,
"action": "set_default_branch",
"method": "PATCH",
"path": path,
"query": query.Encode(),
})
}
env, err := ctx.CallAPIWithQuery("PATCH", path, query)
if err != nil {
return err
}
return ctx.Output(env)
}
func runRestore(ctx *common.RuntimeContext) error {
if err := ctx.ResolveOwnerRepo(); err != nil {
return err
}
id, err := parsePositiveInt(ctx.Arg("id"), "id")
if err != nil {
return err
}
name, err := ctx.RequireArg("name")
if err != nil {
return err
}
path := "/v1" + ctx.RepoPath() + "/branches/restore"
body := map[string]interface{}{
"branch_id": id,
"branch_name": name,
}
if ctx.Arg("dry-run") == "true" {
return ctx.OutputData(map[string]interface{}{
"dry_run": true,
"action": "restore_branch",
"method": "POST",
"path": path,
"body": body,
})
}
env, err := ctx.CallAPI("POST", path, body)
if err != nil {
return err
}
return ctx.Output(env)
}
func validateBranchState(state string) error {
switch state {
case "all", "deleted":
return nil
default:
return fmt.Errorf("invalid --state %q: use all or deleted", state)
}
}
func parsePositiveInt(value, name string) (int64, error) {
value = strings.TrimSpace(value)
parsed, err := strconv.ParseInt(value, 10, 64)
if err != nil || parsed <= 0 {
return 0, fmt.Errorf("invalid --%s %q: use a positive integer", name, value)
}
return parsed, nil
}

View File

@ -60,6 +60,56 @@ func TestBranchList(t *testing.T) {
}
}
func TestBranchListFilters(t *testing.T) {
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path != "/v1/owner/repo/branches.json" {
t.Fatalf("unexpected path: %s", r.URL.Path)
}
if got := r.URL.Query().Get("keyword"); got != "feature" {
t.Fatalf("keyword = %q, want feature", got)
}
if got := r.URL.Query().Get("state"); got != "deleted" {
t.Fatalf("state = %q, want deleted", got)
}
writeJSON(w, map[string]interface{}{"total_count": 0, "branches": []interface{}{}})
}))
defer server.Close()
err := runShortcut(t, server, "list", map[string]string{
"page": "1", "limit": "20", "keyword": "feature", "state": "deleted",
})
if err != nil {
t.Fatalf("list with filters failed: %v", err)
}
}
func TestBranchListRejectsInvalidState(t *testing.T) {
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
t.Fatalf("invalid state should not call API, got %s %s", r.Method, r.URL.Path)
}))
defer server.Close()
err := runShortcut(t, server, "list", map[string]string{"page": "1", "limit": "20", "state": "open"})
if err == nil {
t.Fatal("expected validation error")
}
}
func TestBranchAll(t *testing.T) {
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.Method != "GET" || r.URL.Path != "/v1/owner/repo/branches/all.json" {
t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path)
}
writeJSON(w, []interface{}{map[string]interface{}{"name": "master"}})
}))
defer server.Close()
err := runShortcut(t, server, "all", nil)
if err != nil {
t.Fatalf("all failed: %v", err)
}
}
// --- create ---
func TestBranchCreate(t *testing.T) {
@ -150,6 +200,69 @@ func TestBranchUnprotect(t *testing.T) {
}
}
func TestBranchSetDefault(t *testing.T) {
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.Method != "PATCH" || r.URL.Path != "/v1/owner/repo/branches/update_default_branch.json" {
t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path)
}
if got := r.URL.Query().Get("name"); got != "main" {
t.Fatalf("name query = %q, want main", got)
}
writeJSON(w, map[string]interface{}{"status": 0, "message": "success"})
}))
defer server.Close()
if err := runShortcut(t, server, "set-default", map[string]string{"name": "main"}); err != nil {
t.Fatalf("set-default failed: %v", err)
}
}
func TestBranchSetDefaultDryRunDoesNotCallAPI(t *testing.T) {
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
t.Fatalf("dry-run should not call API, got %s %s", r.Method, r.URL.Path)
}))
defer server.Close()
if err := runShortcut(t, server, "set-default", map[string]string{"name": "main", "dry-run": "true"}); err != nil {
t.Fatalf("set-default dry-run failed: %v", err)
}
}
func TestBranchRestore(t *testing.T) {
var payload map[string]interface{}
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.Method != "POST" || r.URL.Path != "/v1/owner/repo/branches/restore.json" {
t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path)
}
if err := json.NewDecoder(r.Body).Decode(&payload); err != nil {
t.Fatalf("decode body: %v", err)
}
writeJSON(w, map[string]interface{}{"status": 0, "message": "success"})
}))
defer server.Close()
if err := runShortcut(t, server, "restore", map[string]string{"id": "7", "name": "feature/deleted"}); err != nil {
t.Fatalf("restore failed: %v", err)
}
if payload["branch_id"] != float64(7) {
t.Fatalf("branch_id = %v, want 7", payload["branch_id"])
}
if payload["branch_name"] != "feature/deleted" {
t.Fatalf("branch_name = %v, want feature/deleted", payload["branch_name"])
}
}
func TestBranchRestoreValidation(t *testing.T) {
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
t.Fatalf("invalid restore should not call API, got %s %s", r.Method, r.URL.Path)
}))
defer server.Close()
if err := runShortcut(t, server, "restore", map[string]string{"id": "0", "name": "feature/deleted"}); err == nil {
t.Fatal("expected invalid id error")
}
}
// --- HTTP error paths ---
func TestBranchListHTTPError(t *testing.T) {

View File

@ -1,7 +1,7 @@
---
name: gitlink-branch
version: 1.0.0
description: "分支管理:创建、查看、删除、保护分支。当用户需要操作 GitLink 分支时触发。"
version: 1.1.0
description: "分支管理:创建、查看、过滤、删除、保护、设置默认分支、恢复已删除分支。当用户需要操作 GitLink 分支时触发。"
metadata:
requires:
bins: ["gitlink-cli"]
@ -21,10 +21,13 @@ metadata:
| Shortcut | 说明 | 操作类型 |
|----------|------|----------|
| `branch +list` | 列出仓库的所有分支 | Read |
| `branch +all` | 无分页列出仓库所有分支 | Read |
| `branch +create` | 创建新分支 | ⚠️ Write Operation |
| `branch +delete` | 删除分支 | 🔴 Destructive Operation |
| `branch +protect` | 设置分支保护规则 | ⚠️ Write Operation |
| `branch +unprotect` | 移除分支保护规则 | ⚠️ Write Operation |
| `branch +set-default` | 设置默认分支 | ⚠️ Write Operation |
| `branch +restore` | 恢复已删除分支 | ⚠️ Write Operation |
## 参数参考
@ -36,6 +39,17 @@ metadata:
| `--repo` | 是* | 仓库名称(可从 git remote 自动推断) |
| `--page, -p` | 否 | 页码(默认 `1` |
| `--limit, -l` | 否 | 每页条数(默认 `20` |
| `--keyword, -k` | 否 | 分支关键词过滤 |
| `--state, -s` | 否 | 分支状态:`all` 或 `deleted` |
| `--format` | 否 | 输出格式:`json`/`table`/`yaml` |
| `--debug` | 否 | 启用调试输出 |
### branch +all
| 参数 | 必填 | 说明 |
|------|------|------|
| `--owner` | 是* | 仓库所有者(可从 git remote 自动推断) |
| `--repo` | 是* | 仓库名称(可从 git remote 自动推断) |
| `--format` | 否 | 输出格式:`json`/`table`/`yaml` |
| `--debug` | 否 | 启用调试输出 |
@ -80,6 +94,29 @@ metadata:
| `--format` | 否 | 输出格式:`json`/`table`/`yaml` |
| `--debug` | 否 | 启用调试输出 |
### branch +set-default
| 参数 | 必填 | 说明 |
|------|------|------|
| `--name, -n` | 是 | 要设为默认分支的名称 |
| `--dry-run` | 否 | 预览请求,不修改默认分支 |
| `--owner` | 是* | 仓库所有者(可从 git remote 自动推断) |
| `--repo` | 是* | 仓库名称(可从 git remote 自动推断) |
| `--format` | 否 | 输出格式:`json`/`table`/`yaml` |
| `--debug` | 否 | 启用调试输出 |
### branch +restore
| 参数 | 必填 | 说明 |
|------|------|------|
| `--id, -i` | 是 | 已删除分支的 branch_id |
| `--name, -n` | 是 | 要恢复的分支名称 |
| `--dry-run` | 否 | 预览请求,不恢复分支 |
| `--owner` | 是* | 仓库所有者(可从 git remote 自动推断) |
| `--repo` | 是* | 仓库名称(可从 git remote 自动推断) |
| `--format` | 否 | 输出格式:`json`/`table`/`yaml` |
| `--debug` | 否 | 启用调试输出 |
> *如果在 GitLink 仓库目录下执行,`--owner` 和 `--repo` 可自动推断。
## 使用示例
@ -91,6 +128,12 @@ gitlink-cli branch +list
# 指定仓库并分页
gitlink-cli branch +list --owner Gitlink --repo forgeplus --page 1 --limit 10
# 搜索分支或查看已删除分支
gitlink-cli branch +list --owner Gitlink --repo forgeplus --keyword fix --state deleted
# 无分页列出所有分支
gitlink-cli branch +all --owner Gitlink --repo forgeplus
# 输出为 JSON
gitlink-cli branch +list --format json
@ -117,6 +160,14 @@ gitlink-cli branch +protect --name main --owner someone --repo myrepo
# 移除分支保护(仅简单分支名,含 / 的路径需通过 Web 操作)
gitlink-cli branch +unprotect --name main
# 设置默认分支(先 dry-run 预览)
gitlink-cli branch +set-default --name main --dry-run
gitlink-cli branch +set-default --name main
# 恢复已删除分支(先 dry-run 预览)
gitlink-cli branch +restore --id 7 --name feature/old --dry-run
gitlink-cli branch +restore --id 7 --name feature/old
```
## Workflow 注意事项
@ -157,6 +208,24 @@ gitlink-cli branch +unprotect --name main
2. 执行 `branch +unprotect --name <name>`
3. 输出结果。
### branch +set-defaultWrite Operation
> [!CAUTION]
> This is a **Write Operation** — confirm user intent.
1. 确认用户希望切换默认分支。
2. 先执行 `branch +set-default --name <name> --dry-run` 预览。
3. 用户确认后执行不带 `--dry-run` 的命令。
### branch +restoreWrite Operation
> [!CAUTION]
> This is a **Write Operation** — confirm user intent.
1. 通过 `branch +list --state deleted` 确认 `branch_id` 和分支名。
2. 先执行 `branch +restore --id <branch_id> --name <name> --dry-run` 预览。
3. 用户确认后执行不带 `--dry-run` 的命令。
> **注意:**`/` 的分支名(如 `feature/my-branch`)可能无法通过 CLI 解除保护(受限于 API 路由),需通过 Web 页面操作。
## References