diff options
Diffstat (limited to 'doc/api/repositories.md')
| -rw-r--r-- | doc/api/repositories.md | 346 |
1 files changed, 21 insertions, 325 deletions
diff --git a/doc/api/repositories.md b/doc/api/repositories.md index dcbb5d14741..a34fde54e90 100644 --- a/doc/api/repositories.md +++ b/doc/api/repositories.md @@ -20,7 +20,7 @@ command. For more information, refer to the section in the Git internals documentation. WARNING: -This endpoint changed to [keyset-based pagination](index.md#keyset-based-pagination) +This endpoint changed to [keyset-based pagination](rest/index.md#keyset-based-pagination) in GitLab 15.0. Iterating pages of results with a number (`?page=2`) is unsupported. ```plaintext @@ -31,11 +31,11 @@ Supported attributes: | Attribute | Type | Required | Description | | :---------- | :------------- | :------- | :---------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `page_token` | string | no | The tree record ID at which to fetch the next page. Used only with keyset pagination. | -| `pagination` | string | no | If `keyset`, use the [keyset-based pagination method](index.md#keyset-based-pagination). | +| `pagination` | string | no | If `keyset`, use the [keyset-based pagination method](rest/index.md#keyset-based-pagination). | | `path` | string | no | The path inside the repository. Used to get content of subdirectories. | -| `per_page` | integer | no | Number of results to show per page. If not specified, defaults to `20`. [Learn more on pagination](index.md#pagination). | +| `per_page` | integer | no | Number of results to show per page. If not specified, defaults to `20`. For more information, see [Pagination](rest/index.md#pagination). | | `recursive` | boolean | no | Boolean value used to get a recursive tree. Default is `false`. | | `ref` | string | no | The name of a repository branch or tag or, if not given, the default branch. | @@ -107,7 +107,7 @@ Supported attributes: | Attribute | Type | Required | Description | | :-------- | :------------- | :------- | :---------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `sha` | string | yes | The blob SHA. | ## Raw blob content @@ -123,7 +123,7 @@ Supported attributes: | Attribute | Type | Required | Description | | :-------- | :------- | :------- | :---------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `sha` | string | yes | The blob SHA. | ## Get file archive @@ -157,7 +157,7 @@ Supported attributes: | Attribute | Type | Required | Description | |:------------|:---------------|:---------|:----------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `path` | string | no | The subpath of the repository to download. If an empty string, defaults to the whole repository. | | `sha` | string | no | The commit SHA to download. A tag, branch reference, or SHA can be used. If not specified, defaults to the tip of the default branch. | @@ -181,7 +181,7 @@ Supported attributes: | Attribute | Type | Required | Description | | :--------- | :------------- | :------- | :---------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `from` | string | yes | The commit SHA or branch name. | | `to` | string | yes | The commit SHA or branch name. | | `from_project_id` | integer | no | The ID to compare from. | @@ -243,7 +243,7 @@ Supported attributes: | Attribute | Type | Required | Description | | :--------- | :------------- | :------- | :---------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `order_by` | string | no | Return contributors ordered by `name`, `email`, or `commits` (orders by commit date) fields. Default is `commits`. | | `sort` | string | no | Return contributors sorted in `asc` or `desc` order. Default is `asc`. | @@ -275,7 +275,7 @@ GET /projects/:id/repository/merge_base | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ---------------------------------------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `refs` | array | yes | The refs to find the common ancestor of. Accepts multiple refs. | Example request: @@ -316,11 +316,15 @@ of commits, GitLab generates a changelog for all commits that use a particular a new Markdown-formatted section to a changelog file in the Git repository of the project. The output format can be customized. +For user-facing documentation, see [Changelogs](../user/project/changelogs.md). + ```plaintext POST /projects/:id/repository/changelog ``` -Supported attributes: +### Supported attributes + +Changelogs support these attributes: | Attribute | Type | Required | Description | | :-------- | :------- | :--------- | :---------- | @@ -403,319 +407,6 @@ To store the results in a different file, use the `file` parameter: curl --request POST --header "PRIVATE-TOKEN: token" --data "version=1.0.0&file=NEWS" "https://gitlab.com/api/v4/projects/42/repository/changelog" ``` -### How it works - -Changelogs are generated based on commit titles. Commits are only included if -they contain a specific Git trailer. GitLab uses the value of this trailer to -categorize the changes. - -GitLab uses Git trailers, because Git trailers are -supported by Git out of the box. We use commits as input, as this is the only -source of data every project uses. In addition, commits can be retrieved when -operating on a mirror. This is important for GitLab itself, because during a security -release we might need to include changes from both public projects and private -security mirrors. - -Changelogs are generated by taking the title of the commits to include and using -these as the changelog entries. You can enrich entries with additional data, -such as a link to the merge request or details about the commit author. You can -[customize the format of a changelog](#customize-the-changelog-output) section with a template. - -Trailers can be manually added while editing a commit message. To include a commit -using the default trailer of `Changelog` and categorize it as a feature, the -trailer could be added to a commit message like so: - -```plaintext -<Commit message subject> - -<Commit message description> - -Changelog: feature -``` - -### Reverted commits - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55537) in GitLab 13.10. - -When generating a changelog for a range, GitLab ignores commits both added and -reverted in that range. Revert commits themselves _are_ included if they use the -Git trailer used for generating changelogs. - -Imagine the following scenario: you have three commits: A, B, and C. To generate -changelogs, you use the default trailer `Changelog`. Both A and B use this -trailer. Commit C is a commit that reverts commit B. When generating a changelog -for this range, GitLab only includes commit A. - -Revert commits are detected by looking for commits where the message contains -the pattern `This reverts commit SHA`, where `SHA` is the SHA of the commit that -is reverted. - -If a revert commit includes the trailer used for generating changelogs -(`Changelog` in the above example), the revert commit itself _is_ included. - -### Customize the changelog output - -The output is customized using a YAML configuration file stored in your -project's Git repository. This default configuration file path is -`.gitlab/changelog_config.yml`. - -You can set the following variables in this file: - -- `date_format`: the date format to use in the title of the newly added - changelog data. This uses regular `strftime` formatting. -- `template`: a custom template to use for generating the changelog data. -- `categories`: a hash that maps raw category names to the names to use in the - changelog. -- `include_groups`: a list of group full paths containing users whose - contributions should be credited regardless of project membership. The user - generating the changelog must have access to each group or the members will - not be credited. - -Using the default settings, generating a changelog results in a section along -the lines of the following: - -```markdown -## 1.0.0 (2021-01-05) - -### Features (4 changes) - -- [Feature 1](gitlab-org/gitlab@123abc) by @alice ([merge request](gitlab-org/gitlab!123)) -- [Feature 2](gitlab-org/gitlab@456abc) ([merge request](gitlab-org/gitlab!456)) -- [Feature 3](gitlab-org/gitlab@234abc) by @steve -- [Feature 4](gitlab-org/gitlab@456) -``` - -Each section starts with a title that contains the version and release date. -While the format of the date can be customized, the rest of the title can't be -changed. When adding a new section, GitLab parses these titles to determine -where in the file the new section should be placed. GitLab sorts sections -according to their versions, not their dates. - -Each section can have categories, each with their -corresponding changes. In the above example, "Features" is one such category. -You can customize the format of these sections. - -The section names are derived from the values of the Git trailer used to include -or exclude commits. - -For example, if the trailer to use is called `Changelog`, -and its value is `feature`, then the commit is grouped in the `feature` -category. The names of these raw values might differ from what you want to -show in a changelog, you can remap them. Let's say we use the `Changelog` -trailer and developers use the following values: `feature`, `bug`, and -`performance`. - -You can remap these using the following YAML configuration file: - -```yaml ---- -categories: - feature: Features - bug: Bug fixes - performance: Performance improvements -``` - -When generating the changelog data, the category titles are then `### Features`, -`### Bug fixes`, and `### Performance improvements`. - -### Custom templates - -The category sections are generated using a template. The default template is as -follows: - -```plaintext -{% if categories %} -{% each categories %} -### {{ title }} ({% if single_change %}1 change{% else %}{{ count }} changes{% end %}) - -{% each entries %} -- [{{ title }}]({{ commit.reference }})\ -{% if author.credit %} by {{ author.reference }}{% end %}\ -{% if merge_request %} ([merge request]({{ merge_request.reference }})){% end %} - -{% end %} - -{% end %} -{% else %} -No changes. -{% end %} -``` - -The `{% ... %}` tags are for statements, and `{{ ... }}` is used for printing -data. Statements must be terminated using a `{% end %}` tag. Both the `if` and -`each` statements require a single argument. - -For example, if we have a variable `valid`, and we want to display "yes" -when this value is true, and display "nope" otherwise. We can do so as follows: - -```plaintext -{% if valid %} -yes -{% else %} -nope -{% end %} -``` - -The use of `else` is optional. A value is considered true when it's a non-empty -value or boolean `true`. Empty arrays and hashes are considered false. - -Looping is done using `each`, and variables inside a loop are scoped to it. -Referring to the current value in a loop is done using the variable tag `{{ it -}}`. Other variables read their value from the current loop value. Take -this template for example: - -```plaintext -{% each users %} -{{name}} -{% end %} -``` - -Assuming `users` is an array of objects, each with a `name` field, this would -then print the name of every user. - -Using variable tags, you can access nested objects. For example, `{{ -users.0.name }}` prints the name of the first user in the `users` variable. - -If a line ends in a backslash, the next newline is ignored. This allows you to -wrap code across multiple lines, without introducing unnecessary newlines in the -Markdown output. - -Tags that use `{%` and `%}` (known as expression tags) consume the newline that -directly follows them, if any. This means that this: - -```plaintext ---- -{% if foo %} -bar -{% end %} ---- -``` - -Compiles into this: - -```plaintext ---- -bar ---- -``` - -Instead of this: - -```plaintext ---- - -bar - ---- -``` - -You can specify a custom template in your configuration like so: - -```yaml ---- -template: | - {% if categories %} - {% each categories %} - ### {{ title }} - - {% each entries %} - - [{{ title }}]({{ commit.reference }})\ - {% if author.credit %} by {{ author.reference }}{% end %} - - {% end %} - - {% end %} - {% else %} - No changes. - {% end %} -``` - -When specifying the template you should use `template: |` and not -`template: >`, as the latter doesn't preserve newlines in the template. - -### Template data - -At the top level, the following variable is available: - -- `categories`: an array of objects, one for every changelog category. - -In a category, the following variables are available: - -- `count`: the number of entries in this category. -- `entries`: the entries that belong to this category. -- `single_change`: a boolean that indicates if there is only one change (`true`), - or multiple changes (`false`). -- `title`: the title of the category (after it has been remapped). - -In an entry, the following variables are available (here `foo.bar` means that -`bar` is a sub-field of `foo`): - -- `author.contributor`: a boolean set to `true` when the author is not a project - member, otherwise `false`. -- `author.credit`: a boolean set to `true` when `author.contributor` is `true` or - when `include_groups` is configured, and the author is a member of one of the - groups. -- `author.reference`: a reference to the commit author (for example, `@alice`). -- `commit.reference`: a reference to the commit, for example, - `gitlab-org/gitlab@0a4cdd86ab31748ba6dac0f69a8653f206e5cfc7`. -- `commit.trailers`: an object containing all the Git trailers that were present - in the commit body. -- `merge_request.reference`: a reference to the merge request that first - introduced the change (for example, `gitlab-org/gitlab!50063`). -- `title`: the title of the changelog entry (this is the commit title). - -The `author` and `merge_request` objects might not be present if the data -couldn't be determined. For example, when a commit is created without a -corresponding merge request, no merge request is displayed. - -### Customize the tag format when extracting versions - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56889) in GitLab 13.11. - -GitLab uses a regular expression (using the -[re2](https://github.com/google/re2/) engine and syntax) to extract a semantic -version from tag names. The default regular expression is: - -```plaintext -^v?(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<pre>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<meta>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ -``` - -This regular expression is based on the official -[semantic versioning](https://semver.org/) regular expression, and also includes -support for tag names that start with the letter `v`. - -If your project uses a different format for tags, you can specify a different -regular expression. The regular expression used _must_ produce the following -capture groups. If any of these capture groups are missing, the tag is ignored: - -- `major` -- `minor` -- `patch` - -The following capture groups are optional: - -- `pre`: If set, the tag is ignored. Ignoring `pre` tags ensures release candidate - tags and other pre-release tags are not considered when determining the range of - commits to generate a changelog for. -- `meta`: Optional. Specifies build metadata. - -Using this information, GitLab builds a map of Git tags and their release -versions. It then determines what the latest tag is, based on the version -extracted from each tag. - -To specify a custom regular expression, use the `tag_regex` setting in your -changelog configuration YAML file. For example, this pattern matches tag names -such as `version-1.2.3` but not `version-1.2`. - -```yaml ---- -tag_regex: '^version-(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)$' -``` - -To test if your regular expression is working, you can use websites such as -[regex101](https://regex101.com/). If the regular expression syntax is invalid, -an error is produced when generating a changelog. - ## Generate changelog data > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345934) in GitLab 14.6. @@ -738,7 +429,7 @@ Supported attributes: | `config_file` | string | no | The path of changelog configuration file in the project's Git repository, defaults to `.gitlab/changelog_config.yml`. | | `date` | datetime | no | The date and time of the release, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z`. Defaults to the current time. | | `from` | string | no | The start of the range of commits (as a SHA) to use for generating the changelog. This commit itself isn't included in the list. | -| `to` | string | no | The end of the range of commits (as a SHA) to use for the changelog. This commit _is_ included in the list. Defaults to the branch specified in the `branch` attribute. | +| `to` | string | no | The end of the range of commits (as a SHA) to use for the changelog. This commit _is_ included in the list. Defaults to the HEAD of the default project branch. | | `trailer` | string | no | The Git trailer to use for including commits, defaults to `Changelog`. | ```shell @@ -752,3 +443,8 @@ Example Response: "notes": "## 1.0.0 (2021-11-17)\n\n### feature (2 changes)\n\n- [Title 2](namespace13/project13@ad608eb642124f5b3944ac0ac772fecaf570a6bf) ([merge request](namespace13/project13!2))\n- [Title 1](namespace13/project13@3c6b80ff7034fa0d585314e1571cc780596ce3c8) ([merge request](namespace13/project13!1))\n" } ``` + +## Related topics + +- User documentation for [changelogs](../user/project/changelogs.md) +- Developer documentation for [changelog entries](../development/changelog.md) in GitLab. |