# Repository files API

> 原文：[https://docs.gitlab.com/ee/api/repository_files.html](https://docs.gitlab.com/ee/api/repository_files.html)

*   [Get file from repository](#get-file-from-repository)
*   [Get file blame from repository](#get-file-blame-from-repository)
*   [Get raw file from repository](#get-raw-file-from-repository)
*   [Create new file in repository](#create-new-file-in-repository)
*   [Update existing file in repository](#update-existing-file-in-repository)
*   [Delete existing file in repository](#delete-existing-file-in-repository)

# Repository files API[](#repository-files-api "Permalink")

**库文件的 CRUD**

**使用此 API 创建，读取，更新和删除存储库文件**

下表描述了使用[个人访问令牌](../user/profile/personal_access_tokens.html)可用的不同范围.

| Scope | Description |
| --- | --- |
| `read_repository` | 允许对存储库文件进行读取访问. |
| `api` | 允许对存储库文件进行读写访问. |

`read_repository` scope was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23534) in GitLab 11.6.

## Get file from repository[](#get-file-from-repository "Permalink")

允许您接收有关存储库中文件的信息，例如名称，大小，内容. 请注意，文件内容是 Base64 编码的. 如果可公开访问该存储库，则无需身份验证即可访问此端点.

```
GET /projects/:id/repository/files/:file_path 
```

```
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb?ref=master" 
```

响应示例：

```
{  "file_name":  "key.rb",  "file_path":  "app/models/key.rb",  "size":  1476,  "encoding":  "base64",  "content":  "IyA9PSBTY2hlbWEgSW5mb3...",  "content_sha256":  "4c294617b60715c1d218e61164a3abd4808a4284cbc30e6728a01ad9aada4481",  "ref":  "master",  "blob_id":  "79f7bbd25901e8334750839545a9bd021f0e4c83",  "commit_id":  "d5a3ff139356ce33e37e73add446f16869741b50",  "last_commit_id":  "570e7b2abdd848b95f2f578043fc23bd6f6fd24d"  } 
```

Parameters:

*   `file_path` （必需）-URL 编码的新文件的完整路径. 例如 lib％2Fclass％2Erb
*   `ref` （必填）-分支，标记或提交的名称

**注意：** `blob_id`是 blob SHA，请参见[存储库-从存储库获取 blob](repositories.html#get-a-blob-from-repository)

除了`GET`方法外，您还可以使用`HEAD`来获取文件元数据.

```
HEAD /projects/:id/repository/files/:file_path 
```

```
curl --head --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb?ref=master" 
```

响应示例：

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

## Get file blame from repository[](#get-file-blame-from-repository "Permalink")

允许您接收责备信息. 每个责任范围包含行和相应的提交信息.

```
GET /projects/:id/repository/files/:file_path/blame 
```

```
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/13083/repository/files/path%2Fto%2Ffile.rb/blame?ref=master" 
```

响应示例：

```
[  {  "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'",  ""  ]  },  ...  ] 
```

Parameters:

*   `file_path` （必需）-URL 编码的新文件的完整路径. 例如 lib％2Fclass％2Erb
*   `ref` （必填）-分支，标记或提交的名称

**注意：** `HEAD`方法仅返回文件元数据，如[从存储库](repository_files.html#get-file-from-repository)中[获取文件中所示](repository_files.html#get-file-from-repository) .

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

响应示例：

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

## Get raw file from repository[](#get-raw-file-from-repository "Permalink")

```
GET /projects/:id/repository/files/:file_path/raw 
```

```
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb/raw?ref=master" 
```

Parameters:

*   `file_path` （必需）-URL 编码的新文件的完整路径. 例如 lib％2Fclass％2Erb
*   `ref` （必填）-分支，标记或提交的名称

**注意：**像[从存储库中获取文件](repository_files.html#get-file-from-repository)一样[，](repository_files.html#get-file-from-repository)您可以使用`HEAD`仅获取文件元数据.

## Create new file in repository[](#create-new-file-in-repository "Permalink")

这使您可以创建一个文件. 要使用一个请求创建多个文件，请参阅[commits API](commits.html#create-a-commit-with-multiple-files-and-actions) .

```
POST /projects/:id/repository/files/:file_path 
```

```
curl --request POST --header 'PRIVATE-TOKEN: <your_access_token>' --header "Content-Type: application/json" \
  --data '{"branch": "master", "author_email": "author@example.com", "author_name": "Firstname Lastname", \
    "content": "some content", "commit_message": "create a new file"}' \
  "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb" 
```

响应示例：

```
{  "file_path":  "app/project.rb",  "branch":  "master"  } 
```

Parameters:

*   `file_path` （必需）-URL 编码的新文件的完整路径. 例如 lib％2Fclass％2Erb
*   `branch` （必填）-分支的名称
*   `start_branch` （可选）-从中开始新提交的分支名称
*   `encoding` （可选）-将编码更改为" base64". 默认为文本.
*   `author_email` （可选）-指定提交作者的电子邮件地址
*   `author_name` （可选）-指定提交作者的姓名
*   `content` （必填）-文件内容
*   `commit_message` （必填）-提交消息

## Update existing file in repository[](#update-existing-file-in-repository "Permalink")

这使您可以更新单个文件. 有关通过单个请求更新多个文件的信息，请参见[commits API](commits.html#create-a-commit-with-multiple-files-and-actions) .

```
PUT /projects/:id/repository/files/:file_path 
```

```
curl --request PUT --header 'PRIVATE-TOKEN: <your_access_token>' --header "Content-Type: application/json" \
  --data '{"branch": "master", "author_email": "author@example.com", "author_name": "Firstname Lastname", \
    "content": "some content", "commit_message": "update file"}' \
  "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb" 
```

响应示例：

```
{  "file_path":  "app/project.rb",  "branch":  "master"  } 
```

Parameters:

*   `file_path` （必需）-URL 编码的新文件的完整路径. 例如 lib％2Fclass％2Erb
*   `branch` （必填）-分支的名称
*   `start_branch` （可选）-从中开始新提交的分支名称
*   `encoding` （可选）-将编码更改为" base64". 默认为文本.
*   `author_email` （可选）-指定提交作者的电子邮件地址
*   `author_name` （可选）-指定提交作者的姓名
*   `content` （必填）-新文件内容
*   `commit_message` （必填）-提交消息
*   `last_commit_id` （可选）-已知文件的最新提交 ID

如果提交由于任何原因失败，我们将返回 400 错误，并显示非特定错误消息. 提交失败的可能原因包括：

*   `file_path`包含`/../` （试图遍历目录）；
*   新文件内容与当前文件内容相同. 也就是说，用户尝试进行空提交；
*   在进行文件编辑时，通过 Git 推送更新了分支.

当前，GitLab Shell 具有布尔返回码，可防止 GitLab 指定错误.

## Delete existing file in repository[](#delete-existing-file-in-repository "Permalink")

这使您可以删除单个文件. 有关通过单个请求删除多个文件的信息，请参见[commits API](commits.html#create-a-commit-with-multiple-files-and-actions) .

```
DELETE /projects/:id/repository/files/:file_path 
```

```
curl --request DELETE --header 'PRIVATE-TOKEN: <your_access_token>' --header "Content-Type: application/json" \
  --data '{"branch": "master", "author_email": "author@example.com", "author_name": "Firstname Lastname", \
    "commit_message": "delete file"}' \
  "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb" 
```

Parameters:

*   `file_path` （必需）-URL 编码的新文件的完整路径. 例如 lib％2Fclass％2Erb
*   `branch` （必填）-分支的名称
*   `start_branch` （可选）-从中开始新提交的分支名称
*   `author_email` （可选）-指定提交作者的电子邮件地址
*   `author_name` （可选）-指定提交作者的姓名
*   `commit_message` （必填）-提交消息
*   `last_commit_id` （可选）-已知文件的最新提交 ID