Google Git
Sign in
gerrit / gerrit / 53286f250390006ace1394b03d26e13137de34d9 / . / Documentation / rest-api-changes.txt
blob: 8c10bc7bbca274c7aecb45c25d4849fc8bb72023 [file] [log] [blame]
= Gerrit Code Review - /changes/ REST API
This page describes the change related REST endpoints.
Please also take note of the general information on the
link:rest-api.html[REST API].
[[change-endpoints]]
== Change Endpoints
[[create-change]]
=== Create Change
--
'POST /changes'
--
The change info link:#change-info[ChangeInfo] entity must be provided in the
request body. Only the following attributes are honored: `project`,
`branch`, `subject`, `status` and `topic`. The first three attributes are
mandatory. Valid values for status are: `DRAFT` and `NEW`.
.Request
----
POST /changes HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"project" : "myProject",
"subject" : "Let's support 100% Gerrit workflow direct in browser",
"branch" : "master",
"topic" : "create-change-in-browser",
"status" : "DRAFT"
}
----
As response a link:#change-info[ChangeInfo] entity is returned that describes
the resulting change.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9941",
"project": "myProject",
"branch": "master",
"topic": "create-change-in-browser",
"change_id": "I8473b95934b5732ac55d26311a706c9c2bde9941",
"subject": "Let's support 100% Gerrit workflow direct in browser",
"status": "DRAFT",
"created": "2014-05-05 07:15:44.639000000",
"updated": "2014-05-05 07:15:44.639000000",
"mergeable": true,
"insertions": 0,
"deletions": 0,
"_number": 4711,
"owner": {
"name": "John Doe"
}
}
----
[[list-changes]]
=== Query Changes
--
'GET /changes/'
--
Queries changes visible to the caller. The
link:user-search.html#_search_operators[query string] must be provided
by the `q` parameter. The `n` parameter can be used to limit the
returned results.
As result a list of link:#change-info[ChangeInfo] entries is returned.
The change output is sorted by the last update time, most recently
updated to oldest updated.
Query for open changes of watched projects:
.Request
----
GET /changes/?q=status:open+is:watched&n=2 HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
[
{
"id": "demo~master~Idaf5e098d70898b7119f6f4af5a6c13343d64b57",
"project": "demo",
"branch": "master",
"change_id": "Idaf5e098d70898b7119f6f4af5a6c13343d64b57",
"subject": "One change",
"status": "NEW",
"created": "2012-07-17 07:18:30.854000000",
"updated": "2012-07-17 07:19:27.766000000",
"mergeable": true,
"insertions": 26,
"deletions": 10,
"_number": 1756,
"owner": {
"name": "John Doe"
},
},
{
"id": "demo~master~I09c8041b5867d5b33170316e2abc34b79bbb8501",
"project": "demo",
"branch": "master",
"change_id": "I09c8041b5867d5b33170316e2abc34b79bbb8501",
"subject": "Another change",
"status": "NEW",
"created": "2012-07-17 07:18:30.884000000",
"updated": "2012-07-17 07:18:30.885000000",
"mergeable": true,
"insertions": 12,
"deletions": 18,
"_number": 1757,
"owner": {
"name": "John Doe"
},
"_more_changes": true
}
]
----
If the `n` query parameter is supplied and additional changes exist
that match the query beyond the end, the last change object has a
`_more_changes: true` JSON field set.
The `S` or `start` query parameter can be supplied to skip a number
of changes from the list.
Clients are allowed to specify more than one query by setting the `q`
parameter multiple times. In this case the result is an array of
arrays, one per query in the same order the queries were given in.
.Query for the 25 most recent open changes of the projects that you watch
****
get::/changes/?q=status:open+is:watched&n=25
****
Query that retrieves changes for a user's dashboard:
.Request
----
GET /changes/?q=is:open+owner:self&q=is:open+reviewer:self+-owner:self&q=is:closed+owner:self+limit:5&o=LABELS HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
[
[
{
"id": "demo~master~Idaf5e098d70898b7119f6f4af5a6c13343d64b57",
"project": "demo",
"branch": "master",
"change_id": "Idaf5e098d70898b7119f6f4af5a6c13343d64b57",
"subject": "One change",
"status": "NEW",
"created": "2012-07-17 07:18:30.854000000",
"updated": "2012-07-17 07:19:27.766000000",
"mergeable": true,
"insertions": 4,
"deletions": 7,
"_number": 1756,
"owner": {
"name": "John Doe"
},
"labels": {
"Verified": {},
"Code-Review": {}
}
}
],
[],
[]
]
----
.Query the changes for your user dashboard
****
get::/changes/?q=is:open+owner:self&q=is:open+reviewer:self+-owner:self&q=is:closed+owner:self+limit:5&o=LABELS
****
Additional fields can be obtained by adding `o` parameters, each
option requires more database lookups and slows down the query
response time to the client so they are generally disabled by
default. Optional fields are:
[[labels]]
--
* `LABELS`: a summary of each label required for submit, and
approvers that have granted (or rejected) with that label.
--
[[detailed-labels]]
--
* `DETAILED_LABELS`: detailed label information, including numeric
values of all existing approvals, recognized label values, values
permitted to be set by the current user, and reviewers that may be
removed by the current user.
--
[[current-revision]]
--
* `CURRENT_REVISION`: describe the current revision (patch set)
of the change, including the commit SHA-1 and URLs to fetch from.
--
[[all-revisions]]
--
* `ALL_REVISIONS`: describe all revisions, not just current.
--
[[download_commands]]
--
* `DOWNLOAD_COMMANDS`: include the `commands` field in the
link:#fetch-info[FetchInfo] for revisions. Only valid when the
`CURRENT_REVISION` or `ALL_REVISIONS` option is selected.
--
[[draft_comments]]
--
* `DRAFT_COMMENTS`: include the `has_draft_comments` field for
revisions. Only valid when the `CURRENT_REVISION` or `ALL_REVISIONS`
option is selected.
--
[[current-commit]]
--
* `CURRENT_COMMIT`: parse and output all header fields from the
commit object, including message. Only valid when the
`CURRENT_REVISION` or `ALL_REVISIONS` option is selected.
--
[[all-commits]]
--
* `ALL_COMMITS`: parse and output all header fields from the
output revisions. If only `CURRENT_REVISION` was requested
then only the current revision's commit data will be output.
--
[[current-files]]
--
* `CURRENT_FILES`: list files modified by the commit, including
basic line counts inserted/deleted per file. Only valid when
the `CURRENT_REVISION` or `ALL_REVISIONS` option is selected.
--
[[all-files]]
--
* `ALL_FILES`: list files modified by the commit, including
basic line counts inserted/deleted per file. If only the
`CURRENT_REVISION` was requested then only that commit's
modified files will be output.
--
[[detailed-accounts]]
--
* `DETAILED_ACCOUNTS`: include `_account_id`, `email` and `username`
fields when referencing accounts.
--
[[messages]]
--
* `MESSAGES`: include messages associated with the change.
--
[[actions]]
--
* `CURRENT_ACTIONS`: include information on available actions
for the change and its current revision. Ignored if the caller
is not authenticated.
--
[[change-actions]]
--
* `CHANGE_ACTIONS`: include information on available
change actions for the change. Ignored if the caller
is not authenticated.
--
[[reviewed]]
--
* `REVIEWED`: include the `reviewed` field if the caller is
authenticated and has commented on the current revision.
--
[[web-links]]
--
* `WEB_LINKS`: include the `web_links` field in link:#commit-info[CommitInfo],
therefore only valid in combination with `CURRENT_COMMIT` or
`ALL_COMMITS`.
--
[[check]]
--
* `CHECK`: include potential problems with the change.
--
.Request
----
GET /changes/?q=97&o=CURRENT_REVISION&o=CURRENT_COMMIT&o=CURRENT_FILES&o=DOWNLOAD_COMMANDS HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
[
{
"id": "gerrit~master~I7ea46d2e2ee5c64c0d807677859cfb7d90b8966a",
"project": "gerrit",
"branch": "master",
"change_id": "I7ea46d2e2ee5c64c0d807677859cfb7d90b8966a",
"subject": "Use an EventBus to manage star icons",
"status": "NEW",
"created": "2012-04-25 00:52:25.580000000",
"updated": "2012-04-25 00:52:25.586000000",
"mergeable": true,
"insertions": 16,
"deletions": 7,
"_number": 97,
"owner": {
"name": "Shawn Pearce"
},
"current_revision": "184ebe53805e102605d11f6b143486d15c23a09c",
"revisions": {
"184ebe53805e102605d11f6b143486d15c23a09c": {
"_number": 1,
"ref": "refs/changes/97/97/1",
"fetch": {
"git": {
"url": "git://localhost/gerrit",
"ref": "refs/changes/97/97/1",
"commands": {
"Checkout": "git fetch git://localhost/gerrit refs/changes/97/97/1 \u0026\u0026 git checkout FETCH_HEAD",
"Cherry-Pick": "git fetch git://localhost/gerrit refs/changes/97/97/1 \u0026\u0026 git cherry-pick FETCH_HEAD",
"Format-Patch": "git fetch git://localhost/gerrit refs/changes/97/97/1 \u0026\u0026 git format-patch -1 --stdout FETCH_HEAD",
"Pull": "git pull git://localhost/gerrit refs/changes/97/97/1"
}
},
"http": {
"url": "http://myuser@127.0.0.1:8080/gerrit",
"ref": "refs/changes/97/97/1",
"commands": {
"Checkout": "git fetch http://myuser@127.0.0.1:8080/gerrit refs/changes/97/97/1 \u0026\u0026 git checkout FETCH_HEAD",
"Cherry-Pick": "git fetch http://myuser@127.0.0.1:8080/gerrit refs/changes/97/97/1 \u0026\u0026 git cherry-pick FETCH_HEAD",
"Format-Patch": "git fetch http://myuser@127.0.0.1:8080/gerrit refs/changes/97/97/1 \u0026\u0026 git format-patch -1 --stdout FETCH_HEAD",
"Pull": "git pull http://myuser@127.0.0.1:8080/gerrit refs/changes/97/97/1"
}
},
"ssh": {
"url": "ssh://myuser@*:29418/gerrit",
"ref": "refs/changes/97/97/1",
"commands": {
"Checkout": "git fetch ssh://myuser@*:29418/gerrit refs/changes/97/97/1 \u0026\u0026 git checkout FETCH_HEAD",
"Cherry-Pick": "git fetch ssh://myuser@*:29418/gerrit refs/changes/97/97/1 \u0026\u0026 git cherry-pick FETCH_HEAD",
"Format-Patch": "git fetch ssh://myuser@*:29418/gerrit refs/changes/97/97/1 \u0026\u0026 git format-patch -1 --stdout FETCH_HEAD",
"Pull": "git pull ssh://myuser@*:29418/gerrit refs/changes/97/97/1"
}
}
},
"commit": {
"parents": [
{
"commit": "1eee2c9d8f352483781e772f35dc586a69ff5646",
"subject": "Migrate contributor agreements to All-Projects."
}
],
"author": {
"name": "Shawn O. Pearce",
"email": "sop@google.com",
"date": "2012-04-24 18:08:08.000000000",
"tz": -420
},
"committer": {
"name": "Shawn O. Pearce",
"email": "sop@google.com",
"date": "2012-04-24 18:08:08.000000000",
"tz": -420
},
"subject": "Use an EventBus to manage star icons",
"message": "Use an EventBus to manage star icons\n\nImage widgets that need to ..."
},
"files": {
"gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeCache.java": {
"lines_deleted": 8
},
"gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeDetailCache.java": {
"lines_inserted": 1
},
"gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeScreen.java": {
"lines_inserted": 11,
"lines_deleted": 19
},
"gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeTable.java": {
"lines_inserted": 23,
"lines_deleted": 20
},
"gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarCache.java": {
"status": "D",
"lines_deleted": 139
},
"gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarredChanges.java": {
"status": "A",
"lines_inserted": 204
},
"gerrit-gwtui/src/main/java/com/google/gerrit/client/ui/Screen.java": {
"lines_deleted": 9
}
}
}
}
}
]
----
[[get-change]]
=== Get Change
--
'GET /changes/link:#change-id[\{change-id\}]'
--
Retrieves a change.
Additional fields can be obtained by adding `o` parameters, each
option requires more database lookups and slows down the query
response time to the client so they are generally disabled by
default. Fields are described in link:#list-changes[Query Changes].
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940 HTTP/1.0
----
As response a link:#change-info[ChangeInfo] entity is returned that
describes the change.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
"project": "myProject",
"branch": "master",
"change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940",
"subject": "Implementing Feature X",
"status": "NEW",
"created": "2013-02-01 09:59:32.126000000",
"updated": "2013-02-21 11:16:36.775000000",
"mergeable": true,
"insertions": 34,
"deletions": 101,
"_number": 3965,
"owner": {
"name": "John Doe"
}
}
----
[[get-change-detail]]
=== Get Change Detail
--
'GET /changes/link:#change-id[\{change-id\}]/detail'
--
Retrieves a change with link:#labels[labels], link:#detailed-labels[
detailed labels], link:#detailed-accounts[detailed accounts], and
link:#messages[messages].
Additional fields can be obtained by adding `o` parameters, each
option requires more database lookups and slows down the query
response time to the client so they are generally disabled by
default. Fields are described in link:#list-changes[Query Changes].
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/detail HTTP/1.0
----
As response a link:#change-info[ChangeInfo] entity is returned that
describes the change. This response will contain all votes for each
label and include one combined vote. The combined label vote is
calculated in the following order (from highest to lowest):
REJECTED > APPROVED > DISLIKED > RECOMMENDED.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
"project": "myProject",
"branch": "master",
"change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940",
"subject": "Implementing Feature X",
"status": "NEW",
"created": "2013-02-01 09:59:32.126000000",
"updated": "2013-02-21 11:16:36.775000000",
"mergeable": true,
"insertions": 126,
"deletions": 11,
"_number": 3965,
"owner": {
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com",
"username": "jdoe"
},
"labels": {
"Verified": {
"all": [
{
"value": 0,
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com",
"username": "jdoe"
},
{
"value": 0,
"_account_id": 1000097,
"name": "Jane Roe",
"email": "jane.roe@example.com",
"username": "jroe"
}
],
"values": {
"-1": "Fails",
" 0": "No score",
"+1": "Verified"
}
},
"Code-Review": {
"disliked": {
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com",
"username": "jdoe"
},
"all": [
{
"value": -1,
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com",
"username": "jdoe"
},
{
"value": 1,
"_account_id": 1000097,
"name": "Jane Roe",
"email": "jane.roe@example.com",
"username": "jroe"
}
]
"values": {
"-2": "This shall not be merged",
"-1": "I would prefer this is not merged as is",
" 0": "No score",
"+1": "Looks good to me, but someone else must approve",
"+2": "Looks good to me, approved"
}
}
},
"permitted_labels": {
"Verified": [
"-1",
" 0",
"+1"
],
"Code-Review": [
"-2",
"-1",
" 0",
"+1",
"+2"
]
},
"removable_reviewers": [
{
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com",
"username": "jdoe"
},
{
"_account_id": 1000097,
"name": "Jane Roe",
"email": "jane.roe@example.com",
"username": "jroe"
}
],
"messages": [
{
"id": "YH-egE",
"author": {
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com",
"username": "jdoe"
},
"updated": "2013-03-23 21:34:02.419000000",
"message": "Patch Set 1:\n\nThis is the first message.",
"revision_number": 1
},
{
"id": "WEEdhU",
"author": {
"_account_id": 1000097,
"name": "Jane Roe",
"email": "jane.roe@example.com",
"username": "jroe"
},
"updated": "2013-03-23 21:36:52.332000000",
"message": "Patch Set 1:\n\nThis is the second message.\n\nWith a line break.",
"revision_number": 1
}
]
}
----
[[get-topic]]
=== Get Topic
--
'GET /changes/link:#change-id[\{change-id\}]/topic'
--
Retrieves the topic of a change.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
"Documentation"
----
If the change does not have a topic an empty string is returned.
[[set-topic]]
=== Set Topic
--
'PUT /changes/link:#change-id[\{change-id\}]/topic'
--
Sets the topic of a change.
The new topic must be provided in the request body inside a
link:#topic-input[TopicInput] entity.
.Request
----
PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"topic": "Documentation"
}
----
As response the new topic is returned.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
"Documentation"
----
If the topic was deleted the response is "`204 No Content`".
[[delete-topic]]
=== Delete Topic
--
'DELETE /changes/link:#change-id[\{change-id\}]/topic'
--
Deletes the topic of a change.
The request body does not need to include a link:#topic-input[
TopicInput] entity if no review comment is added.
Please note that some proxies prohibit request bodies for DELETE
requests. In this case, if you want to specify a commit message, use
link:#set-topic[PUT] to delete the topic.
.Request
----
DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic HTTP/1.0
----
.Response
----
HTTP/1.1 204 No Content
----
[[abandon-change]]
=== Abandon Change
--
'POST /changes/link:#change-id[\{change-id\}]/abandon'
--
Abandons a change.
The request body does not need to include a link:#abandon-input[
AbandonInput] entity if no review comment is added.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/abandon HTTP/1.0
----
As response a link:#change-info[ChangeInfo] entity is returned that
describes the abandoned change.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
"project": "myProject",
"branch": "master",
"change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940",
"subject": "Implementing Feature X",
"status": "ABANDONED",
"created": "2013-02-01 09:59:32.126000000",
"updated": "2013-02-21 11:16:36.775000000",
"mergeable": true,
"insertions": 3,
"deletions": 310,
"_number": 3965,
"owner": {
"name": "John Doe"
}
}
----
If the change cannot be abandoned because the change state doesn't
allow abandoning of the change, the response is "`409 Conflict`" and
the error message is contained in the response body.
.Response
----
HTTP/1.1 409 Conflict
Content-Disposition: attachment
Content-Type: text/plain; charset=UTF-8
change is merged
----
[[restore-change]]
=== Restore Change
--
'POST /changes/link:#change-id[\{change-id\}]/restore'
--
Restores a change.
The request body does not need to include a link:#restore-input[
RestoreInput] entity if no review comment is added.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/restore HTTP/1.0
----
As response a link:#change-info[ChangeInfo] entity is returned that
describes the restored change.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
"project": "myProject",
"branch": "master",
"change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940",
"subject": "Implementing Feature X",
"status": "NEW",
"created": "2013-02-01 09:59:32.126000000",
"updated": "2013-02-21 11:16:36.775000000",
"mergeable": true,
"insertions": 2,
"deletions": 13,
"_number": 3965,
"owner": {
"name": "John Doe"
}
}
----
If the change cannot be restored because the change state doesn't
allow restoring the change, the response is "`409 Conflict`" and
the error message is contained in the response body.
.Response
----
HTTP/1.1 409 Conflict
Content-Disposition: attachment
Content-Type: text/plain; charset=UTF-8
change is new
----
[[rebase-change]]
=== Rebase Change
--
'POST /changes/link:#change-id[\{change-id\}]/rebase'
--
Rebases a change.
Optionally, the parent revision can be changed to another patch set through the
link:#rebase-input[RebaseInput] entity.
.Request
----
POST /changes/myProject~master~I3ea943139cb62e86071996f2480e58bf3eeb9dd2/rebase HTTP/1.0
Content-Type: application/json;charset=UTF-8
{
"base" : "1234",
}
----
As response a link:#change-info[ChangeInfo] entity is returned that
describes the rebased change. Information about the current patch set
is included.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "myProject~master~I3ea943139cb62e86071996f2480e58bf3eeb9dd2",
"project": "myProject",
"branch": "master",
"change_id": "I3ea943139cb62e86071996f2480e58bf3eeb9dd2",
"subject": "Implement Feature X",
"status": "NEW",
"created": "2013-02-01 09:59:32.126000000",
"updated": "2013-02-21 11:16:36.775000000",
"mergeable": false,
"insertions": 33,
"deletions": 9,
"_number": 4799,
"owner": {
"name": "John Doe"
},
"current_revision": "27cc4558b5a3d3387dd11ee2df7a117e7e581822",
"revisions": {
"27cc4558b5a3d3387dd11ee2df7a117e7e581822": {
"_number": 2,
"ref": "refs/changes/99/4799/2",
"fetch": {
"http": {
"url": "http://gerrit:8080/myProject",
"ref": "refs/changes/99/4799/2"
}
},
"commit": {
"parents": [
{
"commit": "b4003890dadd406d80222bf1ad8aca09a4876b70",
"subject": "Implement Feature A"
}
],
"author": {
"name": "John Doe",
"email": "john.doe@example.com",
"date": "2013-05-07 15:21:27.000000000",
"tz": 120
},
"committer": {
"name": "Gerrit Code Review",
"email": "gerrit-server@example.com",
"date": "2013-05-07 15:35:43.000000000",
"tz": 120
},
"subject": "Implement Feature X",
"message": "Implement Feature X\n\nAdded feature X."
}
}
}
----
If the change cannot be rebased, e.g. due to conflicts, the response is
"`409 Conflict`" and the error message is contained in the response
body.
.Response
----
HTTP/1.1 409 Conflict
Content-Disposition: attachment
Content-Type: text/plain; charset=UTF-8
The change could not be rebased due to a path conflict during merge.
----
[[revert-change]]
=== Revert Change
--
'POST /changes/link:#change-id[\{change-id\}]/revert'
--
Reverts a change.
The request body does not need to include a link:#revert-input[
RevertInput] entity if no review comment is added.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revert HTTP/1.0
----
As response a link:#change-info[ChangeInfo] entity is returned that
describes the reverting change.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
"project": "myProject",
"branch": "master",
"change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940",
"subject": "Revert \"Implementing Feature X\"",
"status": "NEW",
"created": "2013-02-01 09:59:32.126000000",
"updated": "2013-02-21 11:16:36.775000000",
"mergeable": true,
"insertions": 6,
"deletions": 4,
"_number": 3965,
"owner": {
"name": "John Doe"
}
}
----
If the change cannot be reverted because the change state doesn't
allow reverting the change, the response is "`409 Conflict`" and
the error message is contained in the response body.
.Response
----
HTTP/1.1 409 Conflict
Content-Disposition: attachment
Content-Type: text/plain; charset=UTF-8
change is new
----
[[submit-change]]
=== Submit Change
--
'POST /changes/link:#change-id[\{change-id\}]/submit'
--
Submits a change.
The request body only needs to include a link:#submit-input[
SubmitInput] entity if the request should wait for the merge to
complete.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/submit HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"wait_for_merge": true
}
----
As response a link:#change-info[ChangeInfo] entity is returned that
describes the submitted/merged change.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
"project": "myProject",
"branch": "master",
"change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940",
"subject": "Implementing Feature X",
"status": "MERGED",
"created": "2013-02-01 09:59:32.126000000",
"updated": "2013-02-21 11:16:36.775000000",
"_number": 3965,
"owner": {
"name": "John Doe"
}
}
----
If the change cannot be submitted because the submit rule doesn't allow
submitting the change, the response is "`409 Conflict`" and the error
message is contained in the response body.
.Response
----
HTTP/1.1 409 Conflict
Content-Disposition: attachment
Content-Type: text/plain; charset=UTF-8
blocked by Verified
----
[[publish-draft-change]]
=== Publish Draft Change
--
'POST /changes/link:#change-id[\{change-id\}]/publish'
--
Publishes a draft change.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/publish HTTP/1.0
Content-Type: application/json; charset=UTF-8
----
.Response
----
HTTP/1.1 204 No Content
----
[[delete-draft-change]]
=== Delete Draft Change
--
'DELETE /changes/link:#change-id[\{change-id\}]'
--
Deletes a draft change.
.Request
----
DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940 HTTP/1.0
Content-Type: application/json; charset=UTF-8
----
.Response
----
HTTP/1.1 204 No Content
----
[[get-included-in]]
=== Get Included In
--
'GET /changes/link:#change-id[\{change-id\}]/in'
--
Retrieves the branches and tags in which a change is included. As result
an link:#included-in-info[IncludedInInfo] entity is returned.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/in HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"branches": [
"master"
],
"tags": []
}
----
[[index-change]]
=== Index Change
--
'POST /changes/link:#change-id[\{change-id\}]/index'
--
Adds or updates the change in the secondary index.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/index HTTP/1.0
----
.Response
----
HTTP/1.1 204 No Content
----
[[check-change]]
=== Check change
--
'GET /changes/link:#change-id[\{change-id\}]/check'
--
Performs consistency checks on the change, and returns a
link:#change-info[ChangeInfo] entity with the `problems` field set to a
list of link:#problem-info[ProblemInfo] entities.
Depending on the type of problem, some fields not marked optional may be
missing from the result. At least `id`, `project`, `branch`, and
`_number` will be present.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/check HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
"project": "myProject",
"branch": "master",
"change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940",
"subject": "Implementing Feature X",
"status": "NEW",
"created": "2013-02-01 09:59:32.126000000",
"updated": "2013-02-21 11:16:36.775000000",
"mergeable": true,
"insertions": 34,
"deletions": 101,
"_number": 3965,
"owner": {
"name": "John Doe"
},
"problems": [
{
"message": "Current patch set 1 not found"
}
]
}
----
[[fix-change]]
=== Fix change
--
'POST /changes/link:#change-id[\{change-id\}]/check'
--
Performs consistency checks on the change as with link:#check-change[GET
/check], and additionally fixes any problems that can be fixed
automatically. The returned field values reflect any fixes.
Only the change owner, a project owner, or an administrator may fix changes.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/check HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
"project": "myProject",
"branch": "master",
"change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940",
"subject": "Implementing Feature X",
"status": "MERGED",
"created": "2013-02-01 09:59:32.126000000",
"updated": "2013-02-21 11:16:36.775000000",
"mergeable": true,
"insertions": 34,
"deletions": 101,
"_number": 3965,
"owner": {
"name": "John Doe"
},
"problems": [
{
"message": "Current patch set 2 not found"
},
{
"message": "Patch set 1 (1eee2c9d8f352483781e772f35dc586a69ff5646) is merged into destination ref master (1eee2c9d8f352483781e772f35dc586a69ff5646), but change status is NEW",
"status": FIXED,
"outcome": "Marked change as merged"
}
]
}
----
[[edit-endpoints]]
== Change Edit Endpoints
These endpoints are considered to be unstable and can be changed in
backwards incompatible way any time without notice.
[[get-edit-detail]]
=== Get Change Edit Details
--
'GET /changes/link:#change-id[\{change-id\}]/edit
--
Retrieves a change edit details.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit HTTP/1.0
----
As response an link:#edit-info[EditInfo] entity is returned that
describes the change edit, or "`204 No Content`" when change edit doesn't
exist for this change. Change edits are stored on special branches and there
can be max one edit per user per change. Edits aren't tracked in the database.
When request parameter `list` is provided the response also includes the file
list. When `base` request parameter is provided the file list is computed
against this base revision. When request parameter `download-commands` is
provided fetch info map is also included.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"commit":{
"parents":[
{
"commit":"1eee2c9d8f352483781e772f35dc586a69ff5646",
}
],
"author":{
"name":"Shawn O. Pearce",
"email":"sop@google.com",
"date":"2012-04-24 18:08:08.000000000",
"tz":-420
},
"committer":{
"name":"Shawn O. Pearce",
"email":"sop@google.com",
"date":"2012-04-24 18:08:08.000000000",
"tz":-420
},
"subject":"Use an EventBus to manage star icons",
"message":"Use an EventBus to manage star icons\n\nImage widgets that need to ..."
},
}
----
[[put-edit-file]]
=== Change file content in Change Edit
--
'PUT /changes/link:#change-id[\{change-id\}]/edit/path%2fto%2ffile
--
Put content of a file to a change edit.
.Request
----
PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit/foo HTTP/1.0
----
When change edit doesn't exist for this change yet it is created. When file
content isn't provided, it is wiped out for that file. As response
"`204 No Content`" is returned.
.Response
----
HTTP/1.1 204 No Content
----
[[post-edit]]
=== Restore file content or rename files in Change Edit
--
'POST /changes/link:#change-id[\{change-id\}]/edit
--
Creates empty change edit, restores file content or renames files in change
edit. The request body needs to include a
link:#change-edit-input[ChangeEditInput] entity when a file within change
edit should be restored or old and new file names to rename a file.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"restore_path": "foo"
}
----
or for rename:
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"old_path": "foo",
"new_path": "bar"
}
----
When change edit doesn't exist for this change yet it is created. When path
and restore flag are provided in request body, this file is restored. When
old and new file names are provided, the file is renamed. As response
"`204 No Content`" is returned.
.Response
----
HTTP/1.1 204 No Content
----
[[put-change-edit-message]]
=== Change commit message in Change Edit
--
'PUT /changes/link:#change-id[\{change-id\}]/edit:message
--
Modify commit message. The request body needs to include a
link:#change-edit-message-input[ChangeEditMessageInput]
entity.
.Request
----
PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit:message HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"message": "New commit message\n\nChange-Id: I10394472cbd17dd12454f229e4f6de00b143a444"
}
----
If a change edit doesn't exist for this change yet, it is created. As
response "`204 No Content`" is returned.
.Response
----
HTTP/1.1 204 No Content
----
[[delete-edit-file]]
=== Delete file in Change Edit
--
'DELETE /changes/link:#change-id[\{change-id\}]/edit/path%2fto%2ffile'
--
Deletes a file from a change edit. This deletes the file from the repository
completely. This is not the same as reverting or restoring a file to its
previous contents.
.Request
----
DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit/foo HTTP/1.0
----
When change edit doesn't exist for this change yet it is created.
.Response
----
HTTP/1.1 204 No Content
----
[[get-edit-file]]
=== Retrieve file content from Change Edit
--
'GET /changes/link:#change-id[\{change-id\}]/edit/path%2fto%2ffile
--
Retrieves content of a file from a change edit.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit/foo HTTP/1.0
----
The content of the file is returned as text encoded inside base64.
The Content-Type header will always be `text/plain` reflecting the
outer base64 encoding. A Gerrit-specific `X-FYI-Content-Type` header
can be examined to find the server detected content type of the file.
When the specified file was deleted in the change edit
"`204 No Content`" is returned.
If only the content type is required, callers should use HEAD to
avoid downloading the encoded file contents.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: text/plain; charset=ISO-8859-1
X-FYI-Content-Encoding: base64
X-FYI-Content-Type: text/xml
RnJvbSA3ZGFkY2MxNTNmZGVhMTdhYTg0ZmYzMmE2ZTI0NWRiYjY...
----
Alternatively, if the only value of the Accept request header is
`application/json` the content is returned as JSON string and
`X-FYI-Content-Encoding` is set to `json`.
[[get-edit-meta-data]]
=== Retrieve meta data of a file from Change Edit
--
'GET /changes/link:#change-id[\{change-id\}]/edit/path%2fto%2ffile/meta
--
Retrieves meta data of a file from a change edit. Currently only
web links are returned.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit/foo/meta HTTP/1.0
----
This REST endpoint retrieves additional information for a file in a
change edit. As result an link:#edit-file-info[EditFileInfo] entity is
returned.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"web_links":[
{
"show_on_side_by_side_diff_view": true,
"name": "side-by-side preview diff",
"image_url": "plugins/xdocs/static/sideBySideDiffPreview.png",
"url": "#/x/xdocs/c/42/1..0/README.md",
"target": "_self"
},
{
"show_on_unified_diff_view": true,
"name": "unified preview diff",
"image_url": "plugins/xdocs/static/unifiedDiffPreview.png",
"url": "#/x/xdocs/c/42/1..0/README.md,unified",
"target": "_self"
}
]}
----
[[get-edit-message]]
=== Retrieve commit message from Change Edit or current patch set of the change
--
'GET /changes/link:#change-id[\{change-id\}]/edit:message
--
Retrieves commit message from change edit.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit:message HTTP/1.0
----
The commit message is returned as base64 encoded string.
.Response
----
HTTP/1.1 200 OK
VGhpcyBpcyBhIGNvbW1pdCBtZXNzYWdlCgpDaGFuZ2UtSWQ6IElhYzhmZGM1MGRlZjFiYWUzYjAz
M2JhNjcxZTk0OTBmNzUxNDU5ZGUzCg==
----
Alternatively, if the only value of the Accept request header is
`application/json` the commit message is returned as JSON string:
.Response
----
HTTP/1.1 200 OK
)]}'
"Subject of the commit message\n\nThis is the body of the commit message.\n\nChange-Id: Iaf1ba916bf843c175673d675bf7f52862f452db9\n"
----
[[publish-edit]]
=== Publish Change Edit
--
'POST /changes/link:#change-id[\{change-id\}]/edit:publish
--
Promotes change edit to a regular patch set.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit:publish HTTP/1.0
----
As response "`204 No Content`" is returned.
.Response
----
HTTP/1.1 204 No Content
----
[[rebase-edit]]
=== Rebase Change Edit
--
'POST /changes/link:#change-id[\{change-id\}]/edit:rebase
--
Rebases change edit on top of latest patch set.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit:rebase HTTP/1.0
----
When change was rebased on top of latest patch set, response
"`204 No Content`" is returned. When change edit is aready
based on top of the latest patch set, the response
"`409 Conflict`" is returned.
.Response
----
HTTP/1.1 204 No Content
----
[[delete-edit]]
=== Delete Change Edit
--
'DELETE /changes/link:#change-id[\{change-id\}]/edit'
--
Deletes change edit.
.Request
----
DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit HTTP/1.0
----
As response "`204 No Content`" is returned.
.Response
----
HTTP/1.1 204 No Content
----
[[reviewer-endpoints]]
== Reviewer Endpoints
[[list-reviewers]]
=== List Reviewers
--
'GET /changes/link:#change-id[\{change-id\}]/reviewers/'
--
Lists the reviewers of a change.
As result a list of link:#reviewer-info[ReviewerInfo] entries is returned.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/ HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
[
{
"approvals": {
"Verified": "+1",
"Code-Review": "+2"
},
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com"
},
{
"approvals": {
"Verified": " 0",
"Code-Review": "-1"
},
"_account_id": 1000097,
"name": "Jane Roe",
"email": "jane.roe@example.com"
}
]
----
[[suggest-reviewers]]
=== Suggest Reviewers
--
'GET /changes/link:#change-id[\{change-id\}]/suggest_reviewers?q=J&n=5'
--
Suggest the reviewers for a given query `q` and result limit `n`. If result
limit is not passed, then the default 10 is used.
As result a list of link:#suggested-reviewer-info[SuggestedReviewerInfo] entries is returned.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/suggest_reviewers?q=J HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
[
{
"account": {
"_account_id": 1000097,
"name": "Jane Roe",
"email": "jane.roe@example.com"
}
},
{
"group": {
"id": "4fd581c0657268f2bdcc26699fbf9ddb76e3a279",
"name": "Joiner"
}
}
]
----
[[get-reviewer]]
=== Get Reviewer
--
'GET /changes/link:#change-id[\{change-id\}]/reviewers/link:rest-api-accounts.html#account-id[\{account-id\}]'
--
Retrieves a reviewer of a change.
As response a link:#reviewer-info[ReviewerInfo] entity is returned that
describes the reviewer.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/john.doe@example.com HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"approvals": {
"Verified": "+1",
"Code-Review": "+2"
},
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com"
}
----
[[add-reviewer]]
=== Add Reviewer
--
'POST /changes/link:#change-id[\{change-id\}]/reviewers'
--
Adds one user or all members of one group as reviewer to the change.
The reviewer to be added to the change must be provided in the request
body as a link:#reviewer-input[ReviewerInput] entity.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"reviewer": "john.doe@example.com"
}
----
As response an link:#add-reviewer-result[AddReviewerResult] entity is
returned that describes the newly added reviewers.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"reviewers": [
{
"approvals": {
"Verified": " 0",
"Code-Review": " 0"
},
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com"
}
]
}
----
If a group is specified, adding the group members as reviewers is an
atomic operation. This means if an error is returned, none of the
members are added as reviewer.
If a group with many members is added as reviewer a confirmation may be
required.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"reviewer": "MyProjectVerifiers"
}
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"error": "The group My Group has 15 members. Do you want to add them all as reviewers?",
"confirm": true
}
----
To confirm the addition of the reviewers, resend the request with the
`confirmed` flag being set.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"reviewer": "MyProjectVerifiers",
"confirmed": true
}
----
[[delete-reviewer]]
=== Delete Reviewer
--
'DELETE /changes/link:#change-id[\{change-id\}]/reviewers/link:rest-api-accounts.html#account-id[\{account-id\}]'
--
Deletes a reviewer from a change.
.Request
----
DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe HTTP/1.0
----
.Response
----
HTTP/1.1 204 No Content
----
[[revision-endpoints]]
== Revision Endpoints
[[get-commit]]
=== Get Commit
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/commit'
--
Retrieves a parsed commit of a revision.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/commit HTTP/1.0
----
As response a link:#commit-info[CommitInfo] entity is returned that
describes the revision.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"parents": [
{
"commit": "1eee2c9d8f352483781e772f35dc586a69ff5646",
"subject": "Migrate contributor agreements to All-Projects."
}
],
"author": {
"name": "Shawn O. Pearce",
"email": "sop@google.com",
"date": "2012-04-24 18:08:08.000000000",
"tz": -420
},
"committer": {
"name": "Shawn O. Pearce",
"email": "sop@google.com",
"date": "2012-04-24 18:08:08.000000000",
"tz": -420
},
"subject": "Use an EventBus to manage star icons",
"message": "Use an EventBus to manage star icons\n\nImage widgets that need to ..."
}
----
Adding query parameter `links` (for example `/changes/.../commit?links`)
returns a link:#commit-info[CommitInfo] with the additional field `web_links`.
[[get-revision-actions]]
=== Get Revision Actions
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/actions'
--
Retrieves revision link:#action-info[actions] of the revision of a change.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/actions' HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"submit": {
"method": "POST",
"label": "Submit",
"title": "Submit patch set 1 into master",
"enabled": true
},
"cherrypick": {
"method": "POST",
"label": "Cherry Pick",
"title": "Cherry pick change to a different branch",
"enabled": true
}
}
----
The response is a flat map of possible revision actions mapped to their
link:#action-info[ActionInfo].
[[get-review]]
=== Get Review
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/review'
--
Retrieves a review of a revision.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/review HTTP/1.0
----
As response a link:#change-info[ChangeInfo] entity with
link:#detailed-labels[detailed labels] and link:#detailed-accounts[
detailed accounts] is returned that describes the review of the
revision. The revision for which the review is retrieved is contained
in the `revisions` field. In addition the `current_revision` field is
set if the revision for which the review is retrieved is the current
revision of the change. Please note that the returned labels are always
for the current patch set.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
"project": "myProject",
"branch": "master",
"change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940",
"subject": "Implementing Feature X",
"status": "NEW",
"created": "2013-02-01 09:59:32.126000000",
"updated": "2013-02-21 11:16:36.775000000",
"mergeable": true,
"insertions": 34,
"deletions": 45,
"_number": 3965,
"owner": {
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com"
},
"labels": {
"Verified": {
"all": [
{
"value": 0,
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com"
},
{
"value": 0,
"_account_id": 1000097,
"name": "Jane Roe",
"email": "jane.roe@example.com"
}
],
"values": {
"-1": "Fails",
" 0": "No score",
"+1": "Verified"
}
},
"Code-Review": {
"all": [
{
"value": -1,
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com"
},
{
"value": 1,
"_account_id": 1000097,
"name": "Jane Roe",
"email": "jane.roe@example.com"
}
]
"values": {
"-2": "This shall not be merged",
"-1": "I would prefer this is not merged as is",
" 0": "No score",
"+1": "Looks good to me, but someone else must approve",
"+2": "Looks good to me, approved"
}
}
},
"permitted_labels": {
"Verified": [
"-1",
" 0",
"+1"
],
"Code-Review": [
"-2",
"-1",
" 0",
"+1",
"+2"
]
},
"removable_reviewers": [
{
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com"
},
{
"_account_id": 1000097,
"name": "Jane Roe",
"email": "jane.roe@example.com"
}
],
"current_revision": "674ac754f91e64a0efb8087e59a176484bd534d1",
"revisions": {
"674ac754f91e64a0efb8087e59a176484bd534d1": {
"_number": 2,
"ref": "refs/changes/65/3965/2",
"fetch": {
"http": {
"url": "http://gerrit/myProject",
"ref": "refs/changes/65/3965/2"
}
}
}
}
----
[[get-related-changes]]
=== Get Related Changes
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/related'
--
Retrieves related changes of a revision. Related changes are changes that either
depend on, or are dependencies of the revision.
.Request
----
GET /changes/gerrit~master~I5e4fc08ce34d33c090c9e0bf320de1b17309f774/revisions/b1cb4caa6be46d12b94c25aa68aebabcbb3f53fe/related HTTP/1.0
----
As result a link:#related-changes-info[RelatedChangesInfo] entity is returned
describing the related changes.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"changes": [
{
"change_id": "Ic62ae3103fca2214904dbf2faf4c861b5f0ae9b5",
"commit": {
"commit": "78847477532e386f5a2185a4e8c90b2509e354e3",
"parents": [
{
"commit": "bb499510bbcdbc9164d96b0dbabb4aa45f59a87e"
}
],
"author": {
"name": "David Ostrovsky",
"email": "david@ostrovsky.org",
"date": "2014-07-12 15:04:24.000000000",
"tz": 120
},
"subject": "Remove Solr"
},
"_change_number": 58478,
"_revision_number": 2,
"_current_revision_number": 2
},
{
"change_id": "I5e4fc08ce34d33c090c9e0bf320de1b17309f774",
"commit": {
"commit": "b1cb4caa6be46d12b94c25aa68aebabcbb3f53fe",
"parents": [
{
"commit": "d898f12a9b7a92eb37e7a80636195a1b06417aad"
}
],
"author": {
"name": "David Pursehouse",
"email": "david.pursehouse@sonymobile.com",
"date": "2014-06-24 02:01:28.000000000",
"tz": 540
},
"subject": "Add support for secondary index with Elasticsearch"
},
"_change_number": 58081,
"_revision_number": 10,
"_current_revision_number": 10
}
]
}
----
[[set-review]]
=== Set Review
--
'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/review'
--
Sets a review on a revision.
The review must be provided in the request body as a
link:#review-input[ReviewInput] entity.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/review HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"message": "Some nits need to be fixed.",
"labels": {
"Code-Review": -1
},
"comments": {
"gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": [
{
"line": 23,
"message": "[nit] trailing whitespace"
},
{
"line": 49,
"message": "[nit] s/conrtol/control"
},
{
"range": {
"start_line": 50,
"start_character": 0,
"end_line": 55,
"end_character": 20
},
"message": "Incorrect indentation"
}
]
}
}
----
As response a link:#review-info[ReviewInfo] entity is returned that
describes the applied labels.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"labels": {
"Code-Review": -1
}
}
----
A review cannot be set on a change edit. Trying to post a review for a
change edit fails with `409 Conflict`.
[[rebase-revision]]
=== Rebase Revision
--
'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/rebase'
--
Rebases a revision.
Optionally, the parent revision can be changed to another patch set through the
link:#rebase-input[RebaseInput] entity.
.Request
----
POST /changes/myProject~master~I3ea943139cb62e86071996f2480e58bf3eeb9dd2/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/rebase HTTP/1.0
Content-Type: application/json;charset=UTF-8
{
"base" : "1234",
}
----
As response a link:#change-info[ChangeInfo] entity is returned that
describes the rebased change. Information about the current patch set
is included.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "myProject~master~I3ea943139cb62e86071996f2480e58bf3eeb9dd2",
"project": "myProject",
"branch": "master",
"change_id": "I3ea943139cb62e86071996f2480e58bf3eeb9dd2",
"subject": "Implement Feature X",
"status": "NEW",
"created": "2013-02-01 09:59:32.126000000",
"updated": "2013-02-21 11:16:36.775000000",
"mergeable": false,
"insertions": 21,
"deletions": 21,
"_number": 4799,
"owner": {
"name": "John Doe"
},
"current_revision": "27cc4558b5a3d3387dd11ee2df7a117e7e581822",
"revisions": {
"27cc4558b5a3d3387dd11ee2df7a117e7e581822": {
"_number": 2,
"ref": "refs/changes/99/4799/2",
"fetch": {
"http": {
"url": "http://gerrit:8080/myProject",
"ref": "refs/changes/99/4799/2"
}
},
"commit": {
"parents": [
{
"commit": "b4003890dadd406d80222bf1ad8aca09a4876b70",
"subject": "Implement Feature A"
}
],
"author": {
"name": "John Doe",
"email": "john.doe@example.com",
"date": "2013-05-07 15:21:27.000000000",
"tz": 120
},
"committer": {
"name": "Gerrit Code Review",
"email": "gerrit-server@example.com",
"date": "2013-05-07 15:35:43.000000000",
"tz": 120
},
"subject": "Implement Feature X",
"message": "Implement Feature X\n\nAdded feature X."
}
}
}
----
If the revision cannot be rebased, e.g. due to conflicts, the response is
"`409 Conflict`" and the error message is contained in the response
body.
.Response
----
HTTP/1.1 409 Conflict
Content-Disposition: attachment
Content-Type: text/plain; charset=UTF-8
The change could not be rebased due to a path conflict during merge.
----
[[submit-revision]]
=== Submit Revision
--
'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/submit'
--
Submits a revision.
The request body only needs to include a link:#submit-input[
SubmitInput] entity if the request should wait for the merge to
complete.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/submit HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"wait_for_merge": true
}
----
As response a link:#submit-info[SubmitInfo] entity is returned that
describes the status of the submitted change.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"status": "MERGED"
}
----
If the revision cannot be submitted, e.g. because the submit rule
doesn't allow submitting the revision or the revision is not the
current revision, the response is "`409 Conflict`" and the error
message is contained in the response body.
.Response
----
HTTP/1.1 409 Conflict
Content-Type: text/plain; charset=UTF-8
"revision 674ac754f91e64a0efb8087e59a176484bd534d1 is not current revision"
----
[[publish-draft-revision]]
=== Publish Draft Revision
--
'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/publish'
--
Publishes a draft revision.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/publish HTTP/1.0
Content-Type: application/json; charset=UTF-8
----
.Response
----
HTTP/1.1 204 No Content
----
[[delete-draft-revision]]
=== Delete Draft Revision
--
'DELETE /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]'
--
Deletes a draft revision.
.Request
----
DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1 HTTP/1.0
Content-Type: application/json; charset=UTF-8
----
.Response
----
HTTP/1.1 204 No Content
----
[[get-patch]]
=== Get Patch
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/patch'
--
Gets the formatted patch for one revision.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/patch HTTP/1.0
----
The formatted patch is returned as text encoded inside base64:
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: text/plain; charset=ISO-8859-1
X-FYI-Content-Encoding: base64
X-FYI-Content-Type: application/mbox
RnJvbSA3ZGFkY2MxNTNmZGVhMTdhYTg0ZmYzMmE2ZTI0NWRiYjY...
----
Adding query parameter `zip` (for example `/changes/.../patch?zip`)
returns the patch as a single file inside of a ZIP archive. Clients
can expand the ZIP to obtain the plain text patch, avoiding the
need for a base64 decoding step. This option implies `download`.
Query parameter `download` (e.g. `/changes/.../patch?download`)
will suggest the browser save the patch as `commitsha1.diff.base64`,
for later processing by command line tools.
[[get-mergeable]]
=== Get Mergeable
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/mergeable'
--
Gets the method the server will use to submit (merge) the change and
an indicator if the change is currently mergeable.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/mergeable HTTP/1.0
----
As response a link:#mergeable-info[MergeableInfo] entity is returned.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
submit_type: "MERGE_IF_NECESSARY",
mergeable: true,
}
----
If the `other-branches` parameter is specified, the mergeability will also be
checked for all other branches.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/mergeable?other-branches HTTP/1.0
----
The response will then contain a list of all other branches where this changes
could merge cleanly.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
submit_type: "MERGE_IF_NECESSARY",
mergeable: true,
mergeable_into: [
"refs/heads/stable-2.7",
"refs/heads/stable-2.8",
]
}
----
[[get-submit-type]]
=== Get Submit Type
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/submit_type'
--
Gets the method the server will use to submit (merge) the change.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/submit_type HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
"MERGE_IF_NECESSARY"
----
[[test-submit-type]]
=== Test Submit Type
--
'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/test.submit_type'
--
Tests the submit_type Prolog rule in the project, or the one given.
Request body may be either the Prolog code as `text/plain` or a
link:#rule-input[RuleInput] object. The query parameter `filters`
may be set to `SKIP` to bypass parent project filters while testing
a project-specific rule.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/test.submit_type HTTP/1.0
Content-Type: text/plain; charset-UTF-8
submit_type(cherry_pick).
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
"CHERRY_PICK"
----
[[test-submit-rule]]
=== Test Submit Rule
--
'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/test.submit_rule'
--
Tests the submit_rule Prolog rule in the project, or the one given.
Request body may be either the Prolog code as `text/plain` or a
link:#rule-input[RuleInput] object. The query parameter `filters`
may be set to `SKIP` to bypass parent project filters while testing
a project-specific rule.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/test.submit_rule?filters=SKIP HTTP/1.0
Content-Type: text/plain; charset-UTF-8
submit_rule(submit(R)) :-
R = label('Any-Label-Name', reject(_)).
----
The response is a list of link:#submit-record[SubmitRecord] entries
describing the permutations that satisfy the tested submit rule.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
[
{
"status": "NOT_READY",
"reject": {
"Any-Label-Name": {}
}
}
]
----
When testing with the `curl` command line client the
`--data-binary @rules.pl` flag should be used to ensure
all LFs are included in the Prolog code:
----
curl -X POST \
-H 'Content-Type: text/plain; charset=UTF-8' \
--data-binary @rules.pl \
http://.../test.submit_rule
----
[[list-drafts]]
=== List Drafts
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/drafts/'
--
Lists the draft comments of a revision that belong to the calling
user.
As result a map is returned that maps the file path to a list of
link:#comment-info[CommentInfo] entries. The entries in the map are
sorted by file path.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/drafts/ HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": [
{
"id": "TvcXrmjM",
"line": 23,
"message": "[nit] trailing whitespace",
"updated": "2013-02-26 15:40:43.986000000"
},
{
"id": "TveXwFiA",
"line": 49,
"in_reply_to": "TfYX-Iuo",
"message": "Done",
"updated": "2013-02-26 15:40:45.328000000"
}
]
}
----
[[create-draft]]
=== Create Draft
--
'PUT /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/drafts'
--
Creates a draft comment on a revision.
The new draft comment must be provided in the request body inside a
link:#comment-input[CommentInput] entity.
.Request
----
PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/drafts HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"line": 23,
"message": "[nit] trailing whitespace"
}
----
As response a link:#comment-info[CommentInfo] entity is returned that
describes the draft comment.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "TvcXrmjM",
"path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"line": 23,
"message": "[nit] trailing whitespace",
"updated": "2013-02-26 15:40:43.986000000"
}
----
[[get-draft]]
=== Get Draft
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/drafts/link:#draft-id[\{draft-id\}]'
--
Retrieves a draft comment of a revision that belongs to the calling
user.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/drafts/TvcXrmjM HTTP/1.0
----
As response a link:#comment-info[CommentInfo] entity is returned that
describes the draft comment.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "TvcXrmjM",
"path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"line": 23,
"message": "[nit] trailing whitespace",
"updated": "2013-02-26 15:40:43.986000000"
}
----
[[update-draft]]
=== Update Draft
--
'PUT /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/drafts/link:#draft-id[\{draft-id\}]'
--
Updates a draft comment on a revision.
The new draft comment must be provided in the request body inside a
link:#comment-input[CommentInput] entity.
.Request
----
PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/drafts/TvcXrmjM HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"line": 23,
"message": "[nit] trailing whitespace"
}
----
As response a link:#comment-info[CommentInfo] entity is returned that
describes the draft comment.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "TvcXrmjM",
"path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"line": 23,
"message": "[nit] trailing whitespace",
"updated": "2013-02-26 15:40:43.986000000"
}
----
[[delete-draft]]
=== Delete Draft
--
'DELETE /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/drafts/link:#draft-id[\{draft-id\}]'
--
Deletes a draft comment from a revision.
.Request
----
DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/drafts/TvcXrmjM HTTP/1.0
----
.Response
----
HTTP/1.1 204 No Content
----
[[list-comments]]
=== List Comments
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/comments/'
--
Lists the published comments of a revision.
As result a map is returned that maps the file path to a list of
link:#comment-info[CommentInfo] entries. The entries in the map are
sorted by file path and only include file (or inline) comments. Use
the link:#get-change-detail[Get Change Detail] endpoint to retrieve
the general change message (or comment).
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/comments/ HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": [
{
"id": "TvcXrmjM",
"line": 23,
"message": "[nit] trailing whitespace",
"updated": "2013-02-26 15:40:43.986000000",
"author": {
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com"
}
},
{
"id": "TveXwFiA",
"line": 49,
"in_reply_to": "TfYX-Iuo",
"message": "Done",
"updated": "2013-02-26 15:40:45.328000000",
"author": {
"_account_id": 1000097,
"name": "Jane Roe",
"email": "jane.roe@example.com"
}
}
]
}
----
[[get-comment]]
=== Get Comment
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/comments/link:#comment-id[\{comment-id\}]'
--
Retrieves a published comment of a revision.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/comments/TvcXrmjM HTTP/1.0
----
As response a link:#comment-info[CommentInfo] entity is returned that
describes the published comment.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "TvcXrmjM",
"path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"line": 23,
"message": "[nit] trailing whitespace",
"updated": "2013-02-26 15:40:43.986000000",
"author": {
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com"
}
}
----
[[list-files]]
=== List Files
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/files/'
--
Lists the files that were modified, added or deleted in a revision.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/ HTTP/1.0
----
As result a map is returned that maps the file path to a list of
link:#file-info[FileInfo] entries. The entries in the map are
sorted by file path.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"/COMMIT_MSG": {
"status": "A",
"lines_inserted": 7
},
"gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": {
"lines_inserted": 5,
"lines_deleted": 3
}
}
----
The request parameter `reviewed` changes the response to return a list
of the paths the caller has marked as reviewed. Clients that also
need the FileInfo should make two requests.
The request parameter `q` changes the response to return a list
of all files (modified or unmodified) that contain that substring
in the path name. This is useful to implement suggestion services
finding a file by partial name.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/?reviewed HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
[
"/COMMIT_MSG",
"gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
]
----
[[get-content]]
=== Get Content
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/files/link:#file-id[\{file-id\}]/content'
--
Gets the content of a file from a certain revision.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/content HTTP/1.0
----
The content is returned as base64 encoded string. The HTTP response
Content-Type is always `text/plain`, reflecting the base64 wrapping.
A Gerrit-specific `X-FYI-Content-Type` header is returned describing
the server detected content type of the file.
If only the content type is required, callers should use HEAD to
avoid downloading the encoded file contents.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: text/plain; charset=ISO-8859-1
X-FYI-Content-Encoding: base64
X-FYI-Content-Type: text/xml
Ly8gQ29weXJpZ2h0IChDKSAyMDEwIFRoZSBBbmRyb2lkIE9wZW4gU291cmNlIFByb2plY...
----
Alternatively, if the only value of the Accept request header is
`application/json` the content is returned as JSON string and
`X-FYI-Content-Encoding` is set to `json`.
[[get-diff]]
=== Get Diff
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/files/link:#file-id[\{file-id\}]/diff'
--
Gets the diff of a file from a certain revision.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/diff HTTP/1.0
----
As response a link:#diff-info[DiffInfo] entity is returned that describes the diff.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]
{
"meta_a": {
"name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"content_type": "text/x-java-source",
"lines": 372
},
"meta_b": {
"name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"content_type": "text/x-java-source",
"lines": 578
},
"change_type": "MODIFIED",
"diff_header": [
"diff --git a/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java b/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"index 59b7670..9faf81c 100644",
"--- a/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"+++ b/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java"
],
"content": [
{
"ab": [
"// Copyright (C) 2010 The Android Open Source Project",
"//",
"// Licensed under the Apache License, Version 2.0 (the \"License\");",
"// you may not use this file except in compliance with the License.",
"// You may obtain a copy of the License at",
"//",
"// http://www.apache.org/licenses/LICENSE-2.0",
"//",
"// Unless required by applicable law or agreed to in writing, software",
"// distributed under the License is distributed on an \"AS IS\" BASIS,",
"// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.",
"// See the License for the specific language governing permissions and",
"// limitations under the License."
]
},
{
"b": [
"//",
"// Add some more lines in the header."
]
},
{
"ab": [
"",
"package com.google.gerrit.server.project;",
"",
"import com.google.common.collect.Maps;",
...
]
}
...
]
}
----
If the `intraline` parameter is specified, intraline differences are included in the diff.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/b6b9c10649b9041884046119ab794374470a1b45/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/diff?intraline HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]
{
"meta_a": {
"name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"content_type": "text/x-java-source",
"lines": 372
},
"meta_b": {
"name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"content_type": "text/x-java-source",
"lines": 578
},
"change_type": "MODIFIED",
"diff_header": [
"diff --git a/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java b/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"index 59b7670..9faf81c 100644",
"--- a/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"+++ b/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java"
],
"content": [
...
{
"a": [
"/** Manages access control for Git references (aka branches, tags). */"
],
"b": [
"/** Manages access control for the Git references (aka branches, tags). */"
],
"edit_a": [],
"edit_b": [
[
31,
4
]
]
}
]
}
----
The `base` parameter can be specified to control the base patch set from which the diff should
be generated.
[[weblinks-only]]
If the `weblinks-only` parameter is specified, only the diff web links are returned.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/b6b9c10649b9041884046119ab794374470a1b45/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/diff?base=2 HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]
{
"meta_a": {
"name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"content_type": "text/x-java-source",
"lines": 578
},
"meta_b": {
"name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"content_type": "text/x-java-source",
"lines": 578
},
"change_type": "MODIFIED",
"content": [
{
"skip": 578
}
]
}
----
The `ignore-whitespace` parameter can be specified to control how whitespace differences are
reported in the result. Valid values are `NONE`, `TRAILING`, `CHANGED` or `ALL`.
The `context` parameter can be specified to control the number of lines of surrounding context
in the diff. Valid values are `ALL` or number of lines.
[[set-reviewed]]
=== Set Reviewed
--
'PUT /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/files/link:#file-id[\{file-id\}]/reviewed'
--
Marks a file of a revision as reviewed by the calling user.
.Request
----
PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/reviewed HTTP/1.0
----
.Response
----
HTTP/1.1 201 Created
----
If the file was already marked as reviewed by the calling user the
response is "`200 OK`".
[[delete-reviewed]]
=== Delete Reviewed
--
'DELETE /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/files/link:#file-id[\{file-id\}]/reviewed'
--
Deletes the reviewed flag of the calling user from a file of a revision.
.Request
----
DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/reviewed HTTP/1.0
----
.Response
----
HTTP/1.1 204 No Content
----
[[cherry-pick]]
=== Cherry Pick Revision
--
'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/cherrypick'
--
Cherry picks a revision to a destination branch.
The commit message and destination branch must be provided in the request body inside a
link:#cherrypick-input[CherryPickInput] entity.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/cherrypick HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"message" : "Implementing Feature X",
"destination" : "release-branch"
}
----
As response a link:#change-info[ChangeInfo] entity is returned that
describes the resulting cherry picked change.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9941",
"project": "myProject",
"branch": "release-branch",
"change_id": "I8473b95934b5732ac55d26311a706c9c2bde9941",
"subject": "Implementing Feature X",
"status": "NEW",
"created": "2013-02-01 09:59:32.126000000",
"updated": "2013-02-21 11:16:36.775000000",
"mergeable": true,
"insertions": 12,
"deletions": 11,
"_number": 3965,
"owner": {
"name": "John Doe"
}
}
----
[[ids]]
== IDs
[[account-id]]
=== link:rest-api-accounts.html#account-id[\{account-id\}]
--
--
[[change-id]]
=== \{change-id\}
Identifier that uniquely identifies one change.
This can be:
* an ID of the change in the format "'$$<project>~<branch>~<Change-Id>$$'",
where for the branch the `refs/heads/` prefix can be omitted
("$$myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940$$")
* a Change-Id if it uniquely identifies one change
("I8473b95934b5732ac55d26311a706c9c2bde9940")
* a legacy numeric change ID ("4247")
[[comment-id]]
=== \{comment-id\}
UUID of a published comment.
[[draft-id]]
=== \{draft-id\}
UUID of a draft comment.
[[file-id]]
\{file-id\}
~~~~~~~~~~~~
The path of the file.
[[revision-id]]
=== \{revision-id\}
Identifier that uniquely identifies one revision of a change.
This can be:
* the literal `current` to name the current patch set/revision
* a commit ID ("674ac754f91e64a0efb8087e59a176484bd534d1")
* an abbreviated commit ID that uniquely identifies one revision of the
change ("674ac754"), at least 4 digits are required
* a legacy numeric patch number ("1" for first patch set of the change)
[[json-entities]]
== JSON Entities
[[abandon-input]]
=== AbandonInput
The `AbandonInput` entity contains information for abandoning a change.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`message` |optional|
Message to be added as review comment to the change when abandoning the
change.
|===========================
[[action-info]]
=== ActionInfo
The `ActionInfo` entity describes a REST API call the client can
make to manipulate a resource. These are frequently implemented by
plugins and may be discovered at runtime.
[options="header",cols="1,^1,5"]
|====================================
|Field Name ||Description
|`method` |optional|
HTTP method to use with the action. Most actions use `POST`, `PUT`
or `DELETE` to cause state changes.
|`label` |optional|
Short title to display to a user describing the action. In the
Gerrit web interface the label is used as the text on the button
presented in the UI.
|`title` |optional|
Longer text to display describing the action. In a web UI this
should be the title attribute of the element, displaying when
the user hovers the mouse.
|`enabled` |optional|
If true the action is permitted at this time and the caller is
likely allowed to execute it. This may change if state is updated
at the server or permissions are modified. Not present if false.
|====================================
[[add-reviewer-result]]
=== AddReviewerResult
The `AddReviewerResult` entity describes the result of adding a
reviewer to a change.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`reviewers` |optional|
The newly added reviewers as a list of link:#reviewer-info[
ReviewerInfo] entities.
|`error` |optional|
Error message explaining why the reviewer could not be added. +
If a group was specified in the input and an error is returned, it
means that none of the members were added as reviewer.
|`confirm` |`false` if not set|
Whether adding the reviewer requires confirmation.
|===========================
[[approval-info]]
=== ApprovalInfo
The `ApprovalInfo` entity contains information about an approval from a
user for a label on a change.
`ApprovalInfo` has the same fields as
link:rest-api-accounts.html#account-info[AccountInfo].
In addition `ApprovalInfo` has the following fields:
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`value` |optional|
The vote that the user has given for the label. If present and zero, the
user is permitted to vote on the label. If absent, the user is not
permitted to vote on that label.
|`date` |optional|
The time and date describing when the approval was made.
|===========================
[[change-edit-input]]
=== ChangeEditInput
The `ChangeEditInput` entity contains information for restoring a
path within change edit.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`restore_path`|optional|Path to file to restore.
|`old_path` |optional|Old path to file to rename.
|`new_path` |optional|New path to file to rename.
|===========================
[[change-edit-message-input]]
=== ChangeEditMessageInput
The `ChangeEditMessageInput` entity contains information for changing
the commit message within a change edit.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`message` ||New commit message.
|===========================
[[change-info]]
=== ChangeInfo
The `ChangeInfo` entity contains information about a change.
[options="header",cols="1,^1,5"]
|==================================
|Field Name ||Description
|`id` ||
The ID of the change in the format "'<project>\~<branch>~<Change-Id>'",
where 'project', 'branch' and 'Change-Id' are URL encoded. For 'branch' the
`refs/heads/` prefix is omitted.
|`project` ||The name of the project.
|`branch` ||
The name of the target branch. +
The `refs/heads/` prefix is omitted.
|`topic` |optional|The topic to which this change belongs.
|`change_id` ||The Change-Id of the change.
|`subject` ||
The subject of the change (header line of the commit message).
|`status` ||
The status of the change (`NEW`, `SUBMITTED`, `MERGED`, `ABANDONED`,
`DRAFT`).
|`created` ||
The link:rest-api.html#timestamp[timestamp] of when the change was
created.
|`updated` ||
The link:rest-api.html#timestamp[timestamp] of when the change was last
updated.
|`starred` |not set if `false`|
Whether the calling user has starred this change.
|`reviewed` |not set if `false`|
Whether the change was reviewed by the calling user.
Only set if link:#reviewed[reviewed] is requested.
|`mergeable` |optional|
Whether the change is mergeable. +
Not set for merged changes, or if the change has not yet been tested.
|`insertions` ||
Number of inserted lines.
|`deletions` ||
Number of deleted lines.
|`_number` ||The legacy numeric ID of the change.
|`owner` ||
The owner of the change as an link:rest-api-accounts.html#account-info[
AccountInfo] entity.
|`actions` |optional|
Actions the caller might be able to perform on this revision. The
information is a map of view name to link:#action-info[ActionInfo]
entities.
|`labels` |optional|
The labels of the change as a map that maps the label names to
link:#label-info[LabelInfo] entries. +
Only set if link:#labels[labels] or link:#detailed-labels[detailed
labels] are requested.
|`permitted_labels` |optional|
A map of the permitted labels that maps a label name to the list of
values that are allowed for that label. +
Only set if link:#detailed-labels[detailed labels] are requested.
|`removable_reviewers`|optional|
The reviewers that can be removed by the calling user as a list of
link:rest-api-accounts.html#account-info[AccountInfo] entities. +
Only set if link:#detailed-labels[detailed labels] are requested.
|`messages`|optional|
Messages associated with the change as a list of
link:#change-message-info[ChangeMessageInfo] entities. +
Only set if link:#messages[messages] are requested.
|`current_revision` |optional|
The commit ID of the current patch set of this change. +
Only set if link:#current-revision[the current revision] is requested
or if link:#all-revisions[all revisions] are requested.
|`revisions` |optional|
All patch sets of this change as a map that maps the commit ID of the
patch set to a link:#revision-info[RevisionInfo] entity. +
Only set if link:#current-revision[the current revision] is requested
(in which case it will only contain a key for the current revision) or
if link:#all-revisions[all revisions] are requested.
|`_more_changes` |optional, not set if `false`|
Whether the query would deliver more results if not limited. +
Only set on the last change that is returned.
|`problems` |optional|
A list of link:#problem-info[ProblemInfo] entities describing potential
problems with this change. Only set if link:#check[CHECK] is set.
|`base_change` |optional|
A link:#change-id[\{change-id\}] that identifies the base change for a create
change operation. Only used for the link:#create-change[CreateChange] endpoint.
|==================================
[[change-message-info]]
=== ChangeMessageInfo
The `ChangeMessageInfo` entity contains information about a message
attached to a change.
[options="header",cols="1,^1,5"]
|==================================
|Field Name ||Description
|`id` ||The ID of the message.
|`author` |optional|
Author of the message as an
link:rest-api-accounts.html#account-info[AccountInfo] entity. +
Unset if written by the Gerrit system.
|`date` ||
The link:rest-api.html#timestamp[timestamp] this message was posted.
|`message` ||The text left by the user.
|`_revision_number` |optional|
Which patchset (if any) generated this message.
|==================================
[[cherrypick-input]]
=== CherryPickInput
The `CherryPickInput` entity contains information for cherry-picking a change to a new branch.
[options="header",cols="1,6"]
|===========================
|Field Name |Description
|`message` |Commit message for the cherry-picked change
|`destination` |Destination branch
|===========================
[[comment-info]]
=== CommentInfo
The `CommentInfo` entity contains information about an inline comment.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`id` ||The URL encoded UUID of the comment.
|`path` |optional|
The path of the file for which the inline comment was done. +
Not set if returned in a map where the key is the file path.
|`side` |optional|
The side on which the comment was added. +
Allowed values are `REVISION` and `PARENT`. +
If not set, the default is `REVISION`.
|`line` |optional|
The number of the line for which the comment was done. +
If range is set, this equals the end line of the range. +
If neither line nor range is set, it's a file comment.
|`range` |optional|
The range of the comment as a link:#comment-range[CommentRange]
entity.
|`in_reply_to` |optional|
The URL encoded UUID of the comment to which this comment is a reply.
|`message` |optional|The comment message.
|`updated` ||
The link:rest-api.html#timestamp[timestamp] of when this comment was
written.
|`author` |optional|
The author of the message as an
link:rest-api-accounts.html#account-info[AccountInfo] entity. +
Unset for draft comments, assumed to be the calling user.
|===========================
[[comment-input]]
=== CommentInput
The `CommentInput` entity contains information for creating an inline
comment.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`id` |optional|
The URL encoded UUID of the comment if an existing draft comment should
be updated.
|`path` |optional|
The path of the file for which the inline comment should be added. +
Doesn't need to be set if contained in a map where the key is the file
path.
|`side` |optional|
The side on which the comment should be added. +
Allowed values are `REVISION` and `PARENT`. +
If not set, the default is `REVISION`.
|`line` |optional|
The number of the line for which the comment should be added. +
`0` if it is a file comment. +
If neither line nor range is set, a file comment is added. +
If range is set, this value is ignored in favor of the `end_line` of the range.
|`range` |optional|
The range of the comment as a link:#comment-range[CommentRange]
entity.
|`in_reply_to` |optional|
The URL encoded UUID of the comment to which this comment is a reply.
|`updated` |optional|
The link:rest-api.html#timestamp[timestamp] of this comment. +
Accepted but ignored.
|`message` |optional|
The comment message. +
If not set and an existing draft comment is updated, the existing draft
comment is deleted.
|===========================
[[comment-range]]
=== CommentRange
The `CommentRange` entity describes the range of an inline comment.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`start_line` ||The start line number of the range.
|`start_character` ||The character position in the start line.
|`end_line` ||The end line number of the range.
|`end_character` ||The character position in the end line.
|===========================
[[commit-info]]
=== CommitInfo
The `CommitInfo` entity contains information about a commit.
[options="header",cols="1,6"]
|==========================
|Field Name |Description
|`commit` |The commit ID.
|`parents` |
The parent commits of this commit as a list of
link:#commit-info[CommitInfo] entities. In each parent
only the `commit` and `subject` fields are populated.
|`author` |The author of the commit as a
link:#git-person-info[GitPersonInfo] entity.
|`committer` |The committer of the commit as a
link:#git-person-info[GitPersonInfo] entity.
|`subject` |
The subject of the commit (header line of the commit message).
|`message` |The commit message.
|`web_links` |optional|
Links to the commit in external sites as a list of
link:#web-link-info[WebLinkInfo] entities.
|==========================
[[diff-content]]
=== DiffContent
The `DiffContent` entity contains information about the content differences
in a file.
[options="header",cols="1,^1,5"]
|==========================
|Field Name ||Description
|`a` |optional|Content only in the file on side A (deleted in B).
|`b` |optional|Content only in the file on side B (added in B).
|`ab` |optional|Content in the file on both sides (unchanged).
|`edit_a` |only present during a replace, i.e. both `a` and `b` are present|
Text sections deleted from side A as a
link:#diff-intraline-info[DiffIntralineInfo] entity.
|`edit_b` |only present during a replace, i.e. both `a` and `b` are present|
Text sections inserted in side B as a
link:#diff-intraline-info[DiffIntralineInfo] entity.
|`skip` |optional|count of lines skipped on both sides when the file is
too large to include all common lines.
|`common` |optional|Set to `true` if the region is common according
to the requested ignore-whitespace parameter, but a and b contain
differing amounts of whitespace. When present and true a and b are
used instead of ab.
|==========================
[[diff-file-meta-info]]
=== DiffFileMetaInfo
The `DiffFileMetaInfo` entity contains meta information about a file diff.
[options="header",cols="1,^1,5"]
|==========================
|Field Name ||Description
|`name` ||The name of the file.
|`content_type`||The content type of the file.
|`lines` ||The total number of lines in the file.
|`web_links` |optional|
Links to the file in external sites as a list of
link:rest-api-changes.html#web-link-info[WebLinkInfo] entries.
|==========================
[[diff-info]]
=== DiffInfo
The `DiffInfo` entity contains information about the diff of a file
in a revision.
If the link:#weblinks-only[weblinks-only] parameter is specified, only
the `web_links` field is set.
[options="header",cols="1,^1,5"]
|==========================
|Field Name ||Description
|`meta_a` |not present when the file is added|
Meta information about the file on side A as a
link:#diff-file-meta-info[DiffFileMetaInfo] entity.
|`meta_b` |not present when the file is deleted|
Meta information about the file on side B as a
link:#diff-file-meta-info[DiffFileMetaInfo] entity.
|`change_type` ||The type of change (`ADDED`, `MODIFIED`, `DELETED`, `RENAMED`
`COPIED`, `REWRITE`).
|`intraline_status`|only set when the `intraline` parameter was specified in the request|
Intraline status (`OK`, `ERROR`, `TIMEOUT`).
|`diff_header` ||A list of strings representing the patch set diff header.
|`content` ||The content differences in the file as a list of
link:#diff-content[DiffContent] entities.
|`web_links` |optional|
Links to the file diff in external sites as a list of
link:rest-api-changes.html#diff-web-link-info[DiffWebLinkInfo] entries.
|`binary` |not set if `false`|Whether the file is binary.
|==========================
[[diff-intraline-info]]
=== DiffIntralineInfo
The `DiffIntralineInfo` entity contains information about intraline edits in a
file.
The information consists of a list of `<skip length, mark length>` pairs, where
the skip length is the number of characters between the end of the previous edit
and the start of this edit, and the mark length is the number of edited characters
following the skip. The start of the edits is from the beginning of the related
diff content lines.
Note that the implied newline character at the end of each line is included in
the length calculation, and thus it is possible for the edits to span newlines.
[[diff-web-link-info]]
=== DiffWebLinkInfo
The `DiffWebLinkInfo` entity describes a link on a diff screen to an
external site.
[options="header",cols="1,6"]
|=======================
|Field Name|Description
|`name` |The link name.
|`url` |The link URL.
|`image_url`|URL to the icon of the link.
|show_on_side_by_side_diff_view|
Whether the web link should be shown on the side-by-side diff screen.
|show_on_unified_diff_view|
Whether the web link should be shown on the unified diff screen.
|=======================
[[edit-file-info]]
=== EditFileInfo
The `EditFileInfo` entity contains additional information
of a file within a change edit.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`web_links` |optional|
Links to the diff info in external sites as a list of
link:#web-link-info[WebLinkInfo] entities.
|===========================
[[edit-info]]
=== EditInfo
The `EditInfo` entity contains information about a change edit.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`commit` ||The commit of change edit as
link:#commit-info[CommitInfo] entity.
|`baseRevision`||The revision of the patch set change edit is based on.
|`fetch` ||
Information about how to fetch this patch set. The fetch information is
provided as a map that maps the protocol name ("`git`", "`http`",
"`ssh`") to link:#fetch-info[FetchInfo] entities.
|`files` |optional|
The files of the change edit as a map that maps the file names to
link:#file-info[FileInfo] entities.
|===========================
[[fetch-info]]
=== FetchInfo
The `FetchInfo` entity contains information about how to fetch a patch
set via a certain protocol.
[options="header",cols="1,^1,5"]
|==========================
|Field Name ||Description
|`url` ||The URL of the project.
|`ref` ||The ref of the patch set.
|`commands` |optional|
The download commands for this patch set as a map that maps the command
names to the commands. +
Only set if link:#download_commands[download commands] are requested.
|==========================
[[file-info]]
=== FileInfo
The `FileInfo` entity contains information about a file in a patch set.
[options="header",cols="1,^1,5"]
|=============================
|Field Name ||Description
|`status` |optional|
The status of the file ("`A`"=Added, "`D`"=Deleted, "`R`"=Renamed,
"`C`"=Copied, "`W`"=Rewritten). +
Not set if the file was Modified ("`M`").
|`binary` |not set if `false`|Whether the file is binary.
|`old_path` |optional|
The old file path. +
Only set if the file was renamed or copied.
|`lines_inserted`|optional|
Number of inserted lines. +
Not set for binary files or if no lines were inserted.
|`lines_deleted` |optional|
Number of deleted lines. +
Not set for binary files or if no lines were deleted.
|=============================
[[git-person-info]]
=== GitPersonInfo
The `GitPersonInfo` entity contains information about the
author/committer of a commit.
[options="header",cols="1,6"]
|==========================
|Field Name |Description
|`name` |The name of the author/committer.
|`email` |The email address of the author/committer.
|`date` |The link:rest-api.html#timestamp[timestamp] of when
this identity was constructed.
|`tz` |The timezone offset from UTC of when this identity was
constructed.
|==========================
[[group-base-info]]
=== GroupBaseInfo
The `GroupBaseInfo` entity contains base information about the group.
[options="header",cols="1,6"]
|==========================
|Field Name |Description
|`id` |The id of the group.
|`name` |The name of the group.
|==========================
[[included-in-info]]
=== IncludedInInfo
The `IncludedInInfo` entity contains information about the branches a
change was merged into and tags it was tagged with.
[options="header",cols="1,6"]
|==========================
|Field Name |Description
|`branches` | The list of branches this change was merged into.
Each branch is listed without the 'refs/head/' prefix.
|`tags` | The list of tags this change was tagged with.
Each tag is listed without the 'refs/tags/' prefix.
|==========================
[[label-info]]
=== LabelInfo
The `LabelInfo` entity contains information about a label on a change, always
corresponding to the current patch set.
There are two options that control the contents of `LabelInfo`:
link:#labels[`LABELS`] and link:#detailed-labels[`DETAILED_LABELS`].
* For a quick summary of the state of labels, use `LABELS`.
* For detailed information about labels, including exact numeric votes for all
users and the allowed range of votes for the current user, use `DETAILED_LABELS`.
==== Common fields
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`optional` |not set if `false`|
Whether the label is optional. Optional means the label may be set, but
it's neither necessary for submission nor does it block submission if
set.
|===========================
==== Fields set by `LABELS`
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`approved` |optional|One user who approved this label on the change
(voted the maximum value) as an
link:rest-api-accounts.html#account-info[AccountInfo] entity.
|`rejected` |optional|One user who rejected this label on the change
(voted the minimum value) as an
link:rest-api-accounts.html#account-info[AccountInfo] entity.
|`recommended` |optional|One user who recommended this label on the
change (voted positively, but not the maximum value) as an
link:rest-api-accounts.html#account-info[AccountInfo] entity.
|`disliked` |optional|One user who disliked this label on the change
(voted negatively, but not the minimum value) as an
link:rest-api-accounts.html#account-info[AccountInfo] entity.
|`blocking` |optional|If `true`, the label blocks submit operation.
If not set, the default is false.
|`value` |optional|The voting value of the user who
recommended/disliked this label on the change if it is not
"`+1`"/"`-1`".
|`default_value`|optional|The default voting value for the label.
This value may be outside the range specified in permitted_labels.
|===========================
==== Fields set by `DETAILED_LABELS`
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`all` |optional|List of all approvals for this label as a list
of link:#approval-info[ApprovalInfo] entities.
|`values` |optional|A map of all values that are allowed for this
label. The map maps the values ("`-2`", "`-1`", " `0`", "`+1`", "`+2`")
to the value descriptions.
|===========================
[[mergeable-info]]
=== MergeableInfo
The `MergeableInfo` entity contains information about the mergeability of a
change.
[options="header",cols="1,^1,5"]
|============================
|Field Name ||Description
|`submit_type` ||
Submit type used for this change, can be `MERGE_IF_NECESSARY`,
`FAST_FORWARD_ONLY`, `REBASE_IF_NECESSARY`, `MERGE_ALWAYS` or
`CHERRY_PICK`.
|`mergeable` ||
`true` if this change is cleanly mergeable, `false` otherwise
|`mergeable_into`|optional|
A list of other branch names where this change could merge cleanly
|============================
[[problem-info]]
=== ProblemInfo
The `ProblemInfo` entity contains a description of a potential consistency problem
with a change. These are not related to the code review process, but rather
indicate some inconsistency in Gerrit's database or repository metadata related
to the enclosing change.
[options="header",cols="1,^1,5"]
|===========================
|Field Name||Description
|`message` ||Plaintext message describing the problem with the change.
|`status` |optional|
The status of fixing the problem (`FIXED`, `FIX_FAILED`). Only set if a
fix was attempted.
|`outcome` |optional|
If `status` is set, an additional plaintext message describing the
outcome of the fix.
|===========================
[[rebase-input]]
=== RebaseInput
The `RebaseInput` entity contains information for changing parent when rebasing.
[options="header",width="50%",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`base` |optional|
The new parent revision. This can be a ref or a SHA1 to a concrete patchset. +
Alternatively, a change number can be specified, in which case the current
patch set is inferred. +
Empty string is used for rebasing directly on top of the target branch,
which effectively breaks dependency towards a parent change.
|===========================
[[related-change-and-commit-info]]
=== RelatedChangeAndCommitInfo
The `RelatedChangeAndCommitInfo` entity contains information about
a related change and commit.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`change_id` |optional|The Change-Id of the change.
|`commit` ||The commit as a
link:#commit-info[CommitInfo] entity.
|`_change_number` |optional|The change number.
|`_revision_number` |optional|The revision number.
|`_current_revision_number`|optional|The current revision number.
|===========================
[[related-changes-info]]
=== RelatedChangesInfo
The `RelatedChangesInfo` entity contains information about related
changes.
[options="header",cols="1,6"]
|===========================
|Field Name |Description
|`changes` |A list of
link:#related-change-and-commit-info[RelatedChangeAndCommitInfo] entities
describing the related changes. Sorted by git commit order, newest to
oldest. Empty if there are no related changes.
|===========================
[[restore-input]]
=== RestoreInput
The `RestoreInput` entity contains information for restoring a change.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`message` |optional|
Message to be added as review comment to the change when restoring the
change.
|===========================
[[revert-input]]
=== RevertInput
The `RevertInput` entity contains information for reverting a change.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`message` |optional|
Message to be added as review comment to the change when reverting the
change.
|===========================
[[review-info]]
=== ReviewInfo
The `ReviewInfo` entity contains information about a review.
[options="header",cols="1,6"]
|===========================
|Field Name |Description
|`labels` |
The labels of the review as a map that maps the label names to the
voting values.
|===========================
[[review-input]]
=== ReviewInput
The `ReviewInput` entity contains information for adding a review to a
revision.
[options="header",cols="1,^1,5"]
|============================
|Field Name ||Description
|`message` |optional|
The message to be added as review comment.
|`labels` |optional|
The votes that should be added to the revision as a map that maps the
label names to the voting values.
|`comments` |optional|
The comments that should be added as a map that maps a file path to a
list of link:#comment-input[CommentInput] entities.
|`strict_labels`|`true` if not set|
Whether all labels are required to be within the user's permitted ranges
based on access controls. +
If `true`, attempting to use a label not granted to the user will fail
the entire modify operation early. +
If `false`, the operation will execute anyway, but the proposed labels
will be modified to be the "best" value allowed by the access controls.
|`drafts` |optional|
Draft handling that defines how draft comments are handled that are
already in the database but that were not also described in this
input. +
Allowed values are `DELETE`, `PUBLISH` and `KEEP`. +
If not set, the default is `DELETE`.
|`notify` |optional|
Notify handling that defines to whom email notifications should be sent
after the review is stored. +
Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. +
If not set, the default is `ALL`.
|`on_behalf_of`|optional|
link:rest-api-accounts.html#account-id[\{account-id\}] the review
should be posted on behalf of. To use this option the caller must
have been granted `labelAs-NAME` permission for all keys of labels.
|============================
[[reviewer-info]]
=== ReviewerInfo
The `ReviewerInfo` entity contains information about a reviewer and its
votes on a change.
`ReviewerInfo` has the same fields as
link:rest-api-accounts.html#account-info[AccountInfo] and includes
link:#detailed-accounts[detailed account information].
In addition `ReviewerInfo` has the following fields:
[options="header",cols="1,6"]
|==========================
|Field Name |Description
|`approvals` |
The approvals of the reviewer as a map that maps the label names to the
approval values ("`-2`", "`-1`", "`0`", "`+1`", "`+2`").
|==========================
[[reviewer-input]]
=== ReviewerInput
The `ReviewerInput` entity contains information for adding a reviewer
to a change.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`reviewer` ||
The link:rest-api-accounts.html#account-id[ID] of one account that
should be added as reviewer or the link:rest-api-groups.html#group-id[
ID] of one group for which all members should be added as reviewers. +
If an ID identifies both an account and a group, only the account is
added as reviewer to the change.
|`confirmed` |optional|
Whether adding the reviewer is confirmed. +
The Gerrit server may be configured to
link:config-gerrit.html#addreviewer.maxWithoutConfirmation[require a
confirmation] when adding a group as reviewer that has many members.
|===========================
[[revision-info]]
=== RevisionInfo
The `RevisionInfo` entity contains information about a patch set.
Not all fields are returned by default. Additional fields can
be obtained by adding `o` parameters as described in
link:#list-changes[Query Changes].
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`draft` |not set if `false`|Whether the patch set is a draft.
|`has_draft_comments` |not set if `false`|Whether the patch
set has one or more draft comments by the calling user. Only set if
link:#draft_comments[DRAFT_COMMENTS] option is requested.
|`_number` ||The patch set number.
|`created` ||
The link:rest-api.html#timestamp[timestamp] of when the patch set was
created.
|`uploader` ||
The uploader of the patch set as an
link:rest-api-accounts.html#account-info[AccountInfo] entity.
|`ref` ||The Git reference for the patch set.
|`fetch` ||
Information about how to fetch this patch set. The fetch information is
provided as a map that maps the protocol name ("`git`", "`http`",
"`ssh`") to link:#fetch-info[FetchInfo] entities. This information is
only included if a plugin implementing the
link:intro-project-owner.html#download-commands[download commands]
interface is installed.
|`commit` |optional|The commit of the patch set as
link:#commit-info[CommitInfo] entity.
|`files` |optional|
The files of the patch set as a map that maps the file names to
link:#file-info[FileInfo] entities. Only set if
link:#current-files[CURRENT_FILES] or link:#all-files[ALL_FILES]
option is requested.
|`actions` |optional|
Actions the caller might be able to perform on this revision. The
information is a map of view name to link:#action-info[ActionInfo]
entities.
|`reviewed` |optional|
Indicates whether the caller is authenticated and has commented on the
current revision. Only set if link:#reviewed[REVIEWED] option is requested.
|===========================
[[rule-input]]
=== RuleInput
The `RuleInput` entity contains information to test a Prolog rule.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`rule`||
Prolog code to execute instead of the code in `refs/meta/config`.
|`filters`|`RUN` if not set|
When `RUN` filter rules in the parent projects are called to
post-process the results of the project specific rule. This
behavior matches how the rule will execute if installed. +
If `SKIP` the parent filters are not called, allowing the test
to return results from the input rule.
|===========================
[[submit-info]]
=== SubmitInfo
The `SubmitInfo` entity contains information about the change status
after submitting.
[options="header",cols="1,6"]
|==========================
|Field Name |Description
|`status` |
The status of the change after submitting, can be `MERGED` or
`SUBMITTED`. +
If `wait_for_merge` in the link:#submit-input[SubmitInput] was set to
`false` the returned status is `SUBMITTED` and the caller can't know
whether the change could be merged successfully.
|`on_behalf_of`|optional|
The link:rest-api-accounts.html#account-id[\{account-id\}] of the user on
whose behalf the action should be done. To use this option the caller must
have been granted both `Submit` and `Submit (On Behalf Of)` permissions.
The user named by `on_behalf_of` does not need to be granted the `Submit`
permission. This feature is aimed for CI solutions: the CI account can be
granted both permssions, so individual users don't need `Submit` permission
themselves. Still the changes can be submited on behalf of real users and
not with the identity of the CI account.
|==========================
[[submit-input]]
=== SubmitInput
The `SubmitInput` entity contains information for submitting a change.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`wait_for_merge`|`false` if not set|
Whether the request should wait for the merge to complete. +
If `false` the request returns immediately after the change has been
added to the merge queue and the caller can't know whether the change
could be merged successfully.
|===========================
[[submit-record]]
=== SubmitRecord
The `SubmitRecord` entity describes results from a submit_rule.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`status`||
`OK`, the change can be submitted. +
`NOT_READY`, additional labels are required before submit. +
`CLOSED`, closed changes cannot be submitted. +
`RULE_ERROR`, rule code failed with an error.
|`ok`|optional|
Map of labels that are approved; an
link:rest-api-accounts.html#account-info[AccountInfo] identifies the
voter chosen by the rule.
|`reject`|optional|
Map of labels that are preventing submit;
link:rest-api-accounts.html#account-info[AccountInfo] identifies voter.
|`need`|optional|
Map of labels that need to be given to submit. The value is
currently an empty object.
|`may`|optional|
Map of labels that can be used, but do not affect submit.
link:rest-api-accounts.html#account-info[AccountInfo] identifies voter,
if the label has been applied.
|`impossible`|optional|
Map of labels that should have been in `need` but cannot be
used by any user because of access restrictions. The value
is currently an empty object.
|`error_message`|optional|
When status is RULE_ERROR this message provides some text describing
the failure of the rule predicate.
|===========================
[[suggested-reviewer-info]]
=== SuggestedReviewerInfo
The `SuggestedReviewerInfo` entity contains information about a reviewer
that can be added to a change (an account or a group).
`SuggestedReviewerInfo` has either the `account` field that contains
the link:rest-api-accounts.html#account-info[AccountInfo] entity, or
the `group` field that contains the
link:rest-api-changes.html#group-base-info[GroupBaseInfo] entity.
[[topic-input]]
=== TopicInput
The `TopicInput` entity contains information for setting a topic.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`topic` |optional|The topic. +
The topic will be deleted if not set.
|===========================
[[web-link-info]]
=== WebLinkInfo
The `WebLinkInfo` entity describes a link to an external site.
[options="header",cols="1,6"]
|======================
|Field Name|Description
|`name` |The link name.
|`url` |The link URL.
|`image_url`|URL to the icon of the link.
|======================
GERRIT
------
Part of link:index.html[Gerrit Code Review]
SEARCHBOX
---------