# Branch Management API

Base URL: `${FORGEJO_URL}/api/v1`

## List Branches

```
GET /repos/{owner}/{repo}/branches
```

**Parameters:**
| Name | Type | In | Description |
|------|------|------|-------------|
| page | integer | query | Page number (1-based) |
| limit | integer | query | Page size |

```bash
curl -s \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/branches?page=1&limit=20"
```

**Response:** Array of `Branch` objects (see schema below).

---

## Create Branch

```
POST /repos/{owner}/{repo}/branches
```

**Request Body (CreateBranchRepoOption):**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| new_branch_name | string | yes | Name for the new branch |
| old_branch_name | string | no | Source branch name (default: repo's default branch) |
| old_ref_name | string | no | Source ref (commit SHA or tag). Alternative to old_branch_name |

### Create from default branch

```bash
curl -s -X POST \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "new_branch_name": "{new_branch}"
  }' \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/branches"
```

### Create from a specific branch

```bash
curl -s -X POST \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "new_branch_name": "{new_branch}",
    "old_branch_name": "{source_branch}"
  }' \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/branches"
```

### Create from a commit SHA

```bash
curl -s -X POST \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "new_branch_name": "{new_branch}",
    "old_ref_name": "abc123def456"
  }' \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/branches"
```

---

## Get Branch Details

```
GET /repos/{owner}/{repo}/branches/{branch}
```

```bash
curl -s \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/branches/{branch}"
```

**Response (Branch):**
| Field | Type | Description |
|-------|------|-------------|
| name | string | Branch name |
| commit | object | Head commit object |
| protected | boolean | Branch is protected |
| required_approvals | integer | Required approval count |
| enable_status_check | boolean | Status checks enabled |
| status_check_contexts | array | Required status check contexts |
| user_can_push | boolean | Current user can push |
| user_can_merge | boolean | Current user can merge |
| effective_branch_protection_name | string | Name of applied protection rule |

### Commit Object

| Field | Type | Description |
|-------|------|-------------|
| id | string | Commit SHA |
| message | string | Commit message |
| url | string | API URL for commit |
| author | object | Author info (name, email, date) |
| committer | object | Committer info (name, email, date) |
| timestamp | string | Commit timestamp |
| added | array | Added files (if available) |
| removed | array | Removed files (if available) |
| modified | array | Modified files (if available) |

**Example Response:**
```json
{
  "name": "{branch}",
  "commit": {
    "id": "abc123def456789...",
    "message": "feat: add new feature\n\nDetailed description",
    "url": "https://{FORGEJO_HOST}/api/v1/repos/{owner}/{repo}/git/commits/{sha}...",
    "author": {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "date": "2025-01-15T10:30:00Z"
    },
    "committer": {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "date": "2025-01-15T10:30:00Z"
    },
    "timestamp": "2025-01-15T10:30:00Z"
  },
  "protected": true,
  "required_approvals": 2,
  "enable_status_check": true,
  "status_check_contexts": ["ci/build", "ci/test"],
  "user_can_push": false,
  "user_can_merge": true,
  "effective_branch_protection_name": "main-protection"
}
```

---

## Update (Rename) Branch

```
PATCH /repos/{owner}/{repo}/branches/{branch}
```

Renames an existing branch.

**Body: UpdateBranchRepoOption**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| name  | string | yes    | New branch name |

```bash
# Rename a branch
curl -s -X PATCH \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"name": "{new_branch_name}"}' \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/branches/{branch}"
```

Returns the updated `Branch` object on success (200).

> **Note:** Renaming the default branch requires updating the repository's default branch setting too (`PATCH /repos/{owner}/{repo}` with `default_branch`). Open pull requests targeting the renamed branch may need to be updated.

---

## Delete Branch

```
DELETE /repos/{owner}/{repo}/branches/{branch}
```

> **Note:** Protected branches cannot be deleted. Remove protection first if needed.

```bash
curl -s -X DELETE \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/branches/{branch}"
```

Returns `204 No Content` on success.

---

## Example: Create feature branch, verify, then clean up

```bash
OWNER="{owner}"
REPO="{repo}"
BRANCH="{branch}"

# Create the branch
curl -s -X POST \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d "{\"new_branch_name\": \"${BRANCH}\"}" \
  "${FORGEJO_URL}/api/v1/repos/${OWNER}/${REPO}/branches"

# Verify it was created
curl -s \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/repos/${OWNER}/${REPO}/branches/${BRANCH}" | jq '.name'

# Delete when done
curl -s -X DELETE \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/repos/${OWNER}/${REPO}/branches/${BRANCH}"
```
