debian-mirror-gitlab/doc/api/branches.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

240 lines
8.3 KiB
Markdown
Raw Normal View History

2020-10-24 23:57:45 +05:30
---
stage: Create
group: Source Code
2022-11-25 23:54:43 +05:30
info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments"
2020-10-24 23:57:45 +05:30
type: reference, api
---
2021-03-11 19:13:27 +05:30
# Branches API **(FREE)**
2014-09-02 18:07:02 +05:30
2019-03-02 22:35:43 +05:30
This API operates on [repository branches](../user/project/repository/branches/index.md).
See also [Protected branches API](protected_branches.md).
2014-09-02 18:07:02 +05:30
## List repository branches
Get a list of repository branches from a project, sorted by name alphabetically.
2021-02-22 17:27:13 +05:30
NOTE:
2019-03-02 22:35:43 +05:30
This endpoint can be accessed without authentication if the repository is publicly accessible.
2020-05-24 23:13:21 +05:30
```plaintext
2014-09-02 18:07:02 +05:30
GET /projects/:id/repository/branches
```
2019-03-02 22:35:43 +05:30
Parameters:
2019-07-07 11:18:12 +05:30
| Attribute | Type | Required | Description |
|:----------|:---------------|:---------|:------------|
2023-04-23 21:23:45 +05:30
| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user.|
2023-07-09 08:55:56 +05:30
| `search` | string | no | Return list of branches containing the search string. You can use `^term` to find branches that begin with `term`, and `term$` to find branches that end with `term`. |
2023-04-23 21:23:45 +05:30
| `regex` | string | no | Return list of branches with names matching a [re2](https://github.com/google/re2/wiki/Syntax) regular expression. |
2019-03-02 22:35:43 +05:30
Example request:
2014-09-02 18:07:02 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/branches"
2016-04-02 18:10:28 +05:30
```
Example response:
2014-09-02 18:07:02 +05:30
```json
[
{
2022-01-26 12:08:38 +05:30
"name": "main",
2017-08-17 22:00:37 +05:30
"merged": false,
2016-04-02 18:10:28 +05:30
"protected": true,
2018-11-20 20:47:30 +05:30
"default": true,
2016-08-24 12:49:21 +05:30
"developers_can_push": false,
"developers_can_merge": false,
2018-11-08 19:23:39 +05:30
"can_push": true,
2022-01-26 12:08:38 +05:30
"web_url": "https://gitlab.example.com/my-group/my-project/-/tree/main",
2014-09-02 18:07:02 +05:30
"commit": {
2015-04-26 12:48:37 +05:30
"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-09-02 18:07:02 +05:30
"id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
2017-08-17 22:00:37 +05:30
"short_id": "7b5c3cc",
"title": "add projects API",
2014-09-02 18:07:02 +05:30
"message": "add projects API",
2015-04-26 12:48:37 +05:30
"parent_ids": [
"4ad91d3c1144c406e50c7b33bae684bd6837faf8"
]
2016-04-02 18:10:28 +05:30
}
},
...
2014-09-02 18:07:02 +05:30
]
```
## Get single repository branch
2019-03-02 22:35:43 +05:30
Get a single project repository branch.
2014-09-02 18:07:02 +05:30
2021-02-22 17:27:13 +05:30
NOTE:
2019-03-02 22:35:43 +05:30
This endpoint can be accessed without authentication if the repository is publicly accessible.
2020-05-24 23:13:21 +05:30
```plaintext
2014-09-02 18:07:02 +05:30
GET /projects/:id/repository/branches/:branch
```
2019-03-02 22:35:43 +05:30
Parameters:
| Attribute | Type | Required | Description |
|:----------|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------|
2023-04-23 21:23:45 +05:30
| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. |
| `branch` | string | yes | [URL-encoded name](rest/index.md#namespaced-path-encoding) of the branch. |
2014-09-02 18:07:02 +05:30
2019-03-02 22:35:43 +05:30
Example request:
2020-03-13 15:44:24 +05:30
```shell
2022-01-26 12:08:38 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/branches/main"
2016-04-02 18:10:28 +05:30
```
Example response:
2014-09-02 18:07:02 +05:30
```json
{
2016-04-02 18:10:28 +05:30
"name": "master",
2017-08-17 22:00:37 +05:30
"merged": false,
2016-04-02 18:10:28 +05:30
"protected": true,
2018-11-20 20:47:30 +05:30
"default": true,
2016-08-24 12:49:21 +05:30
"developers_can_push": false,
"developers_can_merge": false,
2018-11-08 19:23:39 +05:30
"can_push": true,
2022-01-26 12:08:38 +05:30
"web_url": "https://gitlab.example.com/my-group/my-project/-/tree/main",
2014-09-02 18:07:02 +05:30
"commit": {
2015-04-26 12:48:37 +05:30
"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-09-02 18:07:02 +05:30
"id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
2017-08-17 22:00:37 +05:30
"short_id": "7b5c3cc",
"title": "add projects API",
2014-09-02 18:07:02 +05:30
"message": "add projects API",
2015-04-26 12:48:37 +05:30
"parent_ids": [
"4ad91d3c1144c406e50c7b33bae684bd6837faf8"
]
2016-04-02 18:10:28 +05:30
}
2014-09-02 18:07:02 +05:30
}
```
## Protect repository branch
2019-03-02 22:35:43 +05:30
See [`POST /projects/:id/protected_branches`](protected_branches.md#protect-repository-branches) for
information on protecting repository branches.
2014-09-02 18:07:02 +05:30
## Unprotect repository branch
2019-03-02 22:35:43 +05:30
See [`DELETE /projects/:id/protected_branches/:name`](protected_branches.md#unprotect-repository-branches)
for information on unprotecting repository branches.
2017-09-10 17:25:29 +05:30
2019-03-02 22:35:43 +05:30
## Create repository branch
2014-09-02 18:07:02 +05:30
2019-03-02 22:35:43 +05:30
Create a new branch in the repository.
2014-09-02 18:07:02 +05:30
2020-05-24 23:13:21 +05:30
```plaintext
2019-03-02 22:35:43 +05:30
POST /projects/:id/repository/branches
2014-09-02 18:07:02 +05:30
```
2019-03-02 22:35:43 +05:30
Parameters:
2014-09-02 18:07:02 +05:30
2019-03-02 22:35:43 +05:30
| Attribute | Type | Required | Description |
|:----------|:--------|:---------|:-------------------------------------------------------------------------------------------------------------|
2023-04-23 21:23:45 +05:30
| `id` | integer | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. |
2019-03-02 22:35:43 +05:30
| `branch` | string | yes | Name of the branch. |
| `ref` | string | yes | Branch name or commit SHA to create branch from. |
2014-09-02 18:07:02 +05:30
2019-03-02 22:35:43 +05:30
Example request:
2016-04-02 18:10:28 +05:30
2020-03-13 15:44:24 +05:30
```shell
2022-01-26 12:08:38 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/branches?branch=newbranch&ref=main"
2016-04-02 18:10:28 +05:30
```
2014-09-02 18:07:02 +05:30
2016-04-02 18:10:28 +05:30
Example response:
2014-09-02 18:07:02 +05:30
```json
{
"commit": {
"author_email": "john@example.com",
2015-04-26 12:48:37 +05:30
"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",
2017-08-17 22:00:37 +05:30
"short_id": "7b5c3cc",
"title": "add projects API",
2015-04-26 12:48:37 +05:30
"message": "add projects API",
"parent_ids": [
"4ad91d3c1144c406e50c7b33bae684bd6837faf8"
]
2014-09-02 18:07:02 +05:30
},
2016-04-02 18:10:28 +05:30
"name": "newbranch",
2017-08-17 22:00:37 +05:30
"merged": false,
2016-08-24 12:49:21 +05:30
"protected": false,
2018-11-20 20:47:30 +05:30
"default": false,
2016-08-24 12:49:21 +05:30
"developers_can_push": false,
2018-11-08 19:23:39 +05:30
"developers_can_merge": false,
2020-05-24 23:13:21 +05:30
"can_push": true,
2021-11-11 11:23:49 +05:30
"web_url": "https://gitlab.example.com/my-group/my-project/-/tree/newbranch"
2014-09-02 18:07:02 +05:30
}
```
## Delete repository branch
2019-03-02 22:35:43 +05:30
Delete a branch from the repository.
2021-02-22 17:27:13 +05:30
NOTE:
2019-03-02 22:35:43 +05:30
In the case of an error, an explanation message is provided.
2020-05-24 23:13:21 +05:30
```plaintext
2014-09-02 18:07:02 +05:30
DELETE /projects/:id/repository/branches/:branch
```
2019-03-02 22:35:43 +05:30
Parameters:
| Attribute | Type | Required | Description |
|:----------|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------|
2023-04-23 21:23:45 +05:30
| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. |
2019-03-02 22:35:43 +05:30
| `branch` | string | yes | Name of the branch. |
2014-09-02 18:07:02 +05:30
2019-03-02 22:35:43 +05:30
Example request:
2014-09-02 18:07:02 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/branches/newbranch"
2016-04-02 18:10:28 +05:30
```
2015-04-26 12:48:37 +05:30
2017-08-17 22:00:37 +05:30
## Delete merged branches
2015-04-26 12:48:37 +05:30
2021-04-17 20:07:23 +05:30
Deletes all branches that are merged into the project's default branch.
2017-08-17 22:00:37 +05:30
2021-02-22 17:27:13 +05:30
NOTE:
2021-04-17 20:07:23 +05:30
[Protected branches](../user/project/protected_branches.md) are not deleted as part of this operation.
2017-09-10 17:25:29 +05:30
2020-05-24 23:13:21 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
DELETE /projects/:id/repository/merged_branches
```
2019-03-02 22:35:43 +05:30
Parameters:
| Attribute | Type | Required | Description |
|:----------|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------|
2023-04-23 21:23:45 +05:30
| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. |
2017-08-17 22:00:37 +05:30
2019-03-02 22:35:43 +05:30
Example request:
2017-08-17 22:00:37 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/merged_branches"
2015-04-26 12:48:37 +05:30
```
2023-07-09 08:55:56 +05:30
## Related topics
- [Branches](../user/project/repository/branches/index.md)
- [Protected branches](../user/project/protected_branches.md)
- [Protected branches API](protected_branches.md)