repository_files.md 7.15 KB
Newer Older
1
# Repository files API
2

Ciro Santilli's avatar
Ciro Santilli committed
3
**CRUD for repository files**
4

Ciro Santilli's avatar
Ciro Santilli committed
5
**Create, read, update and delete repository files using this API**
6

7
The different scopes available using [personal access tokens](../user/profile/personal_access_tokens.md) are depicted
James Lopez's avatar
James Lopez committed
8 9 10 11
in the following table.

| Scope | Description |
| ----- | ----------- |
12 13
| `read_repository` | Allows read-access to the repository files. |
| `api` | Allows read-write access to the repository files. |
James Lopez's avatar
James Lopez committed
14

James Lopez's avatar
James Lopez committed
15
> `read_repository` scope was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/23534) in GitLab 11.6.
James Lopez's avatar
James Lopez committed
16

17 18
## Get file from repository

19 20 21
Allows you to receive information about file in repository like name, size,
content. Note that file content is Base64 encoded. This endpoint can be accessed
without authentication if the repository is publicly accessible.
22 23

```
24
GET /projects/:id/repository/files/:file_path
25 26
```

27
```bash
28
curl --request GET --header 'PRIVATE-TOKEN: <your_access_token>' 'https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb?ref=master'
29 30
```

31 32 33 34 35 36 37 38 39
Example response:

```json
{
  "file_name": "key.rb",
  "file_path": "app/models/key.rb",
  "size": 1476,
  "encoding": "base64",
  "content": "IyA9PSBTY2hlbWEgSW5mb3...",
40
  "content_sha256": "4c294617b60715c1d218e61164a3abd4808a4284cbc30e6728a01ad9aada4481",
41 42
  "ref": "master",
  "blob_id": "79f7bbd25901e8334750839545a9bd021f0e4c83",
43 44
  "commit_id": "d5a3ff139356ce33e37e73add446f16869741b50",
  "last_commit_id": "570e7b2abdd848b95f2f578043fc23bd6f6fd24d"
45 46 47 48 49
}
```

Parameters:

50 51 52
- `file_path` (required) - Url encoded full path to new file. Ex. lib%2Fclass%2Erb
- `ref` (required) - The name of branch, tag or commit

53 54 55 56 57 58 59 60 61 62
NOTE: **Note:**
`blob_id` is the blob sha, see [repositories - Get a blob from repository](repositories.md#get-a-blob-from-repository)

In addition to the `GET` method, you can also use `HEAD` to get just file metadata.

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

```bash
63
curl --head --header 'PRIVATE-TOKEN: <your_access_token>' 'https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb?ref=master'
64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82
```

Example response:

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

83 84 85 86 87 88 89
## Get raw file from repository

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

```bash
90
curl --request GET --header 'PRIVATE-TOKEN: <your_access_token>' 'https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb/raw?ref=master'
91 92 93 94 95
```

Parameters:

- `file_path` (required) - Url encoded full path to new file. Ex. lib%2Fclass%2Erb
96
- `ref` (required) - The name of branch, tag or commit
97

98 99 100
NOTE: **Note:**
Like [Get file from repository](repository_files.md#get-file-from-repository) you can use `HEAD` to get just file metadata.

101 102
## Create new file in repository

103 104
This allows you to create a single file. For creating multiple files with a single request see the [commits API](commits.html#create-a-commit-with-multiple-files-and-actions).

105
```
106
POST /projects/:id/repository/files/:file_path
107 108
```

109
```bash
110
curl --request POST --header 'PRIVATE-TOKEN: <your_access_token>' --header "Content-Type: application/json" \
111 112 113
  --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'
114 115
```

116 117 118 119
Example response:

```json
{
120
  "file_path": "app/project.rb",
121
  "branch": "master"
122 123 124 125 126
}
```

Parameters:

127
- `file_path` (required) - Url encoded full path to new file. Ex. lib%2Fclass%2Erb
128 129
- `branch` (required) - Name of the branch
- `start_branch` (optional) - Name of the branch to start the new commit from
Robert Schilling's avatar
Robert Schilling committed
130
- `encoding` (optional) - Change encoding to 'base64'. Default is text.
131 132
- `author_email` (optional) - Specify the commit author's email address
- `author_name` (optional) - Specify the commit author's name
133 134
- `content` (required) - File content
- `commit_message` (required) - Commit message
135 136 137

## Update existing file in repository

138 139
This allows you to update a single file. For updating multiple files with a single request see the [commits API](commits.html#create-a-commit-with-multiple-files-and-actions).

140
```
141
PUT /projects/:id/repository/files/:file_path
142 143
```

144
```bash
145
curl --request PUT --header 'PRIVATE-TOKEN: <your_access_token>' --header "Content-Type: application/json" \
146 147 148
  --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'
149 150
```

151 152 153 154
Example response:

```json
{
155
  "file_path": "app/project.rb",
156
  "branch": "master"
157 158 159 160 161
}
```

Parameters:

162
- `file_path` (required) - Url encoded full path to new file. Ex. lib%2Fclass%2Erb
163 164
- `branch` (required) - Name of the branch
- `start_branch` (optional) - Name of the branch to start the new commit from
Robert Schilling's avatar
Robert Schilling committed
165
- `encoding` (optional) - Change encoding to 'base64'. Default is text.
166 167
- `author_email` (optional) - Specify the commit author's email address
- `author_name` (optional) - Specify the commit author's name
168 169
- `content` (required) - New file content
- `commit_message` (required) - Commit message
170
- `last_commit_id` (optional) - Last known file commit id
171

172 173 174 175 176 177 178
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:
- the `file_path` contained `/../` (attempted directory traversal);
- the new file contents were identical to the current file contents, i.e. the
  user tried to make an empty commit;
- the branch was updated by a Git push while the file edit was in progress.

Sytse Sijbrandij's avatar
Sytse Sijbrandij committed
179 180
Currently gitlab-shell has a boolean return code, preventing GitLab from specifying the error.

181 182
## Delete existing file in repository

183 184
This allows you to delete a single file. For deleting multiple files with a singleh request see the [commits API](commits.html#create-a-commit-with-multiple-files-and-actions).

185
```
186
DELETE /projects/:id/repository/files/:file_path
187 188
```

189
```bash
190
curl --request DELETE --header 'PRIVATE-TOKEN: <your_access_token>' --header "Content-Type: application/json" \
191 192 193
  --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'
194 195
```

196 197
Parameters:

198
- `file_path` (required) - Url encoded full path to new file. Ex. lib%2Fclass%2Erb
199 200
- `branch` (required) - Name of the branch
- `start_branch` (optional) - Name of the branch to start the new commit from
201 202
- `author_email` (optional) - Specify the commit author's email address
- `author_name` (optional) - Specify the commit author's name
203
- `commit_message` (required) - Commit message
204
- `last_commit_id` (optional) - Last known file commit id