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

252 lines
7.7 KiB
Markdown
Raw Normal View History

2017-09-10 17:25:29 +05:30
# Repositories API
2014-09-02 18:07:02 +05:30
## List repository tree
2017-08-17 22:00:37 +05:30
Get a list of repository files and directories in a project. This endpoint can
be accessed without authentication if the repository is publicly accessible.
This command provides essentially the same functionality as the `git ls-tree` command. For more information, see the section _Tree Objects_ in the [Git internals documentation](https://git-scm.com/book/en/v2/Git-Internals-Git-Objects/#_tree_objects).
2014-09-02 18:07:02 +05:30
```
GET /projects/:id/repository/tree
```
Parameters:
2017-08-17 22:00:37 +05:30
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
2018-12-13 13:39:08 +05:30
- `path` (optional) - The path inside repository. Used to get content of subdirectories
2017-08-17 22:00:37 +05:30
- `ref` (optional) - The name of a repository branch or tag or if not given the default branch
- `recursive` (optional) - Boolean value used to get a recursive tree (false by default)
2019-02-15 15:39:39 +05:30
- `per_page` (optional) - Number of results to show per page. If not specified, defaults to `20`
2014-09-02 18:07:02 +05:30
```json
[
{
2017-08-17 22:00:37 +05:30
"id": "a1e8f8d745cc87e3a9248358d9352bb7f9a0aeba",
"name": "html",
2014-09-02 18:07:02 +05:30
"type": "tree",
2017-08-17 22:00:37 +05:30
"path": "files/html",
"mode": "040000"
2014-09-02 18:07:02 +05:30
},
{
2017-08-17 22:00:37 +05:30
"id": "4535904260b1082e14f867f7a24fd8c21495bde3",
"name": "images",
2014-09-02 18:07:02 +05:30
"type": "tree",
2017-08-17 22:00:37 +05:30
"path": "files/images",
"mode": "040000"
2014-09-02 18:07:02 +05:30
},
{
2017-08-17 22:00:37 +05:30
"id": "31405c5ddef582c5a9b7a85230413ff90e2fe720",
"name": "js",
2014-09-02 18:07:02 +05:30
"type": "tree",
2017-08-17 22:00:37 +05:30
"path": "files/js",
"mode": "040000"
2014-09-02 18:07:02 +05:30
},
{
2017-08-17 22:00:37 +05:30
"id": "cc71111cfad871212dc99572599a568bfe1e7e00",
"name": "lfs",
"type": "tree",
"path": "files/lfs",
"mode": "040000"
2014-09-02 18:07:02 +05:30
},
{
2017-08-17 22:00:37 +05:30
"id": "fd581c619bf59cfdfa9c8282377bb09c2f897520",
"name": "markdown",
"type": "tree",
"path": "files/markdown",
"mode": "040000"
2014-09-02 18:07:02 +05:30
},
{
2017-08-17 22:00:37 +05:30
"id": "23ea4d11a4bdd960ee5320c5cb65b5b3fdbc60db",
"name": "ruby",
"type": "tree",
"path": "files/ruby",
"mode": "040000"
},
{
"id": "7d70e02340bac451f281cecf0a980907974bd8be",
"name": "whitespace",
2014-09-02 18:07:02 +05:30
"type": "blob",
2017-08-17 22:00:37 +05:30
"path": "files/whitespace",
"mode": "100644"
2014-09-02 18:07:02 +05:30
}
]
```
2017-08-17 22:00:37 +05:30
## Get a blob from repository
2014-09-02 18:07:02 +05:30
2017-08-17 22:00:37 +05:30
Allows you to receive information about blob in repository like size and
content. Note that blob content is Base64 encoded. This endpoint can be accessed
without authentication if the repository is publicly accessible.
2014-09-02 18:07:02 +05:30
```
GET /projects/:id/repository/blobs/:sha
```
Parameters:
2017-08-17 22:00:37 +05:30
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
2018-03-17 18:26:18 +05:30
- `sha` (required) - The blob SHA
2014-09-02 18:07:02 +05:30
## Raw blob content
2017-08-17 22:00:37 +05:30
Get the raw file contents for a blob by blob SHA. This endpoint can be accessed
without authentication if the repository is publicly accessible.
2014-09-02 18:07:02 +05:30
```
2017-08-17 22:00:37 +05:30
GET /projects/:id/repository/blobs/:sha/raw
2014-09-02 18:07:02 +05:30
```
Parameters:
2017-08-17 22:00:37 +05:30
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
2014-09-02 18:07:02 +05:30
- `sha` (required) - The blob SHA
## Get file archive
2017-08-17 22:00:37 +05:30
Get an archive of the repository. This endpoint can be accessed without
authentication if the repository is publicly accessible.
2014-09-02 18:07:02 +05:30
```
2019-02-15 15:39:39 +05:30
GET /projects/:id/repository/archive[.format]
2014-09-02 18:07:02 +05:30
```
2019-02-15 15:39:39 +05:30
`format` is an optional suffix for the archive format. Default is
2019-03-02 22:35:43 +05:30
`tar.gz`. Options are `tar.gz`, `tar.bz2`, `tbz`, `tbz2`, `tb2`,
2019-02-15 15:39:39 +05:30
`bz2`, `tar`, and `zip`. For example, specifying `archive.zip`
would send an archive in ZIP format.
2014-09-02 18:07:02 +05:30
Parameters:
2017-08-17 22:00:37 +05:30
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
2019-07-07 11:18:12 +05:30
- `sha` (optional) - The commit SHA to download. A tag, branch reference, or SHA can be used. This defaults to the tip of the default branch if not specified. For example:
2020-03-09 13:42:32 +05:30
```shell
2019-09-30 21:07:59 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.com/api/v4/projects/<project_id>/repository/archive?sha=<commit_sha>
```
2014-09-02 18:07:02 +05:30
## Compare branches, tags or commits
2017-08-17 22:00:37 +05:30
This endpoint can be accessed without authentication if the repository is
2020-03-09 13:42:32 +05:30
publicly accessible. Note that diffs could have an empty diff string if [diff limits](../development/diffs.md#diff-limits) are reached.
2017-08-17 22:00:37 +05:30
2014-09-02 18:07:02 +05:30
```
GET /projects/:id/repository/compare
```
Parameters:
2017-08-17 22:00:37 +05:30
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
2014-09-02 18:07:02 +05:30
- `from` (required) - the commit SHA or branch name
- `to` (required) - the commit SHA or branch name
2018-11-08 19:23:39 +05:30
- `straight` (optional) - comparison method, `true` for direct comparison between `from` and `to` (`from`..`to`), `false` to compare using merge base (`from`...`to`)'. Default is `false`.
2014-09-02 18:07:02 +05:30
```
GET /projects/:id/repository/compare?from=master&to=feature
```
Response:
```json
{
"commit": {
"id": "12d65c8dd2b2676fa3ac47d955accc085a37a9c1",
"short_id": "12d65c8dd2b",
"title": "JS fix",
"author_name": "Dmitriy Zaporozhets",
"author_email": "dmitriy.zaporozhets@gmail.com",
"created_at": "2014-02-27T10:27:00+02:00"
},
"commits": [{
"id": "12d65c8dd2b2676fa3ac47d955accc085a37a9c1",
"short_id": "12d65c8dd2b",
"title": "JS fix",
"author_name": "Dmitriy Zaporozhets",
"author_email": "dmitriy.zaporozhets@gmail.com",
"created_at": "2014-02-27T10:27:00+02:00"
}],
"diffs": [{
"old_path": "files/js/application.js",
"new_path": "files/js/application.js",
"a_mode": null,
"b_mode": "100644",
"diff": "--- a/files/js/application.js\n+++ b/files/js/application.js\n@@ -24,8 +24,10 @@\n //= require g.raphael-min\n //= require g.bar-min\n //= require branch-graph\n-//= require highlightjs.min\n-//= require ace/ace\n //= require_tree .\n //= require d3\n //= require underscore\n+\n+function fix() { \n+ alert(\"Fixed\")\n+}",
"new_file": false,
"renamed_file": false,
"deleted_file": false
}],
"compare_timeout": false,
"compare_same_ref": false
}
```
## Contributors
2017-08-17 22:00:37 +05:30
Get repository contributors list. This endpoint can be accessed without
authentication if the repository is publicly accessible.
2014-09-02 18:07:02 +05:30
```
GET /projects/:id/repository/contributors
```
Parameters:
2017-08-17 22:00:37 +05:30
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
2018-05-09 12:01:36 +05:30
- `order_by` (optional) - Return contributors ordered by `name`, `email`, or `commits` (orders by commit date) fields. Default is `commits`
2018-03-17 18:26:18 +05:30
- `sort` (optional) - Return contributors sorted in `asc` or `desc` order. Default is `asc`
2014-09-02 18:07:02 +05:30
Response:
```
[{
"name": "Dmitriy Zaporozhets",
"email": "dmitriy.zaporozhets@gmail.com",
"commits": 117,
"additions": 2097,
"deletions": 517
}, {
"name": "Jacob Vosmaer",
"email": "contact@jacobvosmaer.nl",
"commits": 33,
"additions": 338,
"deletions": 244
}]
```
2018-11-20 20:47:30 +05:30
## Merge Base
2019-02-15 15:39:39 +05:30
Get the common ancestor for 2 or more refs (commit SHAs, branch names or tags).
2018-11-20 20:47:30 +05:30
```
GET /projects/:id/repository/merge_base
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
2018-12-13 13:39:08 +05:30
| `refs` | array | yes | The refs to find the common ancestor of, multiple refs can be passed |
2018-11-20 20:47:30 +05:30
2020-03-09 13:42:32 +05:30
```shell
2019-02-15 15:39:39 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/merge_base?refs[]=304d257dcb821665ab5110318fc58a007bd104ed&refs[]=0031876facac3f2b2702a0e53a26e89939a42209"
2018-11-20 20:47:30 +05:30
```
Example response:
```json
{
2019-09-30 21:07:59 +05:30
"id": "1a0b36b3cdad1d2ee32457c102a8c0b7056fa863",
"short_id": "1a0b36b3",
"title": "Initial commit",
"created_at": "2014-02-27T08:03:18.000Z",
"parent_ids": [],
"message": "Initial commit\n",
"author_name": "Dmitriy Zaporozhets",
"author_email": "dmitriy.zaporozhets@gmail.com",
"authored_date": "2014-02-27T08:03:18.000Z",
"committer_name": "Dmitriy Zaporozhets",
"committer_email": "dmitriy.zaporozhets@gmail.com",
"committed_date": "2014-02-27T08:03:18.000Z"
2018-11-20 20:47:30 +05:30
}
```