debian-mirror-gitlab/doc/api/repository_files.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

340 lines
15 KiB
Markdown
Raw Normal View History

2020-10-24 23:57:45 +05:30
---
stage: Create
group: Source Code
2021-02-22 17:27:13 +05:30
info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments"
2020-10-24 23:57:45 +05:30
type: reference, api
---
2021-03-11 19:13:27 +05:30
# Repository files API **(FREE)**
2014-09-02 18:07:02 +05:30
2021-11-18 22:05:49 +05:30
You can fetch, create, update, and delete files in your repository with this API.
You can also [configure rate limits](../user/admin_area/settings/files_api_rate_limits.md)
for this API.
2014-09-02 18:07:02 +05:30
2021-11-18 22:05:49 +05:30
## Available scopes for personal access tokens
2014-09-02 18:07:02 +05:30
2019-02-15 15:39:39 +05:30
The different scopes available using [personal access tokens](../user/profile/personal_access_tokens.md) are depicted
in the following table.
| Scope | Description |
| ----- | ----------- |
| `read_repository` | Allows read-access to the repository files. |
| `api` | Allows read-write access to the repository files. |
2014-09-02 18:07:02 +05:30
## Get file from repository
2022-06-21 17:19:12 +05:30
> The `execute_filemode` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/83499) in GitLab 14.10.
2017-08-17 22:00:37 +05:30
Allows you to receive information about file in repository like name, size,
2021-10-27 15:23:28 +05:30
content. File content is Base64 encoded. This endpoint can be accessed
2017-08-17 22:00:37 +05:30
without authentication if the repository is publicly accessible.
2014-09-02 18:07:02 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
GET /projects/:id/repository/files/:file_path
2014-09-02 18:07:02 +05:30
```
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb?ref=master"
2016-09-13 17:45:13 +05:30
```
2022-01-26 12:08:38 +05:30
| 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 |
| `file_path` | string | yes | URL encoded full path to new file. Ex. `lib%2Fclass%2Erb`. |
| `ref` | string | yes | The name of branch, tag or commit |
2014-09-02 18:07:02 +05:30
Example response:
```json
{
"file_name": "key.rb",
"file_path": "app/models/key.rb",
"size": 1476,
"encoding": "base64",
"content": "IyA9PSBTY2hlbWEgSW5mb3...",
2018-11-08 19:23:39 +05:30
"content_sha256": "4c294617b60715c1d218e61164a3abd4808a4284cbc30e6728a01ad9aada4481",
2014-09-02 18:07:02 +05:30
"ref": "master",
"blob_id": "79f7bbd25901e8334750839545a9bd021f0e4c83",
2015-11-26 14:37:03 +05:30
"commit_id": "d5a3ff139356ce33e37e73add446f16869741b50",
2022-06-21 17:19:12 +05:30
"last_commit_id": "570e7b2abdd848b95f2f578043fc23bd6f6fd24d",
"execute_filemode": false
2014-09-02 18:07:02 +05:30
}
```
2021-02-22 17:27:13 +05:30
NOTE:
2020-06-23 00:09:42 +05:30
`blob_id` is the blob SHA, see [repositories - Get a blob from repository](repositories.md#get-a-blob-from-repository)
2018-11-08 19:23:39 +05:30
In addition to the `GET` method, you can also use `HEAD` to get just file metadata.
2020-04-08 14:13:33 +05:30
```plaintext
2018-11-08 19:23:39 +05:30
HEAD /projects/:id/repository/files/:file_path
```
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --head --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb?ref=master"
2018-11-08 19:23:39 +05:30
```
Example response:
2020-05-24 23:13:21 +05:30
```plaintext
2018-11-08 19:23:39 +05:30
HTTP/1.1 200 OK
...
X-Gitlab-Blob-Id: 79f7bbd25901e8334750839545a9bd021f0e4c83
X-Gitlab-Commit-Id: d5a3ff139356ce33e37e73add446f16869741b50
X-Gitlab-Content-Sha256: 4c294617b60715c1d218e61164a3abd4808a4284cbc30e6728a01ad9aada4481
X-Gitlab-Encoding: base64
X-Gitlab-File-Name: key.rb
X-Gitlab-File-Path: app/models/key.rb
X-Gitlab-Last-Commit-Id: 570e7b2abdd848b95f2f578043fc23bd6f6fd24d
X-Gitlab-Ref: master
X-Gitlab-Size: 1476
2022-06-21 17:19:12 +05:30
X-Gitlab-Execute-Filemode: false
2018-11-08 19:23:39 +05:30
...
```
2019-10-12 21:52:04 +05:30
## Get file blame from repository
2020-04-22 19:07:51 +05:30
Allows you to receive blame information. Each blame range contains lines and corresponding commit information.
2019-10-12 21:52:04 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2019-10-12 21:52:04 +05:30
GET /projects/:id/repository/files/:file_path/blame
```
2022-07-16 23:28:13 +05:30
| 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 |
| `file_path` | string | yes | URL encoded full path to new file. Ex. `lib%2Fclass%2Erb`. |
| `ref` | string | yes | The name of branch, tag or commit |
| `range` | hash | no | Blame range |
| `range[start]` | integer | yes | The first line of the range to blame |
| `range[end]` | integer | yes | The last line of the range to blame |
2022-01-26 12:08:38 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/13083/repository/files/path%2Fto%2Ffile.rb/blame?ref=master"
2019-10-12 21:52:04 +05:30
```
Example response:
```json
[
{
"commit": {
"id": "d42409d56517157c48bf3bd97d3f75974dde19fb",
"message": "Add feature\n\nalso fix bug\n",
"parent_ids": [
"cc6e14f9328fa6d7b5a0d3c30dc2002a3f2a3822"
],
"authored_date": "2015-12-18T08:12:22.000Z",
"author_name": "John Doe",
"author_email": "john.doe@example.com",
"committed_date": "2015-12-18T08:12:22.000Z",
"committer_name": "John Doe",
"committer_email": "john.doe@example.com"
},
"lines": [
"require 'fileutils'",
"require 'open3'",
""
]
},
...
]
```
2021-02-22 17:27:13 +05:30
NOTE:
2019-10-12 21:52:04 +05:30
`HEAD` method return just file metadata as in [Get file from repository](repository_files.md#get-file-from-repository).
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --head --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/13083/repository/files/path%2Fto%2Ffile.rb/blame?ref=master"
2019-10-12 21:52:04 +05:30
```
Example response:
2020-05-24 23:13:21 +05:30
```plaintext
2019-10-12 21:52:04 +05:30
HTTP/1.1 200 OK
...
X-Gitlab-Blob-Id: 79f7bbd25901e8334750839545a9bd021f0e4c83
X-Gitlab-Commit-Id: d5a3ff139356ce33e37e73add446f16869741b50
X-Gitlab-Content-Sha256: 4c294617b60715c1d218e61164a3abd4808a4284cbc30e6728a01ad9aada4481
X-Gitlab-Encoding: base64
X-Gitlab-File-Name: file.rb
X-Gitlab-File-Path: path/to/file.rb
X-Gitlab-Last-Commit-Id: 570e7b2abdd848b95f2f578043fc23bd6f6fd24d
X-Gitlab-Ref: master
X-Gitlab-Size: 1476
2022-06-21 17:19:12 +05:30
X-Gitlab-Execute-Filemode: false
2019-10-12 21:52:04 +05:30
...
```
2022-07-16 23:28:13 +05:30
### Examples
To request a blame range, specify `range[start]` and `range[end]` parameters with the start and end line numbers of the file.
```shell
curl --head --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/13083/repository/files/path%2Fto%2Ffile.rb/blame?ref=master&range[start]=1&range[end]=2"
```
Example response:
```json
[
{
"commit": {
"id": "d42409d56517157c48bf3bd97d3f75974dde19fb",
"message": "Add feature\n\nalso fix bug\n",
"parent_ids": [
"cc6e14f9328fa6d7b5a0d3c30dc2002a3f2a3822"
],
"authored_date": "2015-12-18T08:12:22.000Z",
"author_name": "John Doe",
"author_email": "john.doe@example.com",
"committed_date": "2015-12-18T08:12:22.000Z",
"committer_name": "John Doe",
"committer_email": "john.doe@example.com"
},
"lines": [
"require 'fileutils'",
"require 'open3'"
]
},
...
]
```
2017-08-17 22:00:37 +05:30
## Get raw file from repository
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
GET /projects/:id/repository/files/:file_path/raw
```
2022-01-26 12:08:38 +05:30
| 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 |
| `file_path` | string | yes | URL encoded full path to new file. Ex. `lib%2Fclass%2Erb`. |
| `ref` | string | yes | The name of branch, tag or commit. Default is the `HEAD` of the project. |
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb/raw?ref=master"
2017-08-17 22:00:37 +05:30
```
2021-02-22 17:27:13 +05:30
NOTE:
2018-11-08 19:23:39 +05:30
Like [Get file from repository](repository_files.md#get-file-from-repository) you can use `HEAD` to get just file metadata.
2014-09-02 18:07:02 +05:30
## Create new file in repository
2022-06-21 17:19:12 +05:30
> The `execute_filemode` parameter was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/83499) in GitLab 14.10.
2020-04-08 14:13:33 +05:30
This allows you to create a single file. For creating multiple files with a single request see the [commits API](commits.md#create-a-commit-with-multiple-files-and-actions).
2018-12-05 23:21:45 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
POST /projects/:id/repository/files/:file_path
2014-09-02 18:07:02 +05:30
```
2022-04-04 11:22:00 +05:30
| 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. |
| `file_path` | string | yes | URL-encoded full path to new file. For example: `lib%2Fclass%2Erb`. |
| `branch` | string | yes | Name of the new branch to create. The commit is added to this branch. |
| `start_branch` | string | no | Name of the base branch to create the new branch from. |
| `encoding` | string | no | Change encoding to `base64`. Default is `text`. |
| `author_email` | string | no | The commit author's email address. |
| `author_name` | string | no | The commit author's name. |
| `content` | string | yes | The file's content. |
| `commit_message` | string | yes | The commit message. |
2022-06-21 17:19:12 +05:30
| `execute_filemode` | boolean | no | Enables or disables the `execute` flag on the file. Can be `true` or `false`. |
2022-01-26 12:08:38 +05:30
2020-03-13 15:44:24 +05:30
```shell
2021-09-04 01:27:46 +05:30
curl --request POST --header 'PRIVATE-TOKEN: <your_access_token>' \
--header "Content-Type: application/json" \
2021-12-11 22:18:48 +05:30
--data '{"branch": "master", "author_email": "author@example.com", "author_name": "Firstname Lastname",
2021-09-04 01:27:46 +05:30
"content": "some content", "commit_message": "create a new file"}' \
"https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb"
2016-09-13 17:45:13 +05:30
```
2014-09-02 18:07:02 +05:30
Example response:
```json
{
2018-03-17 18:26:18 +05:30
"file_path": "app/project.rb",
2017-08-17 22:00:37 +05:30
"branch": "master"
2014-09-02 18:07:02 +05:30
}
```
## Update existing file in repository
2022-06-21 17:19:12 +05:30
> The `execute_filemode` parameter was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/83499) in GitLab 14.10.
2020-04-08 14:13:33 +05:30
This allows you to update a single file. For updating multiple files with a single request see the [commits API](commits.md#create-a-commit-with-multiple-files-and-actions).
2018-12-05 23:21:45 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
PUT /projects/:id/repository/files/:file_path
2014-09-02 18:07:02 +05:30
```
2022-04-04 11:22:00 +05:30
| Attribute | Type | Required | Description |
| ---------------- | -------------- | -------- | ----------- |
2022-01-26 12:08:38 +05:30
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2022-04-04 11:22:00 +05:30
| `file_path` | string | yes | URL-encoded full path to new file. For example: `lib%2Fclass%2Erb`. |
| `branch` | string | yes | Name of the new branch to create. The commit is added to this branch. |
| `start_branch` | string | no | Name of the base branch to create the new branch from. |
| `encoding` | string | no | Change encoding to `base64`. Default is `text`. |
| `author_email` | string | no | The commit author's email address. |
| `author_name` | string | no | The commit author's name. |
| `content` | string | yes | The file's content. |
| `commit_message` | string | yes | The commit message. |
| `last_commit_id` | string | no | Last known file commit ID. |
2022-06-21 17:19:12 +05:30
| `execute_filemode` | boolean | no | Enables or disables the `execute` flag on the file. Can be `true` or `false`. |
2022-01-26 12:08:38 +05:30
2020-03-13 15:44:24 +05:30
```shell
2021-09-04 01:27:46 +05:30
curl --request PUT --header 'PRIVATE-TOKEN: <your_access_token>' \
--header "Content-Type: application/json" \
2021-12-11 22:18:48 +05:30
--data '{"branch": "master", "author_email": "author@example.com", "author_name": "Firstname Lastname",
2021-09-04 01:27:46 +05:30
"content": "some content", "commit_message": "update file"}' \
"https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb"
2016-09-13 17:45:13 +05:30
```
2014-09-02 18:07:02 +05:30
Example response:
```json
{
2018-03-17 18:26:18 +05:30
"file_path": "app/project.rb",
2017-08-17 22:00:37 +05:30
"branch": "master"
2014-09-02 18:07:02 +05:30
}
```
If the commit fails for any reason we return a 400 error with a non-specific
error message. Possible causes for a failed commit include:
2019-07-07 11:18:12 +05:30
2014-09-02 18:07:02 +05:30
- the `file_path` contained `/../` (attempted directory traversal);
2020-04-08 14:13:33 +05:30
- the new file contents were identical to the current file contents. That is, the
2014-09-02 18:07:02 +05:30
user tried to make an empty commit;
- the branch was updated by a Git push while the file edit was in progress.
2021-09-04 01:27:46 +05:30
GitLab Shell has a boolean return code, preventing GitLab from specifying the error.
2014-09-02 18:07:02 +05:30
## Delete existing file in repository
2020-04-08 14:13:33 +05:30
This allows you to delete a single file. For deleting multiple files with a single request, see the [commits API](commits.md#create-a-commit-with-multiple-files-and-actions).
2018-12-05 23:21:45 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
DELETE /projects/:id/repository/files/:file_path
2014-09-02 18:07:02 +05:30
```
2022-04-04 11:22:00 +05:30
| 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. |
| `file_path` | string | yes | URL-encoded full path to new file. For example: `lib%2Fclass%2Erb`. |
| `branch` | string | yes | Name of the new branch to create. The commit is added to this branch. |
| `start_branch` | string | no | Name of the base branch to create the new branch from. |
| `author_email` | string | no | The commit author's email address. |
| `author_name` | string | no | The commit author's name. |
| `commit_message` | string | yes | The commit message. |
| `last_commit_id` | string | no | Last known file commit ID. |
2022-01-26 12:08:38 +05:30
2020-03-13 15:44:24 +05:30
```shell
2021-09-04 01:27:46 +05:30
curl --request DELETE --header 'PRIVATE-TOKEN: <your_access_token>' \
--header "Content-Type: application/json" \
2021-12-11 22:18:48 +05:30
--data '{"branch": "master", "author_email": "author@example.com", "author_name": "Firstname Lastname",
2021-09-04 01:27:46 +05:30
"commit_message": "delete file"}' \
"https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb"
2016-09-13 17:45:13 +05:30
```