summaryrefslogtreecommitdiff
path: root/doc/api/repositories.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/api/repositories.md')
-rw-r--r--doc/api/repositories.md60
1 files changed, 48 insertions, 12 deletions
diff --git a/doc/api/repositories.md b/doc/api/repositories.md
index e93ffbc5e72..ec5c97e5b25 100644
--- a/doc/api/repositories.md
+++ b/doc/api/repositories.md
@@ -28,7 +28,7 @@ Supported attributes:
| Attribute | Type | Required | Description |
| :---------- | :------------- | :------- | :---------- |
-| `id` | integer/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](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `path` | string | no | The path inside repository. Used to get content of subdirectories. |
| `ref` | string | no | The name of a repository branch or tag or if not given the default branch. |
| `recursive` | boolean | no | Boolean value used to get a recursive tree (false by default). |
@@ -104,7 +104,7 @@ Supported attributes:
| Attribute | Type | Required | Description |
| :-------- | :------------- | :------- | :---------- |
-| `id` | integer/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](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `sha` | string | yes | The blob SHA. |
## Raw blob content
@@ -146,7 +146,7 @@ Supported attributes:
| Attribute | Type | Required | Description |
|:------------|:---------------|:---------|:----------------------|
-| `id` | integer/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](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `sha` | string | no | The commit SHA to download. A tag, branch reference, or SHA can be used. This defaults to the tip of the default branch if not specified. |
| `path` | string | no | The subpath of the repository to download. This defaults to the whole repository (empty string). |
@@ -169,7 +169,7 @@ Supported attributes:
| Attribute | Type | Required | Description |
| :--------- | :------------- | :------- | :---------- |
-| `id` | integer/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](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 |
@@ -231,7 +231,7 @@ Supported attributes:
| Attribute | Type | Required | Description |
| :--------- | :------------- | :------- | :---------- |
-| `id` | integer/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](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`. |
@@ -263,7 +263,7 @@ GET /projects/:id/repository/merge_base
| Attribute | Type | Required | Description |
| --------- | -------------- | -------- | ------------------------------------------------------------------------------- |
-| `id` | integer/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](index.md#namespaced-path-encoding) |
| `refs` | array | yes | The refs to find the common ancestor of, multiple refs can be passed |
Example request:
@@ -291,7 +291,7 @@ Example response:
}
```
-## Generate changelog data
+## Add changelog data to a changelog file
> [Introduced](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/351) in GitLab 13.9.
@@ -373,26 +373,26 @@ If the last tag is `v0.9.0` and the default branch is `main`, the range of commi
included in this example is `v0.9.0..main`:
```shell
-curl --header "PRIVATE-TOKEN: token" --data "version=1.0.0" "https://gitlab.com/api/v4/projects/42/repository/changelog"
+curl --request POST --header "PRIVATE-TOKEN: token" --data "version=1.0.0" "https://gitlab.com/api/v4/projects/42/repository/changelog"
```
To generate the data on a different branch, specify the `branch` parameter. This
command generates data from the `foo` branch:
```shell
-curl --header "PRIVATE-TOKEN: token" --data "version=1.0.0&branch=foo" "https://gitlab.com/api/v4/projects/42/repository/changelog"
+curl --request POST --header "PRIVATE-TOKEN: token" --data "version=1.0.0&branch=foo" "https://gitlab.com/api/v4/projects/42/repository/changelog"
```
To use a different trailer, use the `trailer` parameter:
```shell
-curl --header "PRIVATE-TOKEN: token" --data "version=1.0.0&trailer=Type" "https://gitlab.com/api/v4/projects/42/repository/changelog"
+curl --request POST --header "PRIVATE-TOKEN: token" --data "version=1.0.0&trailer=Type" "https://gitlab.com/api/v4/projects/42/repository/changelog"
```
To store the results in a different file, use the `file` parameter:
```shell
-curl --header "PRIVATE-TOKEN: token" --data "version=1.0.0&file=NEWS" "https://gitlab.com/api/v4/projects/42/repository/changelog"
+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
@@ -689,7 +689,7 @@ 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.
+- `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
@@ -707,3 +707,39 @@ 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.
+
+Generate changelog data based on commits in a repository, without committing
+them to a changelog file.
+
+Works exactly like `POST /projects/:id/repository/changelog`, except the changelog
+data isn't committed to any changelog file.
+
+```plaintext
+GET /projects/:id/repository/changelog
+```
+
+Supported attributes:
+
+| Attribute | Type | Required | Description |
+| :-------- | :------- | :--------- | :---------- |
+| `version` | string | yes | The version to generate the changelog for. The format must follow [semantic versioning](https://semver.org/). |
+| `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. |
+| `date` | datetime | no | The date and time of the release, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z`. Defaults to the current time. |
+| `trailer` | string | no | The Git trailer to use for including commits, defaults to `Changelog`. |
+
+```shell
+curl --header "PRIVATE-TOKEN: token" "https://gitlab.com/api/v4/projects/42/repository/changelog?version=1.0.0"
+```
+
+Example Response:
+
+```json
+{
+ "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"
+}
+```
View Lorry Controller Status