branches.md 7.42 KB
Newer Older
1
# Branches API
2

3 4 5 6 7
This API operates on [repository branches](../user/project/repository/branches/index.md).

TIP: **Tip:**
See also [Protected branches API](protected_branches.md).

8 9 10 11
## List repository branches

Get a list of repository branches from a project, sorted by name alphabetically.

12 13 14 15
NOTE: **Note:**
This endpoint can be accessed without authentication if the repository is publicly accessible.

```text
16 17 18
GET /projects/:id/repository/branches
```

19 20
Parameters:

21 22 23 24
| Attribute | Type           | Required | Description |
|:----------|:---------------|:---------|:------------|
| `id`      | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user.|
| `search`  | string         | no       | Return list of branches containing the search string. You can use `^term` and `term$` to find branches that begin and end with `term` respectively.|
25

26
Example request:
27

28
```sh
29
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/repository/branches
30 31 32
```

Example response:
33 34 35 36

```json
[
  {
37
    "name": "master",
38
    "merged": false,
39
    "protected": true,
40
    "default": true,
41
    "developers_can_push": false,
42
    "developers_can_merge": false,
43
    "can_push": true,
44
    "commit": {
45 46 47 48 49 50
      "author_email": "john@example.com",
      "author_name": "John Smith",
      "authored_date": "2012-06-27T05:51:39-07:00",
      "committed_date": "2012-06-28T03:44:20-07:00",
      "committer_email": "john@example.com",
      "committer_name": "John Smith",
51
      "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
52 53
      "short_id": "7b5c3cc",
      "title": "add projects API",
54
      "message": "add projects API",
55 56 57
      "parent_ids": [
        "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
      ]
58 59 60
    }
  },
  ...
61 62 63 64 65
]
```

## Get single repository branch

66
Get a single project repository branch.
67

68 69 70 71
NOTE: **Note:**
This endpoint can be accessed without authentication if the repository is publicly accessible.

```text
72 73 74
GET /projects/:id/repository/branches/:branch
```

75 76 77 78 79 80
Parameters:

| Attribute | Type           | Required | Description                                                                                                  |
|:----------|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------|
| `id`      | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `branch`  | string         | yes      | Name of the branch.                                                                                          |
81

82 83 84
Example request:

```sh
85
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/repository/branches/master
86 87 88
```

Example response:
89 90 91

```json
{
92
  "name": "master",
93
  "merged": false,
94
  "protected": true,
95
  "default": true,
96
  "developers_can_push": false,
97
  "developers_can_merge": false,
98
  "can_push": true,
99
  "commit": {
100 101 102 103 104 105
    "author_email": "john@example.com",
    "author_name": "John Smith",
    "authored_date": "2012-06-27T05:51:39-07:00",
    "committed_date": "2012-06-28T03:44:20-07:00",
    "committer_email": "john@example.com",
    "committer_name": "John Smith",
106
    "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
107 108
    "short_id": "7b5c3cc",
    "title": "add projects API",
109
    "message": "add projects API",
110 111 112
    "parent_ids": [
      "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
    ]
113
  }
114 115 116 117 118
}
```

## Protect repository branch

119 120
See [`POST /projects/:id/protected_branches`](protected_branches.md#protect-repository-branches) for
information on protecting repository branches.
121 122 123

## Unprotect repository branch

124 125
See [`DELETE /projects/:id/protected_branches/:name`](protected_branches.md#unprotect-repository-branches)
for information on unprotecting repository branches.
126

127
## Create repository branch
128

129
Create a new branch in the repository.
130

131 132
```text
POST /projects/:id/repository/branches
133
```
134

135
Parameters:
136

137 138 139 140 141
| Attribute | Type    | Required | Description                                                                                                  |
|:----------|:--------|:---------|:-------------------------------------------------------------------------------------------------------------|
| `id`      | integer | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `branch`  | string  | yes      | Name of the branch.                                                                                          |
| `ref`     | string  | yes      | Branch name or commit SHA to create branch from.                                                             |
142

143
Example request:
144

145 146
```sh
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/repository/branches?branch=newbranch&ref=master
147
```
148

149
Example response:
150 151 152

```json
{
153 154
  "commit": {
    "author_email": "john@example.com",
155 156 157 158 159 160
    "author_name": "John Smith",
    "authored_date": "2012-06-27T05:51:39-07:00",
    "committed_date": "2012-06-28T03:44:20-07:00",
    "committer_email": "john@example.com",
    "committer_name": "John Smith",
    "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
161 162
    "short_id": "7b5c3cc",
    "title": "add projects API",
163 164 165 166
    "message": "add projects API",
    "parent_ids": [
      "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
    ]
167
  },
168
  "name": "newbranch",
169
  "merged": false,
170
  "protected": false,
171
  "default": false,
172
  "developers_can_push": false,
173 174
  "developers_can_merge": false,
  "can_push": true
175 176
}
```
177 178 179

## Delete repository branch

180 181 182 183 184 185
Delete a branch from the repository.

NOTE: **Note:**
In the case of an error, an explanation message is provided.

```text
186 187 188
DELETE /projects/:id/repository/branches/:branch
```

189 190 191 192 193 194
Parameters:

| Attribute | Type           | Required | Description                                                                                                  |
|:----------|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------|
| `id`      | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `branch`  | string         | yes      | Name of the branch.                                                                                          |
195

196
Example request:
197

198 199
```sh
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/repository/branches/newbranch
200
```
201

202 203 204 205
## Delete merged branches

Will delete all branches that are merged into the project's default branch.

206 207
NOTE: **Note:**
[Protected branches](../user/project/protected_branches.md) will not be deleted as part of this operation.
208

209
```text
210 211 212
DELETE /projects/:id/repository/merged_branches
```

213 214 215 216 217
Parameters:

| Attribute | Type           | Required | Description                                                                                                  |
|:----------|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------|
| `id`      | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
218

219
Example request:
220

221 222
```sh
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/repository/merged_branches
223
```