Repository files API

原文:https://docs.gitlab.com/ee/api/repository_files.html

Repository files API

库文件的 CRUD

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

下表描述了使用个人访问令牌可用的不同范围.

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

read_repository scope was introduced in GitLab 11.6.

Get file from repository

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

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

响应示例:

  1. { "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

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

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

响应示例:

  1. HTTP/1.1 200 OK
  2. ...
  3. X-Gitlab-Blob-Id: 79f7bbd25901e8334750839545a9bd021f0e4c83
  4. X-Gitlab-Commit-Id: d5a3ff139356ce33e37e73add446f16869741b50
  5. X-Gitlab-Content-Sha256: 4c294617b60715c1d218e61164a3abd4808a4284cbc30e6728a01ad9aada4481
  6. X-Gitlab-Encoding: base64
  7. X-Gitlab-File-Name: key.rb
  8. X-Gitlab-File-Path: app/models/key.rb
  9. X-Gitlab-Last-Commit-Id: 570e7b2abdd848b95f2f578043fc23bd6f6fd24d
  10. X-Gitlab-Ref: master
  11. X-Gitlab-Size: 1476
  12. ...

Get file blame from repository

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

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

响应示例:

  1. [ { "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方法仅返回文件元数据,如从存储库获取文件中所示 .

  1. 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"

响应示例:

  1. HTTP/1.1 200 OK
  2. ...
  3. X-Gitlab-Blob-Id: 79f7bbd25901e8334750839545a9bd021f0e4c83
  4. X-Gitlab-Commit-Id: d5a3ff139356ce33e37e73add446f16869741b50
  5. X-Gitlab-Content-Sha256: 4c294617b60715c1d218e61164a3abd4808a4284cbc30e6728a01ad9aada4481
  6. X-Gitlab-Encoding: base64
  7. X-Gitlab-File-Name: file.rb
  8. X-Gitlab-File-Path: path/to/file.rb
  9. X-Gitlab-Last-Commit-Id: 570e7b2abdd848b95f2f578043fc23bd6f6fd24d
  10. X-Gitlab-Ref: master
  11. X-Gitlab-Size: 1476
  12. ...

Get raw file from repository

  1. GET /projects/:id/repository/files/:file_path/raw
  1. 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 (必填)-分支,标记或提交的名称

注意:从存储库中获取文件一样您可以使用HEAD仅获取文件元数据.

Create new file in repository

这使您可以创建一个文件. 要使用一个请求创建多个文件,请参阅commits API .

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

响应示例:

  1. { "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

这使您可以更新单个文件. 有关通过单个请求更新多个文件的信息,请参见commits API .

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

响应示例:

  1. { "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

这使您可以删除单个文件. 有关通过单个请求删除多个文件的信息,请参见commits API .

  1. DELETE /projects/:id/repository/files/:file_path
  1. curl --request DELETE --header 'PRIVATE-TOKEN: <your_access_token>' --header "Content-Type: application/json" \
  2. --data '{"branch": "master", "author_email": "author@example.com", "author_name": "Firstname Lastname", \
  3. "commit_message": "delete file"}' \
  4. "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