Skip to content

G
gitlab-ce
Commit f06a9035 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis
Browse files
Options

Merge branch 'docs/uplift-branches-api-doc' into 'master' 

Add more information and refactor format of branch-related API topics

See merge request gitlab-org/gitlab-ce!24290
parents 97a0bfd6 3d37cf79
Hide whitespace changes
Inline Side-by-side
Showing with 83 additions and 142 deletions
doc/api/branches.md
View file @ f06a9035
# Branches API # Branches API
This API operates on [repository branches](../user/project/repository/branches/index.md).
TIP: **Tip:**
See also [Protected branches API](protected_branches.md).
## List repository branches ## List repository branches
Get a list of repository branches from a project, sorted by name alphabetically. Get a list of repository branches from a project, sorted by name alphabetically.
This endpoint can be accessed without authentication if the repository is
publicly accessible.
``` NOTE: **Note:**
This endpoint can be accessed without authentication if the repository is publicly accessible.
```text
GET /projects/:id/repository/branches GET /projects/:id/repository/branches
``` ```
| Attribute | Type | Required | Description | Parameters:
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | Attribute | Type | Required | Description |
| `search` | string | no | Return list of branches matching the search criteria. | |:----------|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------|
| `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 matching the search criteria. |
Example request:
```bash ```sh
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/repository/branches curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/repository/branches
``` ```
...@@ -53,19 +63,25 @@ Example response: ...@@ -53,19 +63,25 @@ Example response:
## Get single repository branch ## Get single repository branch
Get a single project repository branch. This endpoint can be accessed without Get a single project repository branch.
authentication if the repository is publicly accessible.
``` NOTE: **Note:**
This endpoint can be accessed without authentication if the repository is publicly accessible.
```text
GET /projects/:id/repository/branches/:branch GET /projects/:id/repository/branches/:branch
``` ```
| Attribute | Type | Required | Description | Parameters:
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | Attribute | Type | Required | Description |
| `branch` | string | yes | The name of the branch | |:----------|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------|
| `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. |
```bash Example request:
```sh
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/repository/branches/master curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/repository/branches/master
``` ```
...@@ -100,120 +116,34 @@ Example response: ...@@ -100,120 +116,34 @@ Example response:
## Protect repository branch ## Protect repository branch
>**Note:** This API endpoint is deprecated in favor of `POST /projects/:id/protected_branches`. See [`POST /projects/:id/protected_branches`](protected_branches.md#protect-repository-branches) for
information on protecting repository branches.
Protects a single project repository branch. This is an idempotent function,
protecting an already protected repository branch still returns a `200 OK`
status code.
```
PUT /projects/:id/repository/branches/:branch/protect
```
```bash
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/repository/branches/master/protect?developers_can_push=true&developers_can_merge=true
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `branch` | string | yes | The name of the branch |
| `developers_can_push` | boolean | no | Flag if developers can push to the branch |
| `developers_can_merge` | boolean | no | Flag if developers can merge to the branch |
Example response:
```json
{
"commit": {
"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",
"id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
"short_id": "7b5c3cc",
"title": "add projects API",
"message": "add projects API",
"parent_ids": [
"4ad91d3c1144c406e50c7b33bae684bd6837faf8"
]
},
"name": "master",
"merged": false,
"protected": true,
"default": true,
"developers_can_push": true,
"developers_can_merge": true,
"can_push": true
}
```
## Unprotect repository branch ## Unprotect repository branch
>**Note:** This API endpoint is deprecated in favor of `DELETE /projects/:id/protected_branches/:name` See [`DELETE /projects/:id/protected_branches/:name`](protected_branches.md#unprotect-repository-branches)
for information on unprotecting repository branches.
Unprotects a single project repository branch. This is an idempotent function, ## Create repository branch
unprotecting an already unprotected repository branch still returns a `200 OK`
status code.
```
PUT /projects/:id/repository/branches/:branch/unprotect
```
```bash
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/repository/branches/master/unprotect
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `branch` | string | yes | The name of the branch |
Example response: Create a new branch in the repository.
```json ```text
{ POST /projects/:id/repository/branches
"commit": {
"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",
"id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
"short_id": "7b5c3cc",
"title": "add projects API",
"message": "add projects API",
"parent_ids": [
"4ad91d3c1144c406e50c7b33bae684bd6837faf8"
]
},
"name": "master",
"merged": false,
"protected": false,
"default": true,
"developers_can_push": false,
"developers_can_merge": false,
"can_push": true
}
``` ```
## Create repository branch Parameters:
``` | Attribute | Type | Required | Description |
POST /projects/:id/repository/branches |:----------|:--------|:---------|:-------------------------------------------------------------------------------------------------------------|
``` | `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. |
| Attribute | Type | Required | Description | Example request:
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `branch` | string | yes | The name of the branch |
| `ref` | string | yes | The branch name or commit SHA to create branch from |
```bash ```sh
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/branches?branch=newbranch&ref=master" curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/repository/branches?branch=newbranch&ref=master
``` ```
Example response: Example response:
...@@ -247,36 +177,47 @@ Example response: ...@@ -247,36 +177,47 @@ Example response:
## Delete repository branch ## Delete repository branch
``` Delete a branch from the repository.
NOTE: **Note:**
In the case of an error, an explanation message is provided.
```text
DELETE /projects/:id/repository/branches/:branch DELETE /projects/:id/repository/branches/:branch
``` ```
| Attribute | Type | Required | Description | Parameters:
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | Attribute | Type | Required | Description |
| `branch` | string | yes | The name of the branch | |:----------|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------|
| `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. |
In case of an error, an explaining message is provided. Example request:
```bash ```sh
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/branches/newbranch" curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/repository/branches/newbranch
``` ```
## Delete merged branches ## Delete merged branches
Will delete all branches that are merged into the project's default branch. Will delete all branches that are merged into the project's default branch.
Protected branches will not be deleted as part of this operation. NOTE: **Note:**
[Protected branches](../user/project/protected_branches.md) will not be deleted as part of this operation.
``` ```text
DELETE /projects/:id/repository/merged_branches DELETE /projects/:id/repository/merged_branches
``` ```
| Attribute | Type | Required | Description | Parameters:
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | 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. |
Example request:
```bash ```sh
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/merged_branches" curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/repository/merged_branches
``` ```
doc/user/project/repository/branches/index.md
View file @ f06a9035
...@@ -2,16 +2,17 @@ ...@@ -2,16 +2,17 @@
Read through GiLab's branching documentation: Read through GiLab's branching documentation:
- [Create a branch](../web_editor.md#create-a-new-branch) - [Create a branch](../web_editor.md#create-a-new-branch).
- [Default branch](#default-branch) - [Default branch](#default-branch).
- [Protected branches](../../protected_branches.md#protected-branches) - [Protected branches](../../protected_branches.md#protected-branches).
- [Delete merged branches](#delete-merged-branches) - [Delete merged branches](#delete-merged-branches).
- [Branch filter search box](#branch-filter-search-box) - [Branch filter search box](#branch-filter-search-box).
See also: See also:
- [GitLab Flow](../../../../university/training/gitlab_flow.md#gitlab-flow): use the best of GitLab for your branching strategies - [Branches API](../../../../api/branches.md), for information on operating on repository branches using the GitLab API.
- [Getting started with Git](../../../../topics/git/index.md) and GitLab - [GitLab Flow](../../../../university/training/gitlab_flow.md#gitlab-flow). Use the best of GitLab for your branching strategies.
- [Getting started with Git](../../../../topics/git/index.md) and GitLab.
## Default branch ## Default branch
...@@ -41,7 +42,6 @@ this operation. ...@@ -41,7 +42,6 @@ this operation.
It's particularly useful to clean up old branches that were not deleted It's particularly useful to clean up old branches that were not deleted
automatically when a merge request was merged. automatically when a merge request was merged.
## Branch filter search box ## Branch filter search box
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22166) in GitLab 11.5. > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22166) in GitLab 11.5.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7