2014-03-31 13:43:45 +00:00
# Branches
## List repository branches
Get a list of repository branches from a project, sorted by name alphabetically.
2017-03-20 08:37:14 +00:00
This endpoint can be accessed without authentication if the repository is
publicly accessible.
2014-03-31 13:43:45 +00:00
```
GET /projects/:id/repository/branches
```
2016-01-18 07:21:01 +00:00
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2016-12-25 13:42:41 +00:00
| `id` | integer/string | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2014-03-31 13:43:45 +00:00
2016-01-18 07:21:01 +00:00
```bash
2017-03-01 17:39:40 +00:00
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/repository/branches
2016-01-18 07:21:01 +00:00
```
Example response:
2014-03-31 13:43:45 +00:00
```json
[
{
2016-01-18 07:21:01 +00:00
"name": "master",
2016-11-28 18:16:15 +00:00
"merged": false,
2016-01-18 07:21:01 +00:00
"protected": true,
2016-07-12 14:31:55 +00:00
"developers_can_push": false,
2016-07-19 08:36:18 +00:00
"developers_can_merge": false,
2014-03-31 13:43:45 +00:00
"commit": {
2015-02-15 14:01:27 +00:00
"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",
2014-03-31 13:43:45 +00:00
"id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
2016-10-27 13:26:58 +00:00
"short_id": "7b5c3cc",
"title": "add projects API",
2014-03-31 13:43:45 +00:00
"message": "add projects API",
2015-02-15 14:01:27 +00:00
"parent_ids": [
"4ad91d3c1144c406e50c7b33bae684bd6837faf8"
]
2016-01-18 07:21:01 +00:00
}
},
...
2014-03-31 13:43:45 +00:00
]
```
## Get single repository branch
2017-03-20 08:37:14 +00:00
Get a single project repository branch. This endpoint can be accessed without
authentication if the repository is publicly accessible.
2014-03-31 13:43:45 +00:00
```
GET /projects/:id/repository/branches/:branch
```
2016-01-18 07:21:01 +00:00
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2016-12-25 13:42:41 +00:00
| `id` | integer/string | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2016-01-18 07:21:01 +00:00
| `branch` | string | yes | The name of the branch |
2014-03-31 13:43:45 +00:00
2016-01-18 07:21:01 +00:00
```bash
2017-03-01 17:39:40 +00:00
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/repository/branches/master
2016-01-18 07:21:01 +00:00
```
Example response:
2014-03-31 13:43:45 +00:00
```json
{
2016-01-18 07:21:01 +00:00
"name": "master",
2016-11-28 18:16:15 +00:00
"merged": false,
2016-01-18 07:21:01 +00:00
"protected": true,
2016-07-12 14:31:55 +00:00
"developers_can_push": false,
2016-07-19 08:36:18 +00:00
"developers_can_merge": false,
2014-03-31 13:43:45 +00:00
"commit": {
2015-02-15 14:01:27 +00:00
"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",
2014-03-31 13:43:45 +00:00
"id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
2016-10-27 13:26:58 +00:00
"short_id": "7b5c3cc",
"title": "add projects API",
2014-03-31 13:43:45 +00:00
"message": "add projects API",
2015-02-15 14:01:27 +00:00
"parent_ids": [
"4ad91d3c1144c406e50c7b33bae684bd6837faf8"
]
2016-01-18 07:21:01 +00:00
}
2014-03-31 13:43:45 +00:00
}
```
## Protect repository branch
2016-01-18 07:21:01 +00:00
Protects a single project repository branch. This is an idempotent function,
protecting an already protected repository branch still returns a `200 OK`
status code.
2014-03-31 13:43:45 +00:00
```
PUT /projects/:id/repository/branches/:branch/protect
```
2016-01-18 07:21:01 +00:00
```bash
2017-03-01 17:39:40 +00:00
curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/repository/branches/master/protect?developers_can_push=true& developers_can_merge=true
2016-01-18 07:21:01 +00:00
```
2014-03-31 13:43:45 +00:00
2016-01-18 07:21:01 +00:00
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2016-12-25 13:42:41 +00:00
| `id` | integer/string | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2016-01-18 07:21:01 +00:00
| `branch` | string | yes | The name of the branch |
2016-07-12 14:31:55 +00:00
| `developers_can_push` | boolean | no | Flag if developers can push to the branch |
2016-07-19 08:36:18 +00:00
| `developers_can_merge` | boolean | no | Flag if developers can merge to the branch |
2016-01-18 07:21:01 +00:00
Example response:
2014-03-31 13:43:45 +00:00
```json
{
"commit": {
2015-02-15 14:01:27 +00:00
"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",
2014-03-31 13:43:45 +00:00
"id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
2016-10-27 13:26:58 +00:00
"short_id": "7b5c3cc",
"title": "add projects API",
2014-03-31 13:43:45 +00:00
"message": "add projects API",
2015-02-15 14:01:27 +00:00
"parent_ids": [
"4ad91d3c1144c406e50c7b33bae684bd6837faf8"
]
2014-03-31 13:43:45 +00:00
},
2015-02-15 14:01:27 +00:00
"name": "master",
2016-11-28 18:16:15 +00:00
"merged": false,
2016-07-12 14:31:55 +00:00
"protected": true,
2016-07-19 08:36:18 +00:00
"developers_can_push": true,
"developers_can_merge": true
2014-03-31 13:43:45 +00:00
}
```
## Unprotect repository branch
2016-01-18 07:21:01 +00:00
Unprotects a single project repository branch. This is an idempotent function,
unprotecting an already unprotected repository branch still returns a `200 OK`
status code.
2014-03-31 13:43:45 +00:00
```
PUT /projects/:id/repository/branches/:branch/unprotect
```
2016-01-18 07:21:01 +00:00
```bash
2017-03-01 17:39:40 +00:00
curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/repository/branches/master/unprotect
2016-01-18 07:21:01 +00:00
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2016-12-25 13:42:41 +00:00
| `id` | integer/string | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2016-01-18 07:21:01 +00:00
| `branch` | string | yes | The name of the branch |
2014-03-31 13:43:45 +00:00
2016-01-18 07:21:01 +00:00
Example response:
2014-03-31 13:43:45 +00:00
```json
{
"commit": {
2015-02-15 14:01:27 +00:00
"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",
2014-03-31 13:43:45 +00:00
"id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
2016-10-27 13:26:58 +00:00
"short_id": "7b5c3cc",
"title": "add projects API",
2014-03-31 13:43:45 +00:00
"message": "add projects API",
2015-02-15 14:01:27 +00:00
"parent_ids": [
"4ad91d3c1144c406e50c7b33bae684bd6837faf8"
]
2014-03-31 13:43:45 +00:00
},
2015-02-15 14:01:27 +00:00
"name": "master",
2016-11-28 18:16:15 +00:00
"merged": false,
2016-07-12 14:31:55 +00:00
"protected": false,
2016-07-19 08:36:18 +00:00
"developers_can_push": false,
"developers_can_merge": false
2014-03-31 13:43:45 +00:00
}
```
2014-04-01 07:44:58 +00:00
## Create repository branch
```
POST /projects/:id/repository/branches
```
2016-01-18 07:21:01 +00:00
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2016-12-25 13:42:41 +00:00
| `id` | integer | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2017-02-02 14:24:30 +00:00
| `branch` | string | yes | The name of the branch |
2016-01-18 07:21:01 +00:00
| `ref` | string | yes | The branch name or commit SHA to create branch from |
```bash
2017-03-01 17:39:40 +00:00
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/repository/branches?branch=newbranch& ref=master"
2016-01-18 07:21:01 +00:00
```
2014-04-01 07:44:58 +00:00
2016-01-18 07:21:01 +00:00
Example response:
2014-04-01 07:44:58 +00:00
```json
{
2014-04-05 06:36:47 +00:00
"commit": {
"author_email": "john@example.com",
2015-02-15 14:01:27 +00:00
"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",
2016-10-27 13:26:58 +00:00
"short_id": "7b5c3cc",
"title": "add projects API",
2015-02-15 14:01:27 +00:00
"message": "add projects API",
"parent_ids": [
"4ad91d3c1144c406e50c7b33bae684bd6837faf8"
]
2014-04-05 06:36:47 +00:00
},
2016-01-18 07:21:01 +00:00
"name": "newbranch",
2016-11-28 18:16:15 +00:00
"merged": false,
2016-07-12 14:31:55 +00:00
"protected": false,
2016-07-19 08:36:18 +00:00
"developers_can_push": false,
"developers_can_merge": false
2014-04-01 07:44:58 +00:00
}
```
2014-05-23 12:34:02 +00:00
## Delete repository branch
```
DELETE /projects/:id/repository/branches/:branch
```
2016-01-18 07:21:01 +00:00
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2016-12-25 13:42:41 +00:00
| `id` | integer/string | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2016-01-18 07:21:01 +00:00
| `branch` | string | yes | The name of the branch |
2014-05-23 12:34:02 +00:00
2016-11-24 17:28:52 +00:00
In case of an error, an explaining message is provided.
2014-05-23 12:34:02 +00:00
2016-01-18 07:21:01 +00:00
```bash
2017-03-01 17:39:40 +00:00
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/repository/branches/newbranch"
2016-01-18 07:21:01 +00:00
```
2014-10-30 15:30:09 +00:00
2016-09-21 14:15:12 +00:00
## Delete merged branches
Will delete all branches that are merged into the project's default branch.
```
DELETE /projects/:id/repository/merged_branches
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2016-12-25 13:42:41 +00:00
| `id` | integer/string | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2016-09-21 14:15:12 +00:00
```bash
2017-03-01 17:39:40 +00:00
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/repository/merged_branches"
2016-09-21 14:15:12 +00:00
```