# branch +create

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

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

## 命令

```bash
# 从 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 }
```

**响应示例：**

```json
{
  "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-list.md) — 列出分支
- [branch +delete](branch-delete.md) — 删除分支
- [gitlink-branch](../SKILL.md) — 分支操作总览
- [gitlink-shared](../../gitlink-shared/SKILL.md) — 认证和全局参数
