# branch +unprotect

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

移除分支保护规则，允许分支被直接修改。

## 命令

```bash
# 移除分支保护
gitlink-cli branch +unprotect --name main

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

# 移除开发分支保护
gitlink-cli branch +unprotect --name develop
```

## 参数

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

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

## API

```
DELETE /{owner}/{repo}/protected_branches/{branch_name}
```

**响应示例：**

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

## Workflow

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

> [!CAUTION]
> This is a **Write Operation** — confirm user intent before executing. This will allow direct pushes to the branch.

## Use Cases

- **紧急修复**：临时允许直接推送紧急修复
- **分支重组**：调整分支保护策略
- **迁移工作流**：从 PR 工作流切换到直接推送
- **权限调整**：根据团队需求调整保护规则

## What Unprotection Means

移除分支保护后，以下操作将被允许：
- ✅ **允许操作**：直接推送代码
- ✅ **允许操作**：强制推送
- ✅ **允许操作**：删除分支
- ✅ **允许操作**：修改历史

## Risks and Considerations

⚠️ **风险提醒**：
- 失去 PR 代码审查机制
- 可能直接推送到关键分支
- 增加代码冲突和错误风险
- 影响代码质量和稳定性

## Best Practices

1. **谨慎使用**：仅在确有需要时移除保护
2. **临时移除**：考虑临时移除后重新保护
3. **团队沟通**：移除保护前通知团队成员
4. **重新保护**：完成操作后及时恢复保护

## When to Use

**适合移除保护的情况：**
- 紧急修复需要快速部署
- 仓库结构重组或迁移
- 测试和验证工作流
- 小团队内部协作

**不适合移除保护的情况：**
- 有 PR 审查需求
- 多人协作的大型项目
- 需要严格代码质量控制
- 生产环境的关键分支

## Error Handling

常见错误及解决方案：

| 错误 | 原因 | 解决方案 |
|------|------|----------|
| `404` | 分支不存在 | 使用 `branch +list` 确认分支存在 |
| `404` | 未被保护 | 分支当前没有保护规则 |
| `403` | 权限不足 | 确认有管理权限 |
| `400` | 路径问题 | 含 `/` 的分支名可能需要通过 Web 操作 |

## Limitations

- ⚠️ **路径限制**：含 `/` 的分支名（如 `feature/my-branch`）可能无法通过 CLI 移除保护
- ⚠️ **API 限制**：某些特殊分支可能需要通过 Web 页面操作
- ⚠️ **权限要求**：需要管理员或协作者权限

## Safety Workflow

推荐的移除保护工作流：

```bash
# 1. 查看当前保护状态
gitlink-cli branch +list --format json | jq '.data.branches[] | select(.protected)'

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

# 3. 移除分支保护
gitlink-cli branch +unprotect --name main

# 4. 验证移除结果
gitlink-cli branch +list --format json | jq '.data.branches[] | select(.name=="main") | .protected'

# 5. 完成操作后重新保护
gitlink-cli branch +protect --name main
```

## Tips

- 移除保护前，建议先检查当前的保护状态
- 考虑设置定时提醒，确保及时恢复保护
- 对于重要分支，建议使用 Web UI 确认移除保护
- 记录移除保护的原因和时间，便于审计

## Team Collaboration

团队协作时的建议：

1. **提前沟通**：在移除保护前通知所有团队成员
2. **说明原因**：向团队解释为什么需要移除保护
3. **时间限制**：设定移除保护的时间限制
4. **操作文档**：记录移除保护的操作和原因
5. **及时恢复**：完成操作后立即恢复保护

## References

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