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

branch +create

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

从现有分支或 commit 创建新分支。

命令

# 从 master 创建分支
gitlink-cli branch +create --name feature/new-feature

# 从指定分支创建
gitlink-cli branch +create --name hotfix/bug-123 --from develop

# 从指定 commit 创建
gitlink-cli branch +create --name feature/x --from abc123def

# 指定仓库创建分支
gitlink-cli branch +create --name feature/x --owner someone --repo myrepo

参数

参数	必填	说明
--name, -n	是	新分支名称
--from, -f	否	源分支或 commit（默认 master）
--owner	否*	仓库所有者（自动从 git remote 解析）
--repo	否*	仓库名称（自动从 git remote 解析）
--format	否	输出格式: json/table/yaml
--debug	否	启用调试输出

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

API

POST /v1/{owner}/{repo}/branches
Body: { "new_branch_name": name, "old_branch_name": from }

响应示例：

{
  "ok": true,
  "data": {
    "name": "feature/new-feature",
    "commit_id": "abc123...",
    "commit_message": "Create feature branch",
    "committed_time": "2026-01-01T00:00:00Z"
  }
}

Workflow

1. Confirm the branch name and source branch with the user.
2. Execute gitlink-cli branch +create --name <name> --from <source>.
3. Report the created branch information.

[!CAUTION] This is a Write Operation — confirm user intent before executing.

Use Cases

• 功能开发：为新功能创建独立分支
• Bug 修复：从稳定分支创建 hotfix 分支
• 实验性功能：创建实验分支进行尝试
• 版本发布：为发布版本创建分支

Best Practices

• 命名规范：使用有意义的分支名，如 feature/xxx、hotfix/xxx、release/xxx
• 源分支选择：通常从 develop 或 master 创建功能分支
• 分支描述：创建后可以添加描述说明分支用途

Error Handling

常见错误及解决方案：

错误	原因	解决方案
404	仓库不存在	检查 --owner 和 --repo 是否正确
409	分支已存在	使用不同的分支名或删除现有分支
404	源分支不存在	确认 --from 指定的分支或 commit 存在

Tips

• 默认从 master 分支创建，如需从其他分支创建需明确指定
• 分支名支持 / 分隔符，便于组织分支结构
• 创建后可以立即使用 gitlink-cli branch +list 验证

References

• branch +list — 列出分支
• branch +delete — 删除分支
• gitlink-branch — 分支操作总览
• gitlink-shared — 认证和全局参数