# branch +protect

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

设置分支保护规则，防止重要分支被意外修改或删除。

## 命令

```bash
# 保护分支
gitlink-cli branch +protect --name main

# 保护 master 分支
gitlink-cli branch +protect --name master

# 指定仓库保护分支
gitlink-cli branch +protect --name main --owner someone --repo myrepo

# 保护开发分支
gitlink-cli branch +protect --name develop
```

## 参数

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

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

## API

```
POST /{owner}/{repo}/protected_branches
Body: { "branch_name": name }
```

**响应示例：**

```json
{
  "ok": true,
  "data": {
    "branch_name": "main",
    "protected": true,
    "message": "Branch protection enabled successfully"
  }
}
```

## Workflow

1. **Confirm** the branch name to protect with the user.
2. **Execute** `gitlink-cli branch +protect --name <name>`.
3. **Report** the protection result.

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

## Use Cases

- **保护主分支**：保护 `main` 或 `master` 分支，防止直接推送
- **保护发布分支**：保护 `release` 分支，确保发布版本稳定性
- **保护开发分支**：保护 `develop` 分支，维护开发主线稳定
- **合规要求**：满足团队管理或合规性要求

## What Protection Means

分支保护后，以下操作将被限制：
- ✅ **仍可操作**：通过 Pull Request 合并更改
- ❌ **受限操作**：直接推送代码
- ❌ **受限操作**：强制推送
- ❌ **受限操作**：删除分支
- ❌ **受限操作**：修改历史

## Best Practices

1. **保护关键分支**：至少保护 `main` 和 `develop` 分支
2. **配合 PR 工作流**：强制通过 PR 进行代码审查
3. **定期审查**：定期检查和保护重要的分支
4. **团队协作**：团队协商确定保护策略

## Common Protected Branches

| 分支名 | 用途 | 建议保护 |
|--------|------|----------|
| `main` / `master` | 主分支 | ✅ 强烈建议 |
| `develop` | 开发分支 | ✅ 建议 |
| `release/*` | 发布分支 | ✅ 建议 |
| `hotfix/*` | 紧急修复分支 | ⚠️ 可选 |

## Error Handling

常见错误及解决方案：

| 错误 | 原因 | 解决方案 |
|------|------|----------|
| `404` | 分支不存在 | 使用 `branch +list` 确认分支存在 |
| `403` | 权限不足 | 确认有管理权限 |
| `409` | 已经被保护 | 分支已经处于保护状态 |

## Safety Considerations

- ⚠️ **权限要求**：需要管理员或协作者权限
- ⚠️ **团队影响**：保护分支影响整个团队的协作流程
- ⚠️ **CI/CD 集成**：确保 CI/CD 流程兼容保护规则

## Tips

- 保护前先确认分支名称正确
- 可以使用 `branch +list --format json` 查看分支保护状态
- 设置保护后，团队成员需要通过 PR 贡献代码
- 建议在设置保护前通知团队成员

## Workflow Example

典型的分支保护工作流：

```bash
# 1. 查看分支列表
gitlink-cli branch +list

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

# 3. 设置分支保护
gitlink-cli branch +protect --name main

# 4. 验证保护设置
gitlink-cli branch +list --format json | jq '.data.branchs[] | select(.name=="main") | .protected'
```

## References

- [branch +unprotect](branch-unprotect.md) — 移除分支保护
- [branch +list](branch-list.md) — 列出分支并查看保护状态
- [gitlink-branch](../SKILL.md) — 分支操作总览
- [gitlink-shared](../../gitlink-shared/SKILL.md) — 认证和全局参数
