gitlink-cli/skills/gitlink-branch/REFERENCE.md

gitlink-branch 参考手册

本文档定义分支管理命令的参数说明、API 字段映射和注意事项。

---

一、命令参考

branch +list

列出仓库所有分支。

gitlink-cli branch +list --owner <owner> --repo <repo> --format json

返回字段：

字段	说明
name	分支名称
protected	是否受保护（true/false）

实测返回（chroe/gitlink-cli）：

master, test/pr-workflow-demo, pr/showcase-dashboard, pr/shortcuts-modules,
fix/showcase-member-v2, fix/showcase-member-org, fix/batch-invite-userid,
feat/task-a-shortcuts, fix/windows-npm-install
共 9 个分支

branch +create

从指定分支或 commit 创建新分支。

gitlink-cli branch +create --owner <owner> --repo <repo> \
  --name <新分支名> --from <源分支> --format json

参数	必填	说明
--name, -n	是	新分支名称
--from, -f	否	源分支或 commit（默认 master）

API：

POST /v1/{owner}/{repo}/branches.json
Body: { "branch_name": name, "ref": from }

branch +delete

删除指定分支。

gitlink-cli branch +delete --owner <owner> --repo <repo> \
  --name <分支名> --format json

参数	必填	说明
--name, -n	是	要删除的分支名称

⚠️ 写入操作 — 删除分支不可恢复，执行前确认用户意图。不能删除默认分支。

branch +protect

设置分支保护。

gitlink-cli branch +protect --owner <owner> --repo <repo> \
  --name <分支名> --format json

参数	必填	说明
--name, -n	是	要保护的分支名称

⚠️ 受保护的分支不允许直接 push 和强制推送。

---

二、分支命名约定

前缀	用途	示例
feat/	新功能	feat/task-a-shortcuts
fix/	Bug 修复	fix/showcase-member-v2
pr/	PR 相关	pr/showcase-dashboard
test/	测试	test/pr-workflow-demo

---

三、常见问题

Q: branch +list 返回的分支数量很多怎么办？

A: 正常现象，开发过程中会积累功能分支。定期清理已合并的分支。

Q: 能删除 master 分支吗？

A: 不能。GitLink 不允许删除默认分支。

Q: branch +protect 和仓库设置里的保护有什么区别？

A: 效果相同，CLI 命令是仓库设置的快捷方式。