# branch +delete

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

删除指定的分支。**此操作不可逆，请谨慎使用。**

## 命令

```bash
# 删除分支
gitlink-cli branch +delete --name feature/old-feature

# 指定仓库删除分支
gitlink-cli branch +delete --name feature/old-feature --owner someone --repo myrepo

# 删除带路径的分支
gitlink-cli branch +delete --name feature/my-feature
```

## 参数

| 参数 | 必填 | 说明 |
|------|------|------|
| `--name, -n` | **是** | 要删除的分支名称 |
| `--owner` | 否* | 仓库所有者（自动从 git remote 解析） |
| `--repo` | 否* | 仓库名称（自动从 git remote 解析） |
| `--format` | 否 | 输出格式: `json`/`table`/`yaml` |
| `--debug` | 否 | 启用调试输出 |

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

## API

```
POST /v1/{owner}/{repo}/branches/delete
Body: { "branch_name": name }
```

**响应示例：**

```json
{
  "ok": true,
  "data": {
    "message": "Branch deleted successfully",
    "branch_name": "feature/old-feature"
  }
}
```

## Workflow

1. **Confirm** the user really wants to delete this branch (emphasize this is **irreversible**).
2. **Check** if the branch exists using `branch +list` if needed.
3. **Execute** `gitlink-cli branch +delete --name <name>`.
4. **Report** the deletion result.

> [!CAUTION]
> This is a **Destructive Operation** — confirm user intent before executing. This action **cannot be undone**.

## Use Cases

- **清理已完成的功能分支**：功能合并后删除功能分支
- **清理错误的分支**：删除创建错误或不再需要的分支
- **维护分支整洁**：定期清理无用分支保持仓库整洁

## Warnings

- ⚠️ **不可逆操作**：删除分支后无法恢复
- ⚠️ **受保护分支**：无法删除受保护的分支
- ⚠️ **默认分支**：无法删除默认分支（通常是 master）
- ⚠️ **未合并更改**：删除包含未合并更改的分支可能导致代码丢失

## Best Practices

1. **确认合并状态**：删除前确认分支的更改已经合并
2. **备份重要更改**：如果有重要更改未合并，先备份或合并
3. **沟通确认**：团队协作时先沟通确认再删除
4. **使用描述性名称**：避免删除错误的分支

## Error Handling

常见错误及解决方案：

| 错误 | 原因 | 解决方案 |
|------|------|----------|
| `404` | 分支不存在 | 使用 `branch +list` 确认分支存在 |
| `403` | 权限不足 | 确认有删除分支的权限 |
| `400` | 受保护分支 | 无法删除受保护的分支 |
| `400` | 默认分支 | 无法删除默认分支 |

## Safety Checks

建议在删除前执行以下检查：

```bash
# 1. 检查分支是否存在
gitlink-cli branch +list | grep branch-name

# 2. 确认不是保护分支
gitlink-cli branch +list --format json | jq '.data.branches[] | select(.name=="branch-name") | .protected'

# 3. 确认不是默认分支
gitlink-cli api GET /{owner}/{repo} | jq '.data.default_branch'
```

## Tips

- 删除前建议使用 `gitlink-cli branch +list` 确认分支名称
- 对于重要分支，建议先检查是否有未合并的 PR
- 团队协作时，删除公共分支前先通知团队成员

## References

- [branch +list](branch-list.md) — 列出分支
- [branch +create](branch-create.md) — 创建分支
- [branch +protect](branch-protect.md) — 保护分支
- [gitlink-branch](../SKILL.md) — 分支操作总览
- [gitlink-shared](../../gitlink-shared/SKILL.md) — 认证和全局参数
