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

3d37cf79 · Evan Read · Achilleas Pipinellis · 97a0bfd6 · 3d37cf79 · 3d37cf79
Commit 3d37cf79 authored Jan 15, 2019 by Evan Read Committed by Achilleas Pipinellis Jan 15, 2019
Hide whitespace changes
Inline Side-by-side

Showing with 83 additions and 142 deletions

doc/api/branches.md doc/api/branches.md +75 -134

doc/user/project/repository/branches/index.md doc/user/project/repository/branches/index.md +8 -8

No files found.
--- a/doc/api/branches.md
+++ b/doc/api/branches.md
 # 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

 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
 ```

-| 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 |
-| `search` | string | no | Return list of branches matching the search criteria.  |
+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. |
+| `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
 ```

@@ -53,19 +63,25 @@ Example response:

 ## Get single repository branch

-Get a single project repository branch. This endpoint can be accessed without
-authentication if the repository is publicly accessible.
+Get a single project repository branch.

-```
+NOTE: **Note:**
+This endpoint can be accessed without authentication if the repository is publicly accessible.
+
+```text
 GET /projects/:id/repository/branches/:branch
 ```

-| 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 |
+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.                                                                                          |

-```bash
+Example request:
+
+```sh
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/repository/branches/master
 ```

@@ -100,120 +116,34 @@ Example response:

 ## Protect repository branch

->**Note:** This API endpoint is deprecated in favor of `POST /projects/:id/protected_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
-}
-```
+See [`POST /projects/:id/protected_branches`](protected_branches.md#protect-repository-branches) for
+information on protecting repository branches.

 ## 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,
-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 |
+## Create repository branch

-Example response:
+Create a new branch in the repository.

-```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": false,
-  "default": true,
-  "developers_can_push": false,
-  "developers_can_merge": false,
-  "can_push": true
-}
+```text
+POST /projects/:id/repository/branches
 ```

-## Create repository branch
+Parameters:

-```
-POST /projects/:id/repository/branches
-```
+| 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.                                                             |

-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `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 |
+Example request:

-```bash
-curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/branches?branch=newbranch&ref=master"
+```sh
+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:
@@ -247,36 +177,47 @@ Example response:

 ## 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
 ```

-| 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 |
+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.                                                                                          |

-In case of an error, an explaining message is provided.
+Example request:

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

 ## Delete merged branches

 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
 ```

-| 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 |
+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. |

+Example request:

-```bash
-curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/merged_branches"
+```sh
+curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/repository/merged_branches
 ```
--- a/doc/user/project/repository/branches/index.md
+++ b/doc/user/project/repository/branches/index.md
@@ -2,16 +2,17 @@

 Read through GiLab's branching documentation:

- [Create a branch](../web_editor.md#create-a-new-branch)
- [Default branch](#default-branch)
- [Protected branches](../../protected_branches.md#protected-branches)
- [Delete merged branches](#delete-merged-branches)
- [Branch filter search box](#branch-filter-search-box)
+- [Create a branch](../web_editor.md#create-a-new-branch).
+- [Default branch](#default-branch).
+- [Protected branches](../../protected_branches.md#protected-branches).
+- [Delete merged branches](#delete-merged-branches).
+- [Branch filter search box](#branch-filter-search-box).

 See also:

- [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
+- [Branches API](../../../../api/branches.md), for information on operating on repository branches using the GitLab API.
+- [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

@@ -41,7 +42,6 @@ this operation.
 It's particularly useful to clean up old branches that were not deleted
 automatically when a merge request was merged.

-
 ## Branch filter search box

 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22166) in GitLab 11.5.