Commit ffab77f3 authored by Craig Norris's avatar Craig Norris

Merge branch 'docs-aqualls-create-future3' into 'master'

Fix future tense in Source Code docset

See merge request gitlab-org/gitlab!55914
parents 07d6cbfb 0768c33d
...@@ -210,10 +210,10 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git ...@@ -210,10 +210,10 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git
## Delete merged branches ## Delete merged branches
Will delete all branches that are merged into the project's default branch. Deletes all branches that are merged into the project's default branch.
NOTE: NOTE:
[Protected branches](../user/project/protected_branches.md) will not be deleted as part of this operation. [Protected branches](../user/project/protected_branches.md) are not deleted as part of this operation.
```plaintext ```plaintext
DELETE /projects/:id/repository/merged_branches DELETE /projects/:id/repository/merged_branches
......
...@@ -21,11 +21,11 @@ GET /projects/:id/repository/commits ...@@ -21,11 +21,11 @@ GET /projects/:id/repository/commits
| --------- | ---- | -------- | ----------- | | --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
| `ref_name` | string | no | The name of a repository branch, tag or revision range, or if not given the default branch | | `ref_name` | string | no | The name of a repository branch, tag or revision range, or if not given the default branch |
| `since` | string | no | Only commits after or on this date will be returned in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ | | `since` | string | no | Only commits after or on this date are returned in ISO 8601 format `YYYY-MM-DDTHH:MM:SSZ` |
| `until` | string | no | Only commits before or on this date will be returned in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ | | `until` | string | no | Only commits before or on this date are returned in ISO 8601 format `YYYY-MM-DDTHH:MM:SSZ` |
| `path` | string | no | The file path | | `path` | string | no | The file path |
| `all` | boolean | no | Retrieve every commit from the repository | | `all` | boolean | no | Retrieve every commit from the repository |
| `with_stats` | boolean | no | Stats about each commit will be added to the response | | `with_stats` | boolean | no | Stats about each commit are added to the response |
| `first_parent` | boolean | no | Follow only the first parent commit upon seeing a merge commit | | `first_parent` | boolean | no | Follow only the first parent commit upon seeing a merge commit |
| `order` | string | no | List commits in order. Possible values: `default`, [`topo`](https://git-scm.com/docs/git-log#Documentation/git-log.txt---topo-order). Defaults to `default`, the commits are shown in reverse chronological order. | | `order` | string | no | List commits in order. Possible values: `default`, [`topo`](https://git-scm.com/docs/git-log#Documentation/git-log.txt---topo-order). Defaults to `default`, the commits are shown in reverse chronological order. |
...@@ -101,9 +101,9 @@ POST /projects/:id/repository/commits ...@@ -101,9 +101,9 @@ POST /projects/:id/repository/commits
| `action` | string | yes | The action to perform, `create`, `delete`, `move`, `update`, `chmod`| | `action` | string | yes | The action to perform, `create`, `delete`, `move`, `update`, `chmod`|
| `file_path` | string | yes | Full path to the file. Ex. `lib/class.rb` | | `file_path` | string | yes | Full path to the file. Ex. `lib/class.rb` |
| `previous_path` | string | no | Original full path to the file being moved. Ex. `lib/class1.rb`. Only considered for `move` action. | | `previous_path` | string | no | Original full path to the file being moved. Ex. `lib/class1.rb`. Only considered for `move` action. |
| `content` | string | no | File content, required for all except `delete`, `chmod`, and `move`. Move actions that do not specify `content` will preserve the existing file content, and any other value of `content` will overwrite the file content. | | `content` | string | no | File content, required for all except `delete`, `chmod`, and `move`. Move actions that do not specify `content` preserve the existing file content, and any other value of `content` overwrites the file content. |
| `encoding` | string | no | `text` or `base64`. `text` is default. | | `encoding` | string | no | `text` or `base64`. `text` is default. |
| `last_commit_id` | string | no | Last known file commit ID. Will be only considered in update, move, and delete actions. | | `last_commit_id` | string | no | Last known file commit ID. Only considered in update, move, and delete actions. |
| `execute_filemode` | boolean | no | When `true/false` enables/disables the execute flag on the file. Only considered for `chmod` action. | | `execute_filemode` | boolean | no | When `true/false` enables/disables the execute flag on the file. Only considered for `chmod` action. |
```shell ```shell
...@@ -333,7 +333,7 @@ Example response: ...@@ -333,7 +333,7 @@ Example response:
} }
``` ```
In the event of a failed cherry-pick, the response will provide context about In the event of a failed cherry-pick, the response provides context about
why: why:
```json ```json
...@@ -348,9 +348,9 @@ indicates that the commit already exists in the target branch. The other ...@@ -348,9 +348,9 @@ indicates that the commit already exists in the target branch. The other
possible error code is `conflict`, which indicates that there was a merge possible error code is `conflict`, which indicates that there was a merge
conflict. conflict.
When `dry_run` is enabled, the server will attempt to apply the cherry-pick _but When `dry_run` is enabled, the server attempts to apply the cherry-pick _but
not actually commit any resulting changes_. If the cherry-pick applies cleanly, not actually commit any resulting changes_. If the cherry-pick applies cleanly,
the API will respond with `200 OK`: the API responds with `200 OK`:
```json ```json
{ {
...@@ -358,7 +358,7 @@ the API will respond with `200 OK`: ...@@ -358,7 +358,7 @@ the API will respond with `200 OK`:
} }
``` ```
In the event of a failure, you'll see an error identical to a failure without In the event of a failure, an error displays that is identical to a failure without
dry run. dry run.
## Revert a commit ## Revert a commit
...@@ -404,7 +404,7 @@ Example response: ...@@ -404,7 +404,7 @@ Example response:
} }
``` ```
In the event of a failed revert, the response will provide context about why: In the event of a failed revert, the response provides context about why:
```json ```json
{ {
...@@ -417,9 +417,9 @@ In this case, the revert failed because the attempted revert generated a merge ...@@ -417,9 +417,9 @@ In this case, the revert failed because the attempted revert generated a merge
conflict. The other possible error code is `empty`, which indicates that the conflict. The other possible error code is `empty`, which indicates that the
changeset was empty, likely due to the change having already been reverted. changeset was empty, likely due to the change having already been reverted.
When `dry_run` is enabled, the server will attempt to apply the revert _but not When `dry_run` is enabled, the server attempts to apply the revert _but not
actually commit any resulting changes_. If the revert applies cleanly, the API actually commit any resulting changes_. If the revert applies cleanly, the API
will respond with `200 OK`: responds with `200 OK`:
```json ```json
{ {
...@@ -427,7 +427,7 @@ will respond with `200 OK`: ...@@ -427,7 +427,7 @@ will respond with `200 OK`:
} }
``` ```
In the event of a failure, you'll see an error identical to a failure without In the event of a failure, an error displays that is identical to a failure without
dry run. dry run.
## Get the diff of a commit ## Get the diff of a commit
...@@ -511,7 +511,7 @@ In order to post a comment in a particular line of a particular file, you must ...@@ -511,7 +511,7 @@ In order to post a comment in a particular line of a particular file, you must
specify the full commit SHA, the `path`, the `line` and `line_type` should be specify the full commit SHA, the `path`, the `line` and `line_type` should be
`new`. `new`.
The comment will be added at the end of the last commit if at least one of the The comment is added at the end of the last commit if at least one of the
cases below is valid: cases below is valid:
- the `sha` is instead a branch or a tag and the `line` or `path` are invalid - the `sha` is instead a branch or a tag and the `line` or `path` are invalid
......
...@@ -15,7 +15,7 @@ Discussions are a set of related notes on: ...@@ -15,7 +15,7 @@ Discussions are a set of related notes on:
- Merge requests - Merge requests
- Commits - Commits
This includes system notes, which are notes about changes to the object (for example, when a milestone changes, there will be a corresponding system note). Label notes are not part of this API, but recorded as separate events in [resource label events](resource_label_events.md). This includes system notes, which are notes about changes to the object (for example, when a milestone changes, a corresponding system note is added). Label notes are not part of this API, but recorded as separate events in [resource label events](resource_label_events.md).
## Discussions pagination ## Discussions pagination
......
...@@ -388,7 +388,7 @@ You can update project approval rules using the following endpoint: ...@@ -388,7 +388,7 @@ You can update project approval rules using the following endpoint:
PUT /projects/:id/approval_rules/:approval_rule_id PUT /projects/:id/approval_rules/:approval_rule_id
``` ```
**Important:** Approvers and groups not in the `users`/`groups` parameters will be **removed** **Important:** Approvers and groups not in the `users`/`groups` parameters are **removed**
**Parameters:** **Parameters:**
...@@ -516,7 +516,7 @@ the following endpoint: ...@@ -516,7 +516,7 @@ the following endpoint:
PUT /projects/:id/approvers PUT /projects/:id/approvers
``` ```
**Important:** Approvers and groups not in the request will be **removed** **Important:** Approvers and groups not in the request are **removed**
**Parameters:** **Parameters:**
...@@ -784,7 +784,7 @@ the following endpoint: ...@@ -784,7 +784,7 @@ the following endpoint:
PUT /projects/:id/merge_requests/:merge_request_iid/approvers PUT /projects/:id/merge_requests/:merge_request_iid/approvers
``` ```
**Important:** Approvers and groups not in the request will be **removed** **Important:** Approvers and groups not in the request are **removed**
**Parameters:** **Parameters:**
...@@ -855,8 +855,8 @@ You can request information about a merge request's approval state by using the ...@@ -855,8 +855,8 @@ You can request information about a merge request's approval state by using the
GET /projects/:id/merge_requests/:merge_request_iid/approval_state GET /projects/:id/merge_requests/:merge_request_iid/approval_state
``` ```
The `approval_rules_overwritten` will be `true` if the merge request level rules The `approval_rules_overwritten` are `true` if the merge request level rules
are created for the merge request. If there's none, it'll be `false`. are created for the merge request. If there are none, it is `false`.
This includes additional information about the users who have already approved This includes additional information about the users who have already approved
(`approved_by`) and whether a rule is already approved (`approved`). (`approved_by`) and whether a rule is already approved (`approved`).
...@@ -1019,8 +1019,8 @@ POST /projects/:id/merge_requests/:merge_request_iid/approval_rules ...@@ -1019,8 +1019,8 @@ POST /projects/:id/merge_requests/:merge_request_iid/approval_rules
| `group_ids` | Array | no | The ids of groups as approvers | | `group_ids` | Array | no | The ids of groups as approvers |
**Important:** When `approval_project_rule_id` is set, the `name`, `users` and **Important:** When `approval_project_rule_id` is set, the `name`, `users` and
`groups` of project-level rule will be copied. The `approvals_required` specified `groups` of project-level rule are copied. The `approvals_required` specified
will be used. is used.
```json ```json
{ {
...@@ -1091,7 +1091,7 @@ You can update merge request approval rules using the following endpoint: ...@@ -1091,7 +1091,7 @@ You can update merge request approval rules using the following endpoint:
PUT /projects/:id/merge_requests/:merge_request_iid/approval_rules/:approval_rule_id PUT /projects/:id/merge_requests/:merge_request_iid/approval_rules/:approval_rule_id
``` ```
**Important:** Approvers and groups not in the `users`/`groups` parameters will be **removed** **Important:** Approvers and groups not in the `users`/`groups` parameters are **removed**
**Important:** Updating a `report_approver` or `code_owner` rule is not allowed. **Important:** Updating a `report_approver` or `code_owner` rule is not allowed.
These are system generated rules. These are system generated rules.
...@@ -1212,7 +1212,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/approve ...@@ -1212,7 +1212,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/approve
The `sha` parameter works in the same way as The `sha` parameter works in the same way as
when [accepting a merge request](merge_requests.md#accept-mr): if it is passed, then it must when [accepting a merge request](merge_requests.md#accept-mr): if it is passed, then it must
match the current HEAD of the merge request for the approval to be added. If it match the current HEAD of the merge request for the approval to be added. If it
does not match, the response code will be `409`. does not match, the response code is `409`.
```json ```json
{ {
......
...@@ -11,14 +11,14 @@ type: reference, api ...@@ -11,14 +11,14 @@ type: reference, api
## Placeholder tokens ## Placeholder tokens
Badges support placeholders that will be replaced in real time in both the link and image URL. The allowed placeholders are: Badges support placeholders that are replaced in real time in both the link and image URL. The allowed placeholders are:
<!-- vale gitlab.Spelling = NO --> <!-- vale gitlab.Spelling = NO -->
- **%{project_path}**: will be replaced by the project path. - **%{project_path}**: Replaced by the project path.
- **%{project_id}**: will be replaced by the project ID. - **%{project_id}**: Replaced by the project ID.
- **%{default_branch}**: will be replaced by the project default branch. - **%{default_branch}**: Replaced by the project default branch.
- **%{commit_sha}**: will be replaced by the last project's commit SHA. - **%{commit_sha}**: Replaced by the last project's commit SHA.
<!-- vale gitlab.Spelling = YES --> <!-- vale gitlab.Spelling = YES -->
## List all badges of a project ## List all badges of a project
...@@ -162,7 +162,7 @@ Example response: ...@@ -162,7 +162,7 @@ Example response:
## Remove a badge from a project ## Remove a badge from a project
Removes a badge from a project. Only project's badges will be removed by using this endpoint. Removes a badge from a project. Only project badges are removed by using this endpoint.
```plaintext ```plaintext
DELETE /projects/:id/badges/:badge_id DELETE /projects/:id/badges/:badge_id
......
...@@ -50,7 +50,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla ...@@ -50,7 +50,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla
``` ```
NOTE: NOTE:
The upload request will be sent with `Content-Type: application/gzip` header. Ensure that your pre-signed URL includes this as part of the signature. The upload request is sent with `Content-Type: application/gzip` header. Ensure that your pre-signed URL includes this as part of the signature.
## Export status ## Export status
...@@ -138,14 +138,14 @@ POST /projects/import ...@@ -138,14 +138,14 @@ POST /projects/import
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | -------------- | -------- | ---------------------------------------- | | --------- | -------------- | -------- | ---------------------------------------- |
| `namespace` | integer/string | no | The ID or path of the namespace that the project will be imported to. Defaults to the current user's namespace | | `namespace` | integer/string | no | The ID or path of the namespace to import the project to. Defaults to the current user's namespace |
| `name` | string | no | The name of the project to be imported. Defaults to the path of the project if not provided | | `name` | string | no | The name of the project to be imported. Defaults to the path of the project if not provided |
| `file` | string | yes | The file to be uploaded | | `file` | string | yes | The file to be uploaded |
| `path` | string | yes | Name and path for new project | | `path` | string | yes | Name and path for new project |
| `overwrite` | boolean | no | If there is a project with the same path the import will overwrite it. Default to false | | `overwrite` | boolean | no | If there is a project with the same path the import overwrites it. Default to false |
| `override_params` | Hash | no | Supports all fields defined in the [Project API](projects.md) | | `override_params` | Hash | no | Supports all fields defined in the [Project API](projects.md) |
The override parameters passed will take precedence over all values defined inside the export file. The override parameters passed take precedence over all values defined inside the export file.
To upload a file from your file system, use the `--form` argument. This causes To upload a file from your file system, use the `--form` argument. This causes
cURL to post data using the header `Content-Type: multipart/form-data`. cURL to post data using the header `Content-Type: multipart/form-data`.
...@@ -220,7 +220,7 @@ Status can be one of: ...@@ -220,7 +220,7 @@ Status can be one of:
- `started` - `started`
- `finished` - `finished`
If the status is `failed`, it will include the import error message under `import_error`. If the status is `failed`, it includes the import error message under `import_error`.
If the status is `failed`, `started` or `finished`, the `failed_relations` array might If the status is `failed`, `started` or `finished`, the `failed_relations` array might
be populated with any occurrences of relations that failed to import either due to be populated with any occurrences of relations that failed to import either due to
unrecoverable errors or because retries were exhausted (a typical example are query timeouts.) unrecoverable errors or because retries were exhausted (a typical example are query timeouts.)
......
...@@ -16,7 +16,7 @@ This API is a project-specific version of these endpoints: ...@@ -16,7 +16,7 @@ This API is a project-specific version of these endpoints:
- [Issue and merge request templates](../user/project/description_templates.md) - [Issue and merge request templates](../user/project/description_templates.md)
([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37890) in GitLab 13.3) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37890) in GitLab 13.3)
It deprecates these endpoints, which will be removed for API version 5. It deprecates these endpoints, which are scheduled for removal in API version 5.
In addition to templates common to the entire instance, project-specific In addition to templates common to the entire instance, project-specific
templates are also available from this API endpoint. templates are also available from this API endpoint.
......
...@@ -18,7 +18,7 @@ Every API call to vulnerabilities must be [authenticated](README.md#authenticati ...@@ -18,7 +18,7 @@ Every API call to vulnerabilities must be [authenticated](README.md#authenticati
Vulnerability permissions inherit permissions from their project. If a project is Vulnerability permissions inherit permissions from their project. If a project is
private, and a user isn't a member of the project to which the vulnerability private, and a user isn't a member of the project to which the vulnerability
belongs, requests to that project will return a `404 Not Found` status code. belongs, requests to that project returns a `404 Not Found` status code.
## Vulnerabilities pagination ## Vulnerabilities pagination
...@@ -32,7 +32,7 @@ List all of a project's vulnerabilities. ...@@ -32,7 +32,7 @@ List all of a project's vulnerabilities.
If an authenticated user does not have permission to If an authenticated user does not have permission to
[use the Project Security Dashboard](../user/permissions.md#project-members-permissions), [use the Project Security Dashboard](../user/permissions.md#project-members-permissions),
`GET` requests for vulnerabilities of this project will result in a `403` status code. `GET` requests for vulnerabilities of this project result in a `403` status code.
```plaintext ```plaintext
GET /projects/:id/vulnerabilities GET /projects/:id/vulnerabilities
...@@ -109,7 +109,7 @@ Creates a new vulnerability. ...@@ -109,7 +109,7 @@ Creates a new vulnerability.
If an authenticated user does not have a permission to If an authenticated user does not have a permission to
[create a new vulnerability](../user/permissions.md#project-members-permissions), [create a new vulnerability](../user/permissions.md#project-members-permissions),
this request will result in a `403` status code. this request results in a `403` status code.
```plaintext ```plaintext
POST /projects/:id/vulnerabilities?finding_id=<your_finding_id> POST /projects/:id/vulnerabilities?finding_id=<your_finding_id>
...@@ -118,7 +118,7 @@ POST /projects/:id/vulnerabilities?finding_id=<your_finding_id> ...@@ -118,7 +118,7 @@ POST /projects/:id/vulnerabilities?finding_id=<your_finding_id>
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| ------------------- | ----------------- | ---------- | -----------------------------------------------------------------------------------------------------------------------------| | ------------------- | ----------------- | ---------- | -----------------------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) which the authenticated user is a member of | | `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) which the authenticated user is a member of |
| `finding_id` | integer or string | yes | The ID of a Vulnerability Finding from which the new Vulnerability will be created | | `finding_id` | integer or string | yes | The ID of a Vulnerability Finding to create the new Vulnerability from |
The other attributes of a newly created Vulnerability are populated from The other attributes of a newly created Vulnerability are populated from
its source Vulnerability Finding, or with these default values: its source Vulnerability Finding, or with these default values:
......
...@@ -48,14 +48,14 @@ Example response: ...@@ -48,14 +48,14 @@ Example response:
``` ```
NOTE: NOTE:
For security reasons, the `url` attribute will always be scrubbed of username For security reasons, the `url` attribute is always scrubbed of username
and password information. and password information.
## Create a remote mirror ## Create a remote mirror
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24189) in GitLab 12.9. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24189) in GitLab 12.9.
Create a remote mirror for a project. The mirror will be disabled by default. You can enable it by including the optional parameter `enabled` when creating it: Create a remote mirror for a project. The mirror is disabled by default. You can enable it by including the optional parameter `enabled` when creating it:
```plaintext ```plaintext
POST /projects/:id/remote_mirrors POST /projects/:id/remote_mirrors
......
...@@ -26,7 +26,7 @@ PUT /projects/:id/repository/submodules/:submodule ...@@ -26,7 +26,7 @@ PUT /projects/:id/repository/submodules/:submodule
| `submodule` | string | yes | URL-encoded full path to the submodule. For example, `lib%2Fclass%2Erb` | | `submodule` | string | yes | URL-encoded full path to the submodule. For example, `lib%2Fclass%2Erb` |
| `branch` | string | yes | Name of the branch to commit into | | `branch` | string | yes | Name of the branch to commit into |
| `commit_sha` | string | yes | Full commit SHA to update the submodule to | | `commit_sha` | string | yes | Full commit SHA to update the submodule to |
| `commit_message` | string | no | Commit message. If no message is provided, a default one will be set | | `commit_message` | string | no | Commit message. If no message is provided, a default is set |
```shell ```shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/submodules/lib%2Fmodules%2Fexample" \ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/submodules/lib%2Fmodules%2Fexample" \
......
...@@ -26,8 +26,8 @@ GET /search ...@@ -26,8 +26,8 @@ GET /search
| `search` | string | yes | The search query | | `search` | string | yes | The search query |
| `state` | string | no | Filter by state. Issues and merge requests are supported; it is ignored for other scopes. | | `state` | string | no | Filter by state. Issues and merge requests are supported; it is ignored for other scopes. |
| `confidential` | boolean | no | Filter by confidentiality. Issues scope is supported; it is ignored for other scopes. | | `confidential` | boolean | no | Filter by confidentiality. Issues scope is supported; it is ignored for other scopes. |
| `order_by` | string | no | Allowed values are `created_at` only. If this is not set, the results will either be sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.| | `order_by` | string | no | Allowed values are `created_at` only. If this is not set, the results are either sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.|
| `sort` | string | no | Allowed values are `asc` or `desc` only. If this is not set, the results will either be sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.| | `sort` | string | no | Allowed values are `asc` or `desc` only. If this is not set, the results are either sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.|
Search the expression within the specified scope. Currently these scopes are supported: projects, issues, merge_requests, milestones, snippet_titles, users. Search the expression within the specified scope. Currently these scopes are supported: projects, issues, merge_requests, milestones, snippet_titles, users.
...@@ -295,7 +295,7 @@ Example response: ...@@ -295,7 +295,7 @@ Example response:
``` ```
NOTE: NOTE:
`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). `filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` is intended to be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521).
### Scope: commits **(PREMIUM)** ### Scope: commits **(PREMIUM)**
...@@ -371,7 +371,7 @@ Example response: ...@@ -371,7 +371,7 @@ Example response:
``` ```
NOTE: NOTE:
`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the file name and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). `filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` is intended to be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521).
### Scope: notes **(PREMIUM)** ### Scope: notes **(PREMIUM)**
...@@ -434,7 +434,7 @@ Example response: ...@@ -434,7 +434,7 @@ Example response:
Search within the specified group. Search within the specified group.
If a user is not a member of a group and the group is private, a `GET` request on that group will result to a `404` status code. If a user is not a member of a group and the group is private, a `GET` request on that group results in a `404` status code.
```plaintext ```plaintext
GET /groups/:id/search GET /groups/:id/search
...@@ -447,8 +447,8 @@ GET /groups/:id/search ...@@ -447,8 +447,8 @@ GET /groups/:id/search
| `search` | string | yes | The search query | | `search` | string | yes | The search query |
| `state` | string | no | Filter by state. Issues and merge requests are supported; it is ignored for other scopes. | | `state` | string | no | Filter by state. Issues and merge requests are supported; it is ignored for other scopes. |
| `confidential` | boolean | no | Filter by confidentiality. Issues scope is supported; it is ignored for other scopes. | | `confidential` | boolean | no | Filter by confidentiality. Issues scope is supported; it is ignored for other scopes. |
| `order_by` | string | no | Allowed values are `created_at` only. If this is not set, the results will either be sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.| | `order_by` | string | no | Allowed values are `created_at` only. If this is not set, the results are either sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.|
| `sort` | string | no | Allowed values are `asc` or `desc` only. If this is not set, the results will either be sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.| | `sort` | string | no | Allowed values are `asc` or `desc` only. If this is not set, the results are either sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.|
Search the expression within the specified scope. Currently these scopes are supported: projects, issues, merge_requests, milestones, users. Search the expression within the specified scope. Currently these scopes are supported: projects, issues, merge_requests, milestones, users.
...@@ -685,7 +685,7 @@ Example response: ...@@ -685,7 +685,7 @@ Example response:
``` ```
NOTE: NOTE:
`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). `filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` is intended to be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521).
### Scope: commits **(PREMIUM)** ### Scope: commits **(PREMIUM)**
...@@ -761,7 +761,7 @@ Example response: ...@@ -761,7 +761,7 @@ Example response:
``` ```
NOTE: NOTE:
`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the file name and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). `filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` is intended to be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521).
### Scope: notes **(PREMIUM)** ### Scope: notes **(PREMIUM)**
...@@ -824,7 +824,7 @@ Example response: ...@@ -824,7 +824,7 @@ Example response:
Search within the specified project. Search within the specified project.
If a user is not a member of a project and the project is private, a `GET` request on that project will result to a `404` status code. If a user is not a member of a project and the project is private, a `GET` request on that project results in a `404` status code.
```plaintext ```plaintext
GET /projects/:id/search GET /projects/:id/search
...@@ -838,8 +838,8 @@ GET /projects/:id/search ...@@ -838,8 +838,8 @@ GET /projects/:id/search
| `ref` | string | no | The name of a repository branch or tag to search on. The project's default branch is used by default. This is only applicable for scopes: commits, blobs, and wiki_blobs. | | `ref` | string | no | The name of a repository branch or tag to search on. The project's default branch is used by default. This is only applicable for scopes: commits, blobs, and wiki_blobs. |
| `state` | string | no | Filter by state. Issues and merge requests are supported; it is ignored for other scopes. | | `state` | string | no | Filter by state. Issues and merge requests are supported; it is ignored for other scopes. |
| `confidential` | boolean | no | Filter by confidentiality. Issues scope is supported; it is ignored for other scopes. | | `confidential` | boolean | no | Filter by confidentiality. Issues scope is supported; it is ignored for other scopes. |
| `order_by` | string | no | Allowed values are `created_at` only. If this is not set, the results will either be sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.| | `order_by` | string | no | Allowed values are `created_at` only. If this is not set, the results are either sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.|
| `sort` | string | no | Allowed values are `asc` or `desc` only. If this is not set, the results will either be sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.| | `sort` | string | no | Allowed values are `asc` or `desc` only. If this is not set, the results are either sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.|
Search the expression within the specified scope. Currently these scopes are supported: issues, merge_requests, milestones, notes, wiki_blobs, commits, blobs, users. Search the expression within the specified scope. Currently these scopes are supported: issues, merge_requests, milestones, notes, wiki_blobs, commits, blobs, users.
...@@ -1096,7 +1096,7 @@ Example response: ...@@ -1096,7 +1096,7 @@ Example response:
``` ```
NOTE: NOTE:
`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). `filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` are intended to be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521).
### Scope: commits **(PREMIUM)** ### Scope: commits **(PREMIUM)**
...@@ -1178,7 +1178,7 @@ Example response: ...@@ -1178,7 +1178,7 @@ Example response:
``` ```
NOTE: NOTE:
`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). `filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` is intended to be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521).
### Scope: users ### Scope: users
......
...@@ -160,11 +160,10 @@ Example response: ...@@ -160,11 +160,10 @@ Example response:
} }
``` ```
The message will be `null` when creating a lightweight tag otherwise The message is `null` when creating a lightweight tag. Otherwise, it contains the annotation.
it will contain the annotation.
The target will contain the tag objects ID when creating annotated tags, The target contains the tag objects ID when creating annotated tags,
otherwise it will contain the commit ID when creating lightweight tags. otherwise it contains the commit ID when creating lightweight tags.
In case of an error, In case of an error,
status code `405` with an explaining error message is returned. status code `405` with an explaining error message is returned.
......
...@@ -13,7 +13,7 @@ When you create a new branch (in your [terminal](start-using-git.md#create-a-bra ...@@ -13,7 +13,7 @@ When you create a new branch (in your [terminal](start-using-git.md#create-a-bra
[the web interface](../user/project/repository/web_editor.md#create-a-new-branch)), [the web interface](../user/project/repository/web_editor.md#create-a-new-branch)),
you are creating a snapshot of a certain branch, usually the main `master` branch, you are creating a snapshot of a certain branch, usually the main `master` branch,
at its current state. From there, you can start to make your own changes without at its current state. From there, you can start to make your own changes without
affecting the main codebase. The history of your changes will be tracked in your branch. affecting the main codebase. The history of your changes is tracked in your branch.
When your changes are ready, you then merge them into the rest of the codebase with a When your changes are ready, you then merge them into the rest of the codebase with a
[merge request](../user/project/merge_requests/creating_merge_requests.md). [merge request](../user/project/merge_requests/creating_merge_requests.md).
...@@ -35,4 +35,4 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/workflow.html' ...@@ -35,4 +35,4 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/workflow.html'
1. Create a merge request. 1. Create a merge request.
1. Your team lead will review the code &amp; merge it to the main branch. 1. Your team lead reviews the code and merges it to the main branch.
...@@ -9,7 +9,7 @@ type: index ...@@ -9,7 +9,7 @@ type: index
# GitLab basics guides **(FREE)** # GitLab basics guides **(FREE)**
This section provides resources to help you start working with GitLab and Git by focusing This section provides resources to help you start working with GitLab and Git by focusing
on the basic features that you will need to use. on the basic features that you must use.
This documentation is split into the following groups: This documentation is split into the following groups:
...@@ -41,7 +41,7 @@ The following are guides to basic GitLab functionality: ...@@ -41,7 +41,7 @@ The following are guides to basic GitLab functionality:
If you're familiar with Git on the command line, you can interact with your GitLab If you're familiar with Git on the command line, you can interact with your GitLab
projects just as you would with any other Git repository. projects just as you would with any other Git repository.
These resources will help you get further acclimated to working on the command line. These resources can help you get further acclimated to working on the command line.
- [Start using Git on the command line](start-using-git.md), for some simple Git commands. - [Start using Git on the command line](start-using-git.md), for some simple Git commands.
- [Command line basics](command-line-commands.md), to create and edit files using the command line. - [Command line basics](command-line-commands.md), to create and edit files using the command line.
......
...@@ -17,10 +17,10 @@ directly in the browser, you’ll eventually need to use Git through the command ...@@ -17,10 +17,10 @@ directly in the browser, you’ll eventually need to use Git through the command
tasks. tasks.
For example, if you need to fix complex merge conflicts, rebase branches, For example, if you need to fix complex merge conflicts, rebase branches,
merge manually, or undo and roll back commits, you'll need to use Git from merge manually, or undo and roll back commits, you musto use Git from
the command line and then push your changes to the remote server. the command line and then push your changes to the remote server.
This guide will help you get started with Git through the command line and can be your reference This guide helps you get started with Git through the command line and can be your reference
for Git commands in the future. If you're only looking for a quick reference of Git commands, you for Git commands in the future. If you're only looking for a quick reference of Git commands, you
can download the GitLab [Git Cheat Sheet](https://about.gitlab.com/images/press/git-cheat-sheet.pdf). can download the GitLab [Git Cheat Sheet](https://about.gitlab.com/images/press/git-cheat-sheet.pdf).
...@@ -39,12 +39,12 @@ You don't need a GitLab account to use Git locally, but for the purpose of this ...@@ -39,12 +39,12 @@ You don't need a GitLab account to use Git locally, but for the purpose of this
recommend registering and signing into your account before starting. Some commands need a recommend registering and signing into your account before starting. Some commands need a
connection between the files in your computer and their version on a remote server. connection between the files in your computer and their version on a remote server.
You'll also need to open a [command shell](#command-shell) and have You must also open a [command shell](#command-shell) and have
[Git installed](#install-git) in your computer. [Git installed](#install-git) in your computer.
### Command shell ### Command shell
To execute Git commands in your computer, you'll need to open a command shell (also known as command To execute Git commands in your computer, you must open a command shell (also known as command
prompt, terminal, and command line) of your preference. Here are some suggestions: prompt, terminal, and command line) of your preference. Here are some suggestions:
- For macOS users: - For macOS users:
...@@ -66,18 +66,18 @@ computer: ...@@ -66,18 +66,18 @@ computer:
git --version git --version
``` ```
If you have Git installed, the output will be: If you have Git installed, the output is:
```shell ```shell
git version X.Y.Z git version X.Y.Z
``` ```
If your computer doesn't recognize `git` as a command, you'll need to [install Git](../topics/git/how_to_install_git/index.md). If your computer doesn't recognize `git` as a command, you must [install Git](../topics/git/how_to_install_git/index.md).
After that, run `git --version` again to verify whether it was correctly installed. After that, run `git --version` again to verify whether it was correctly installed.
## Configure Git ## Configure Git
To start using Git from your computer, you'll need to enter your credentials (user name and email) To start using Git from your computer, you must enter your credentials (user name and email)
to identify you as the author of your work. The user name and email should match the ones you're to identify you as the author of your work. The user name and email should match the ones you're
using on GitLab. using on GitLab.
...@@ -100,7 +100,7 @@ git config --global --list ...@@ -100,7 +100,7 @@ git config --global --list
``` ```
The `--global` option tells Git to always use this information for anything you do on your system. The `--global` option tells Git to always use this information for anything you do on your system.
If you omit `--global` or use `--local`, the configuration will be applied only to the current If you omit `--global` or use `--local`, the configuration is applied only to the current
repository. repository.
You can read more on how Git manages configurations in the You can read more on how Git manages configurations in the
...@@ -113,7 +113,7 @@ You have two options: ...@@ -113,7 +113,7 @@ You have two options:
- Authenticate on a project-by-project basis through HTTPS, and enter your credentials every time - Authenticate on a project-by-project basis through HTTPS, and enter your credentials every time
you perform an operation between your computer and GitLab. you perform an operation between your computer and GitLab.
- Authenticate through SSH once and GitLab won't ask your credentials every time you pull, push, - Authenticate through SSH once and GitLab no longer requests your credentials every time you pull, push,
and clone. and clone.
To start the authentication process, we'll [clone](#clone-a-repository) an existing repository To start the authentication process, we'll [clone](#clone-a-repository) an existing repository
...@@ -121,8 +121,8 @@ to our computer: ...@@ -121,8 +121,8 @@ to our computer:
- If you want to use **SSH** to authenticate, follow the instructions on the [SSH documentation](../ssh/README.md) - If you want to use **SSH** to authenticate, follow the instructions on the [SSH documentation](../ssh/README.md)
to set it up before cloning. to set it up before cloning.
- If you want to use **HTTPS**, GitLab will request your user name and password: - If you want to use **HTTPS**, GitLab requests your user name and password:
- If you have 2FA enabled for your account, you'll have to use a [Personal Access Token](../user/profile/personal_access_tokens.md) - If you have 2FA enabled for your account, you must use a [Personal Access Token](../user/profile/personal_access_tokens.md)
with **read_repository** or **write_repository** permissions instead of your account's password. with **read_repository** or **write_repository** permissions instead of your account's password.
Create one before cloning. Create one before cloning.
- If you don't have 2FA enabled, use your account's password. - If you don't have 2FA enabled, use your account's password.
...@@ -161,11 +161,11 @@ Often, the word "repository" is shortened to "repo". ...@@ -161,11 +161,11 @@ Often, the word "repository" is shortened to "repo".
### Fork ### Fork
When you want to copy someone else's repository, you [**fork**](../user/project/repository/forking_workflow.md#creating-a-fork) When you want to copy someone else's repository, you [**fork**](../user/project/repository/forking_workflow.md#creating-a-fork)
the project. By forking it, you'll create a copy of the project into your own the project. By forking it, you create a copy of the project into your own
namespace to have read and write permissions to modify the project files namespace to have read and write permissions to modify the project files
and settings. and settings.
For example, if you fork this project, <https://gitlab.com/gitlab-tests/sample-project/> into your namespace, you'll create your own copy of the repository in your namespace (`https://gitlab.com/your-namespace/sample-project/`). From there, you can clone it into your computer, For example, if you fork this project, <https://gitlab.com/gitlab-tests/sample-project/> into your namespace, you create your own copy of the repository in your namespace (`https://gitlab.com/your-namespace/sample-project/`). From there, you can clone it into your computer,
work on its files, and (optionally) submit proposed changes back to the work on its files, and (optionally) submit proposed changes back to the
original repository if you'd like. original repository if you'd like.
...@@ -185,19 +185,19 @@ After you saved a local copy of a repository and modified its files on your comp ...@@ -185,19 +185,19 @@ After you saved a local copy of a repository and modified its files on your comp
changes to GitLab. This is referred to as **pushing** to GitLab, as this is achieved by the command changes to GitLab. This is referred to as **pushing** to GitLab, as this is achieved by the command
[`git push`](#send-changes-to-gitlabcom). [`git push`](#send-changes-to-gitlabcom).
When the remote repository changes, your local copy will be behind it. You can update it with the new When the remote repository changes, your local copy is behind it. You can update it with the new
changes in the remote repository. changes in the remote repository.
This is referred to as **pulling** from GitLab, as this is achieved by the command This is referred to as **pulling** from GitLab, as this is achieved by the command
[`git pull`](#download-the-latest-changes-in-the-project). [`git pull`](#download-the-latest-changes-in-the-project).
## Basic Git commands ## Basic Git commands
For the purposes of this guide, we will use this example project on GitLab.com: For the purposes of this guide, we use this example project on GitLab.com:
[https://gitlab.com/gitlab-tests/sample-project/](https://gitlab.com/gitlab-tests/sample-project/). [https://gitlab.com/gitlab-tests/sample-project/](https://gitlab.com/gitlab-tests/sample-project/).
To use it, log into GitLab.com and fork the example project into your To use it, log into GitLab.com and fork the example project into your
namespace to have your own copy to playing with. Your sample namespace to have your own copy to playing with. Your sample
project will be available under `https://gitlab.com/<your-namespace>/sample-project/`. project is available under `https://gitlab.com/<your-namespace>/sample-project/`.
You can also choose any other project to follow this guide. Then, replace the You can also choose any other project to follow this guide. Then, replace the
example URLs with your own project's. example URLs with your own project's.
...@@ -213,7 +213,7 @@ To start working locally on an existing remote repository, clone it with the ...@@ -213,7 +213,7 @@ To start working locally on an existing remote repository, clone it with the
command `git clone <repository path>`. You can either clone it via [HTTPS](#clone-via-https) or [SSH](#clone-via-ssh), according to your preferred [authentication method](#git-authentication-methods). command `git clone <repository path>`. You can either clone it via [HTTPS](#clone-via-https) or [SSH](#clone-via-ssh), according to your preferred [authentication method](#git-authentication-methods).
You can find both paths (HTTPS and SSH) by navigating to your project's landing page You can find both paths (HTTPS and SSH) by navigating to your project's landing page
and clicking **Clone**. GitLab will prompt you with both paths, from which you can copy and clicking **Clone**. GitLab prompts you with both paths, from which you can copy
and paste in your command line. and paste in your command line.
For example, considering our [sample project](https://gitlab.com/gitlab-tests/sample-project/): For example, considering our [sample project](https://gitlab.com/gitlab-tests/sample-project/):
...@@ -224,7 +224,7 @@ For example, considering our [sample project](https://gitlab.com/gitlab-tests/sa ...@@ -224,7 +224,7 @@ For example, considering our [sample project](https://gitlab.com/gitlab-tests/sa
To get started, open a terminal window in the directory you wish to add the To get started, open a terminal window in the directory you wish to add the
repository files into, and run one of the `git clone` commands as described below. repository files into, and run one of the `git clone` commands as described below.
Both commands will download a copy of the files in a folder named after the project's Both commands download a copy of the files in a folder named after the project's
name and preserve the connection with the remote repository. name and preserve the connection with the remote repository.
You can then navigate to the new directory with `cd sample-project` and start working on it You can then navigate to the new directory with `cd sample-project` and start working on it
locally. locally.
...@@ -253,8 +253,8 @@ git clone git@gitlab.com:gitlab-org/gitlab.git ...@@ -253,8 +253,8 @@ git clone git@gitlab.com:gitlab-org/gitlab.git
### Convert a local directory into a repository ### Convert a local directory into a repository
When you have your files in a local folder and want to convert it into When you have your files in a local folder and want to convert it into
a repository, you'll need to _initialize_ the folder through the `git init` a repository, you must _initialize_ the folder through the `git init`
command. This will instruct Git to begin to track that directory as a command. This instructs Git to begin to track that directory as a
repository. To do so, open the terminal on the directory you'd like to convert repository. To do so, open the terminal on the directory you'd like to convert
and run: and run:
...@@ -271,9 +271,9 @@ so that Git can upload your files into the correct project. ...@@ -271,9 +271,9 @@ so that Git can upload your files into the correct project.
#### Add a remote repository #### Add a remote repository
By "adding a remote repository" to your local directory you'll tell Git that By "adding a remote repository" to your local directory you tell Git that
the path to that specific project in GitLab corresponds to that specific the path to that specific project in GitLab corresponds to that specific
folder you have in your computer. This way, your local folder will be folder you have in your computer. This way, your local folder is
identified by Git as the local content for that specific remote project. identified by Git as the local content for that specific remote project.
To add a remote repository to your local copy: To add a remote repository to your local copy:
...@@ -320,7 +320,7 @@ The `-v` flag stands for verbose. ...@@ -320,7 +320,7 @@ The `-v` flag stands for verbose.
## Branching ## Branching
If you want to add code to a project but you're not sure if it will work properly, or you're If you want to add code to a project but you're not sure if it works properly, or you're
collaborating on the project with others, and don't want your work to get mixed up, it's a good idea collaborating on the project with others, and don't want your work to get mixed up, it's a good idea
to work on a different **branch**. to work on a different **branch**.
...@@ -384,7 +384,7 @@ git diff ...@@ -384,7 +384,7 @@ git diff
### Add and commit local changes ### Add and commit local changes
You'll see any local changes in red when you type `git status`. These changes may Local changes are shown in red when you type `git status`. These changes may
be new, modified, or deleted files/folders. Use `git add` to first stage (prepare) be new, modified, or deleted files/folders. Use `git add` to first stage (prepare)
a local file/folder for committing. Then use `git commit` to commit (save) the staged a local file/folder for committing. Then use `git commit` to commit (save) the staged
files: files:
...@@ -420,8 +420,8 @@ For example, to push your local commits to the _`master`_ branch of the _`origin ...@@ -420,8 +420,8 @@ For example, to push your local commits to the _`master`_ branch of the _`origin
git push origin master git push origin master
``` ```
On certain occasions, Git won't allow you to push to your repository, and then On certain occasions, Git disallows pushes to your repository, and then
you'll need to [force an update](../topics/git/git_rebase.md#force-push). you must [force an update](../topics/git/git_rebase.md#force-push).
NOTE: NOTE:
To create a merge request from a fork to an upstream repository, see the To create a merge request from a fork to an upstream repository, see the
......
...@@ -56,7 +56,7 @@ In this case, the feature branch would be `release-X-Y`. Assuming the `release-X ...@@ -56,7 +56,7 @@ In this case, the feature branch would be `release-X-Y`. Assuming the `release-X
![Create merge request](img/create_merge_request_v13_1.png) ![Create merge request](img/create_merge_request_v13_1.png)
1. After you click **Create merge request**, you'll see an option to **Change branches**. Select that option. 1. After you click **Create merge request**, an option to **Change branches** displays. Select that option.
1. In the **New Merge Request** screen, you can now select the **Source** and **Target** branches. 1. In the **New Merge Request** screen, you can now select the **Source** and **Target** branches.
In the screenshot shown, In the screenshot shown,
...@@ -73,10 +73,10 @@ we have selected `test-branch` as the source, and `release-13-0` as the target. ...@@ -73,10 +73,10 @@ we have selected `test-branch` as the source, and `release-13-0` as the target.
From test-branch into release-13-0 From test-branch into release-13-0
``` ```
An entry like this confirms that your MR will **not** merge into master. An entry like this confirms your merge request's destination.
1. Make any additional changes in the **New Merge Request** screen, and click **Submit merge request**. 1. Make any additional changes in the **New Merge Request** screen, and click **Submit merge request**.
1. In the new merge request, look for **Request to merge**. You'll see an entry similar to: 1. In the new merge request, look for **Request to merge**. An entry similar to this displays:
```plaintext ```plaintext
Request to merge test-branch into release-13-0 Request to merge test-branch into release-13-0
......
...@@ -9,9 +9,9 @@ type: howto ...@@ -9,9 +9,9 @@ type: howto
# Installing Git **(FREE)** # Installing Git **(FREE)**
To begin contributing to GitLab projects, To begin contributing to GitLab projects,
you will need to install the Git client on your computer. you must install the Git client on your computer.
This article will show you how to install Git on macOS, Ubuntu Linux and Windows. This article shows you how to install Git on macOS, Ubuntu Linux and Windows.
Information on [installing Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) Information on [installing Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
is also available at the official Git website. is also available at the official Git website.
......
...@@ -22,7 +22,7 @@ More information is also available on the [Git website](https://git-scm.com). ...@@ -22,7 +22,7 @@ More information is also available on the [Git website](https://git-scm.com).
## Getting started ## Getting started
The following resources will help you get started with Git: The following resources can help you get started with Git:
- [Git-ing started with Git](https://www.youtube.com/watch?v=Ce5nz5n41z4), - [Git-ing started with Git](https://www.youtube.com/watch?v=Ce5nz5n41z4),
a video introduction to Git. a video introduction to Git.
......
...@@ -23,13 +23,13 @@ Git 2.22.0 or later is required. ...@@ -23,13 +23,13 @@ Git 2.22.0 or later is required.
> [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/2553) in GitLab 12.10. > [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/2553) in GitLab 12.10.
Storing large binary files in Git is normally discouraged, because every large Storing large binary files in Git is normally discouraged, because every large
file added will be downloaded by everyone who clones or fetches changes file added is downloaded by everyone who clones or fetches changes
thereafter. This is slow, if not a complete obstruction when working from a slow thereafter. This is slow, if not a complete obstruction when working from a slow
or unreliable internet connection. or unreliable internet connection.
Using partial clone with a file size filter solves this problem, by excluding Using partial clone with a file size filter solves this problem, by excluding
troublesome large files from clones and fetches. When Git encounters a missing troublesome large files from clones and fetches. When Git encounters a missing
file, it will be downloaded on demand. file, it's downloaded on demand.
When cloning a repository, use the `--filter=blob:limit=<size>` argument. For example, When cloning a repository, use the `--filter=blob:limit=<size>` argument. For example,
to clone the repository excluding files larger than 1 megabyte: to clone the repository excluding files larger than 1 megabyte:
...@@ -58,7 +58,7 @@ Updating files: 100% (13008/13008), done. ...@@ -58,7 +58,7 @@ Updating files: 100% (13008/13008), done.
Filtering content: 100% (3/3), 131.24 MiB | 4.65 MiB/s, done. Filtering content: 100% (3/3), 131.24 MiB | 4.65 MiB/s, done.
``` ```
The output will be longer because Git will first clone the repository excluding The output is longer because Git first clones the repository excluding
files larger than 1 megabyte, and second download any missing large files needed files larger than 1 megabyte, and second download any missing large files needed
to checkout the `master` branch. to checkout the `master` branch.
...@@ -109,8 +109,8 @@ For more details, see the Git documentation for ...@@ -109,8 +109,8 @@ For more details, see the Git documentation for
## Filter by file path ## Filter by file path
WARNING: WARNING:
Partial Clone using `sparse` filters is experimental, slow, and will Partial Clone using `sparse` filters is experimental, slow, and
significantly increase Gitaly resource utilization when cloning and fetching. significantly increases Gitaly resource utilization when cloning and fetching.
Deeper integration between Partial Clone and Sparse Checkout is being explored Deeper integration between Partial Clone and Sparse Checkout is being explored
through the `--filter=sparse:oid=<blob-ish>` filter spec, but this is highly through the `--filter=sparse:oid=<blob-ish>` filter spec, but this is highly
...@@ -143,7 +143,7 @@ For more details, see the Git documentation for ...@@ -143,7 +143,7 @@ For more details, see the Git documentation for
``` ```
1. **Create a new Git repository and fetch.** Support for `--filter=sparse:oid` 1. **Create a new Git repository and fetch.** Support for `--filter=sparse:oid`
using the clone command is incomplete, so we will emulate the clone command using the clone command is incomplete, so we emulate the clone command
by hand, using `git init` and `git fetch`. Follow by hand, using `git init` and `git fetch`. Follow
[issue tracking support for `--filter=sparse:oid`](https://gitlab.com/gitlab-org/git/-/issues/4) [issue tracking support for `--filter=sparse:oid`](https://gitlab.com/gitlab-org/git/-/issues/4)
for updates. for updates.
...@@ -171,7 +171,7 @@ For more details, see the Git documentation for ...@@ -171,7 +171,7 @@ For more details, see the Git documentation for
WARNING: WARNING:
Git integrations with `bash`, `zsh`, etc and editors that automatically Git integrations with `bash`, `zsh`, etc and editors that automatically
show Git status information often run `git fetch` which will fetch the show Git status information often run `git fetch` which fetches the
entire repository. You many need to disable or reconfigure these entire repository. You many need to disable or reconfigure these
integrations. integrations.
......
...@@ -36,9 +36,9 @@ GitLab supports two different modes of file locking: ...@@ -36,9 +36,9 @@ GitLab supports two different modes of file locking:
Locks can be created by any person who has at least Locks can be created by any person who has at least
[Developer permissions](../permissions.md) to the repository. [Developer permissions](../permissions.md) to the repository.
Only the user who locked the file or directory can edit locked files. Others Only the user who locked the file or directory can edit locked files. Other
users will be prevented from modifying locked files by pushing, merging, users are prevented from modifying locked files by pushing, merging,
or any other means, and will be shown an error like: `The path '.gitignore' is or any other means, and are shown an error like: `The path '.gitignore' is
locked by Administrator`. locked by Administrator`.
## Exclusive file locks **(FREE)** ## Exclusive file locks **(FREE)**
...@@ -60,7 +60,7 @@ Before getting started, make sure you have [Git LFS installed](../../topics/git/ ...@@ -60,7 +60,7 @@ Before getting started, make sure you have [Git LFS installed](../../topics/git/
git-lfs --version git-lfs --version
``` ```
If it doesn't recognize this command, you'll have to install it. There are If it doesn't recognize this command, you must install it. There are
several [installation methods](https://git-lfs.github.com/) that you can several [installation methods](https://git-lfs.github.com/) that you can
choose according to your OS. To install it with Homebrew: choose according to your OS. To install it with Homebrew:
...@@ -70,7 +70,7 @@ brew install git-lfs ...@@ -70,7 +70,7 @@ brew install git-lfs
Once installed, **open your local repository in a terminal window** and Once installed, **open your local repository in a terminal window** and
install Git LFS in your repository. If you're sure that LFS is already installed, install Git LFS in your repository. If you're sure that LFS is already installed,
you can skip this step. If you're unsure, re-installing it won't do any harm: you can skip this step. If you're unsure, re-installing it does no harm:
```shell ```shell
git lfs install git lfs install
...@@ -84,14 +84,14 @@ You need [Maintainer permissions](../permissions.md) to configure ...@@ -84,14 +84,14 @@ You need [Maintainer permissions](../permissions.md) to configure
Exclusive File Locks for your project through the command line. Exclusive File Locks for your project through the command line.
The first thing to do before using File Locking is to tell Git LFS which The first thing to do before using File Locking is to tell Git LFS which
kind of files are lockable. The following command will store PNG files kind of files are lockable. The following command stores PNG files
in LFS and flag them as lockable: in LFS and flag them as lockable:
```shell ```shell
git lfs track "*.png" --lockable git lfs track "*.png" --lockable
``` ```
After executing the above command a file named `.gitattributes` will be After executing the above command a file named `.gitattributes` is
created or updated with the following content: created or updated with the following content:
```shell ```shell
...@@ -110,9 +110,9 @@ implements the LFS File Locking API). To do that you can edit the ...@@ -110,9 +110,9 @@ implements the LFS File Locking API). To do that you can edit the
The `.gitattributes` file is key to the process and **must** The `.gitattributes` file is key to the process and **must**
be pushed to the remote repository for the changes to take effect. be pushed to the remote repository for the changes to take effect.
After a file type has been registered as lockable, Git LFS will make After a file type has been registered as lockable, Git LFS makes
them read-only on the file system automatically. This means you will them read-only on the file system automatically. This means you
need to **lock the file** before [editing it](#edit-lockable-files). must **lock the file** before [editing it](#edit-lockable-files).
### Lock files ### Lock files
...@@ -168,7 +168,7 @@ git lfs locks ...@@ -168,7 +168,7 @@ git lfs locks
The output lists the locked files followed by the user who locked each of them The output lists the locked files followed by the user who locked each of them
and the files' IDs. and the files' IDs.
On the repository file tree, GitLab will display an LFS badge for files On the repository file tree, GitLab displays an LFS badge for files
tracked by Git LFS plus a padlock icon on exclusively-locked files: tracked by Git LFS plus a padlock icon on exclusively-locked files:
![LFS-Locked files](img/lfs_locked_files_v13_2.png) ![LFS-Locked files](img/lfs_locked_files_v13_2.png)
...@@ -176,7 +176,7 @@ tracked by Git LFS plus a padlock icon on exclusively-locked files: ...@@ -176,7 +176,7 @@ tracked by Git LFS plus a padlock icon on exclusively-locked files:
You can also [view and remove existing locks](#view-and-remove-existing-locks) from the GitLab UI. You can also [view and remove existing locks](#view-and-remove-existing-locks) from the GitLab UI.
NOTE: NOTE:
When you rename an exclusively-locked file, the lock is lost. You'll have to When you rename an exclusively-locked file, the lock is lost. You must
lock it again to keep it locked. lock it again to keep it locked.
### Edit lockable files ### Edit lockable files
...@@ -204,7 +204,7 @@ or higher tiers. ...@@ -204,7 +204,7 @@ or higher tiers.
Default branch file and directory locks only apply to the default branch set in Default branch file and directory locks only apply to the default branch set in
the project's settings (usually `master`). the project's settings (usually `master`).
Changes to locked files on the default branch will be blocked, including merge Changes to locked files on the default branch are blocked, including merge
requests that modify locked files. Unlock the file to allow changes. requests that modify locked files. Unlock the file to allow changes.
### Lock a file or a directory ### Lock a file or a directory
...@@ -216,10 +216,10 @@ To lock a file: ...@@ -216,10 +216,10 @@ To lock a file:
![Locking file](img/file_lock.png) ![Locking file](img/file_lock.png)
An **Unlock** button will be displayed if the file is already locked, and An **Unlock** button is displayed if the file is already locked, and
will be disabled if you do not have permission to unlock the file. is disabled if you do not have permission to unlock the file.
If you did not lock the file, hovering your cursor over the button will show If you did not lock the file, hovering your cursor over the button shows
who locked the file. who locked the file.
### View and remove existing locks ### View and remove existing locks
......
...@@ -17,7 +17,7 @@ directory of your repository and push it to the default branch of your project. ...@@ -17,7 +17,7 @@ directory of your repository and push it to the default branch of your project.
## Encoding Requirements ## Encoding Requirements
The `.gitattributes` file _must_ be encoded in UTF-8 and _must not_ contain a The `.gitattributes` file _must_ be encoded in UTF-8 and _must not_ contain a
Byte Order Mark. If a different encoding is used, the file's contents will be Byte Order Mark. If a different encoding is used, the file's contents are
ignored. ignored.
## Syntax Highlighting ## Syntax Highlighting
......
...@@ -17,7 +17,7 @@ to accept merge requests without creating merge commits. ...@@ -17,7 +17,7 @@ to accept merge requests without creating merge commits.
When the fast-forward merge When the fast-forward merge
([`--ff-only`](https://git-scm.com/docs/git-merge#git-merge---ff-only)) setting ([`--ff-only`](https://git-scm.com/docs/git-merge#git-merge---ff-only)) setting
is enabled, no merge commits will be created and all merges are fast-forwarded, is enabled, no merge commits are created and all merges are fast-forwarded,
which means that merging is only allowed if the branch can be fast-forwarded. which means that merging is only allowed if the branch can be fast-forwarded.
When a fast-forward merge is not possible, the user is given the option to rebase. When a fast-forward merge is not possible, the user is given the option to rebase.
...@@ -28,19 +28,19 @@ When a fast-forward merge is not possible, the user is given the option to rebas ...@@ -28,19 +28,19 @@ When a fast-forward merge is not possible, the user is given the option to rebas
1. Select the **Fast-forward merge** option 1. Select the **Fast-forward merge** option
1. Hit **Save changes** for the changes to take effect 1. Hit **Save changes** for the changes to take effect
Now, when you visit the merge request page, you will be able to accept it Now, when you visit the merge request page, you can accept it
**only if a fast-forward merge is possible**. **only if a fast-forward merge is possible**.
![Fast forward merge request](img/ff_merge_mr.png) ![Fast forward merge request](img/ff_merge_mr.png)
If a fast-forward merge is not possible but a conflict free rebase is possible, If a fast-forward merge is not possible but a conflict free rebase is possible,
a rebase button will be offered. a rebase button is offered.
![Fast forward merge request](img/ff_merge_rebase.png) ![Fast forward merge request](img/ff_merge_rebase.png)
If the target branch is ahead of the source branch and a conflict free rebase is If the target branch is ahead of the source branch and a conflict free rebase is
not possible, you need to rebase the not possible, you need to rebase the
source branch locally before you will be able to do a fast-forward merge. source branch locally before you can do a fast-forward merge.
![Fast forward merge rebase locally](img/ff_merge_rebase_locally.png) ![Fast forward merge rebase locally](img/ff_merge_rebase_locally.png)
......
...@@ -79,7 +79,7 @@ An individual user can be added as an approver for a project if they are a membe ...@@ -79,7 +79,7 @@ An individual user can be added as an approver for a project if they are a membe
- The project's immediate parent group. - The project's immediate parent group.
- A group that has access to the project via a [share](../members/share_project_with_groups.md). - A group that has access to the project via a [share](../members/share_project_with_groups.md).
A group of users can also be added as approvers, though they will only count as approvers if A group of users can also be added as approvers, though they only count as approvers if
they have direct membership to the group. In the future, group approvers may be they have direct membership to the group. In the future, group approvers may be
[restricted to only groups with share access to the project](https://gitlab.com/gitlab-org/gitlab/-/issues/2048). [restricted to only groups with share access to the project](https://gitlab.com/gitlab-org/gitlab/-/issues/2048).
......
...@@ -31,7 +31,7 @@ NOTE: ...@@ -31,7 +31,7 @@ NOTE:
The squashed commit in this example is followed by a merge commit, because the merge method for this repository uses a merge commit. You can disable merge commits in The squashed commit in this example is followed by a merge commit, because the merge method for this repository uses a merge commit. You can disable merge commits in
**Project Settings > General > Merge requests > Merge method > Fast-forward merge**. **Project Settings > General > Merge requests > Merge method > Fast-forward merge**.
The squashed commit's commit message will be either: The squashed commit's commit message is either:
- Taken from the first multi-line commit message in the merge. - Taken from the first multi-line commit message in the merge.
- The merge request's title if no multi-line commit message is found. - The merge request's title if no multi-line commit message is found.
...@@ -60,7 +60,7 @@ This way, the history of your base branch remains clean with ...@@ -60,7 +60,7 @@ This way, the history of your base branch remains clean with
meaningful commit messages and: meaningful commit messages and:
- It's simpler to [revert](revert_changes.md) if necessary. - It's simpler to [revert](revert_changes.md) if necessary.
- The merged branch will retain the full commit history. - The merged branch retains the full commit history.
## Enabling squash for a merge request ## Enabling squash for a merge request
...@@ -113,18 +113,18 @@ squashing can itself be considered equivalent to rebasing. ...@@ -113,18 +113,18 @@ squashing can itself be considered equivalent to rebasing.
With Squash Commits Options you can configure the behavior of Squash and Merge for your project. With Squash Commits Options you can configure the behavior of Squash and Merge for your project.
To set it up, navigate to your project's **Settings > General** and expand **Merge requests**. To set it up, navigate to your project's **Settings > General** and expand **Merge requests**.
You will find the following options to choose, which will affect existing and new merge requests You can choose from these options, which affect existing and new merge requests
submitted to your project: submitted to your project:
- **Do not allow**: users cannot use Squash and Merge to squash all the commits immediately before - **Do not allow**: users cannot use Squash and Merge to squash all the commits immediately before
merging. The checkbox to enable or disable it will be unchecked and hidden from the users. merging. The checkbox to enable or disable it is unchecked and hidden from the users.
- **Allow**: users will have the option to enable Squash and Merge on a merge request basis. - **Allow**: users can enable Squash and Merge on a merge request basis.
The checkbox will be unchecked (disabled) by default, but and the user is allowed to enable it. The checkbox is unchecked (disabled) by default, but and the user is allowed to enable it.
- **Encourage**: users will have the option to enable Squash and Merge on a merge request basis. - **Encourage**: users can enable Squash and Merge on a merge request basis.
The checkbox will be checked (enabled) by default to encourage its use, but the user is allowed to The checkbox is checked (enabled) by default to encourage its use, but the user is allowed to
disable it. disable it.
- **Require**: Squash and Merge is enabled for all merge requests, so it will always be performed. - **Require**: Squash and Merge is enabled for all merge requests, so it is always performed.
The checkbox to enable or disable it will be checked and hidden from the users. The checkbox to enable or disable it is checked and hidden from the users.
The Squash and Merge checkbox is displayed when you create a merge request and when you edit the description of an existing one, except when Squash Commit Options is set to **Do not allow** or **Require**. The Squash and Merge checkbox is displayed when you create a merge request and when you edit the description of an existing one, except when Squash Commit Options is set to **Do not allow** or **Require**.
......
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