BigW Consortium Gitlab

repository_files.md 4.07 KB
Newer Older
1 2
# Repository files

Ciro Santilli committed
3
**CRUD for repository files**
4

Ciro Santilli committed
5
**Create, read, update and delete repository files using this API**
6 7 8

## Get file from repository

9 10 11
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.
12 13 14 15 16

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

17
```bash
18
curl --request GET --header 'PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK' 'https://gitlab.example.com/api/v4/projects/13083/repository/files?file_path=app/models/key.rb&ref=master'
19 20
```

21 22 23 24 25 26 27 28 29 30 31
Example response:

```json
{
  "file_name": "key.rb",
  "file_path": "app/models/key.rb",
  "size": 1476,
  "encoding": "base64",
  "content": "IyA9PSBTY2hlbWEgSW5mb3...",
  "ref": "master",
  "blob_id": "79f7bbd25901e8334750839545a9bd021f0e4c83",
32 33
  "commit_id": "d5a3ff139356ce33e37e73add446f16869741b50",
  "last_commit_id": "570e7b2abdd848b95f2f578043fc23bd6f6fd24d"
34 35 36 37 38
}
```

Parameters:

39 40
- `file_path` (required) - Full path to new file. Ex. lib/class.rb
- `ref` (required) - The name of branch, tag or commit
41 42 43 44 45 46 47

## Create new file in repository

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

48
```bash
49
curl --request POST --header 'PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK' 'https://gitlab.example.com/api/v4/projects/13083/repository/files?file_path=app/project.rb&branch=master&author_email=author%40example.com&author_name=Firstname%20Lastname&content=some%20content&commit_message=create%20a%20new%20file'
50 51
```

52 53 54 55
Example response:

```json
{
56 57
  "file_name": "app/project.rb",
  "branch": "master"
58 59 60 61 62
}
```

Parameters:

63
- `file_path` (required) - Full path to new file. Ex. lib/class.rb
64
- `branch` (required) - The name of branch
65
- `encoding` (optional) - Change encoding to 'base64'. Default is text.
66 67
- `author_email` (optional) - Specify the commit author's email address
- `author_name` (optional) - Specify the commit author's name
68 69
- `content` (required) - File content
- `commit_message` (required) - Commit message
70 71 72 73 74 75 76

## Update existing file in repository

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

77
```bash
78
curl --request PUT --header 'PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK' 'https://gitlab.example.com/api/v4/projects/13083/repository/files?file_path=app/project.rb&branch=master&author_email=author%40example.com&author_name=Firstname%20Lastname&content=some%20other%20content&commit_message=update%20file'
79 80
```

81 82 83 84
Example response:

```json
{
85 86
  "file_name": "app/project.rb",
  "branch": "master"
87 88 89 90 91
}
```

Parameters:

92
- `file_path` (required) - Full path to file. Ex. lib/class.rb
93
- `branch` (required) - The name of branch
94
- `encoding` (optional) - Change encoding to 'base64'. Default is text.
95 96
- `author_email` (optional) - Specify the commit author's email address
- `author_name` (optional) - Specify the commit author's name
97 98
- `content` (required) - New file content
- `commit_message` (required) - Commit message
99

100 101 102 103 104 105 106
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 committed
107 108
Currently gitlab-shell has a boolean return code, preventing GitLab from specifying the error.

109 110 111 112 113 114
## Delete existing file in repository

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

115
```bash
116
curl --request DELETE --header 'PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK' 'https://gitlab.example.com/api/v4/projects/13083/repository/files?file_path=app/project.rb&branch=master&author_email=author%40example.com&author_name=Firstname%20Lastname&commit_message=delete%20file'
117 118
```

119 120 121 122
Example response:

```json
{
123 124
  "file_name": "app/project.rb",
  "branch": "master"
125 126 127 128 129
}
```

Parameters:

130
- `file_path` (required) - Full path to file. Ex. lib/class.rb
131
- `branch` (required) - The name of branch
132 133
- `author_email` (optional) - Specify the commit author's email address
- `author_name` (optional) - Specify the commit author's name
134
- `commit_message` (required) - Commit message