2020-07-30 12:09:33 +00:00
---
stage: Create
group: Source Code
2020-11-26 06:09:20 +00:00
info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments"
2020-07-30 12:09:33 +00:00
type: reference, api
---
2021-02-09 18:09:59 +00:00
# Branches API **(FREE)**
2014-03-31 13:43:45 +00:00
2019-01-15 18:31:12 +00:00
This API operates on [repository branches ](../user/project/repository/branches/index.md ).
See also [Protected branches API ](protected_branches.md ).
2014-03-31 13:43:45 +00:00
## List repository branches
Get a list of repository branches from a project, sorted by name alphabetically.
2020-12-04 21:09:29 +00:00
NOTE:
2019-01-15 18:31:12 +00:00
This endpoint can be accessed without authentication if the repository is publicly accessible.
2020-05-20 03:08:04 +00:00
```plaintext
2014-03-31 13:43:45 +00:00
GET /projects/:id/repository/branches
```
2019-01-15 18:31:12 +00:00
Parameters:
2019-01-27 20:36:23 +00:00
| Attribute | Type | Required | Description |
|:----------|:---------------|:---------|:------------|
2021-06-28 15:08:03 +00:00
| `id` | integer/string | yes | ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) owned by the authenticated user.|
2019-11-05 12:06:20 +00:00
| `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. |
2019-02-11 12:08:13 +00:00
2019-01-15 18:31:12 +00:00
Example request:
2014-03-31 13:43:45 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "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,
2018-08-18 11:00:40 +00:00
"default": 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,
2018-06-18 10:02:56 +00:00
"can_push": true,
2021-09-09 09:11:16 +00:00
"web_url": "https://gitlab.example.com/my-group/my-project/-/tree/master",
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
2019-01-15 18:31:12 +00:00
Get a single project repository branch.
2014-03-31 13:43:45 +00:00
2020-12-04 21:09:29 +00:00
NOTE:
2019-01-15 18:31:12 +00:00
This endpoint can be accessed without authentication if the repository is publicly accessible.
2020-05-20 03:08:04 +00:00
```plaintext
2014-03-31 13:43:45 +00:00
GET /projects/:id/repository/branches/:branch
```
2019-01-15 18:31:12 +00:00
Parameters:
| Attribute | Type | Required | Description |
|:----------|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------|
2021-06-28 15:08:03 +00:00
| `id` | integer/string | yes | ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) owned by the authenticated user. |
2019-01-15 18:31:12 +00:00
| `branch` | string | yes | Name of the branch. |
2014-03-31 13:43:45 +00:00
2019-01-15 18:31:12 +00:00
Example request:
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "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,
2018-08-18 11:00:40 +00:00
"default": 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,
2018-06-18 10:02:56 +00:00
"can_push": true,
2021-09-09 09:11:16 +00:00
"web_url": "https://gitlab.example.com/my-group/my-project/-/tree/master",
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
2019-01-15 18:31:12 +00:00
See [`POST /projects/:id/protected_branches` ](protected_branches.md#protect-repository-branches ) for
information on protecting repository branches.
2014-03-31 13:43:45 +00:00
## Unprotect repository branch
2019-01-15 18:31:12 +00:00
See [`DELETE /projects/:id/protected_branches/:name` ](protected_branches.md#unprotect-repository-branches )
for information on unprotecting repository branches.
2017-08-02 10:16:17 +00:00
2019-01-15 18:31:12 +00:00
## Create repository branch
2014-03-31 13:43:45 +00:00
2019-01-15 18:31:12 +00:00
Create a new branch in the repository.
2014-03-31 13:43:45 +00:00
2020-05-20 03:08:04 +00:00
```plaintext
2019-01-15 18:31:12 +00:00
POST /projects/:id/repository/branches
2014-03-31 13:43:45 +00:00
```
2014-04-01 07:44:58 +00:00
2019-01-15 18:31:12 +00:00
Parameters:
2014-04-01 07:44:58 +00:00
2019-01-15 18:31:12 +00:00
| Attribute | Type | Required | Description |
|:----------|:--------|:---------|:-------------------------------------------------------------------------------------------------------------|
2021-06-28 15:08:03 +00:00
| `id` | integer | yes | ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) owned by the authenticated user. |
2019-01-15 18:31:12 +00:00
| `branch` | string | yes | Name of the branch. |
| `ref` | string | yes | Branch name or commit SHA to create branch from. |
2014-04-01 07:44:58 +00:00
2019-01-15 18:31:12 +00:00
Example request:
2016-01-18 07:21:01 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " "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,
2018-08-18 11:00:40 +00:00
"default": false,
2016-07-19 08:36:18 +00:00
"developers_can_push": false,
2018-06-18 10:02:56 +00:00
"developers_can_merge": false,
2020-04-29 12:10:00 +00:00
"can_push": true,
2021-09-09 09:11:16 +00:00
"web_url": "https://gitlab.example.com/my-group/my-project/-/tree/newbranch"
2014-04-01 07:44:58 +00:00
}
```
2014-05-23 12:34:02 +00:00
## Delete repository branch
2019-01-15 18:31:12 +00:00
Delete a branch from the repository.
2020-12-04 21:09:29 +00:00
NOTE:
2019-01-15 18:31:12 +00:00
In the case of an error, an explanation message is provided.
2020-05-20 03:08:04 +00:00
```plaintext
2014-05-23 12:34:02 +00:00
DELETE /projects/:id/repository/branches/:branch
```
2019-01-15 18:31:12 +00:00
Parameters:
| Attribute | Type | Required | Description |
|:----------|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------|
2021-06-28 15:08:03 +00:00
| `id` | integer/string | yes | ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) owned by the authenticated user. |
2019-01-15 18:31:12 +00:00
| `branch` | string | yes | Name of the branch. |
2014-05-23 12:34:02 +00:00
2019-01-15 18:31:12 +00:00
Example request:
2014-05-23 12:34:02 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --request DELETE --header "PRIVATE-TOKEN: < your_access_token > " "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
2021-03-08 18:09:12 +00:00
Deletes all branches that are merged into the project's default branch.
2016-09-21 14:15:12 +00:00
2020-12-04 21:09:29 +00:00
NOTE:
2021-03-08 18:09:12 +00:00
[Protected branches ](../user/project/protected_branches.md ) are not deleted as part of this operation.
2017-06-08 10:37:35 +00:00
2020-05-20 03:08:04 +00:00
```plaintext
2016-09-21 14:15:12 +00:00
DELETE /projects/:id/repository/merged_branches
```
2019-01-15 18:31:12 +00:00
Parameters:
| Attribute | Type | Required | Description |
|:----------|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------|
2021-06-28 15:08:03 +00:00
| `id` | integer/string | yes | ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) owned by the authenticated user. |
2016-09-21 14:15:12 +00:00
2019-01-15 18:31:12 +00:00
Example request:
2016-09-21 14:15:12 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --request DELETE --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/repository/merged_branches"
2016-09-21 14:15:12 +00:00
```