Google Git
Sign in
gerrit / gerrit / 04975d9ef5030bc03e54c830e956fc021073cdfa / . / Documentation / rest-api-changes.txt
blob: da3018be2ac06eadc972007aa35ee6858d987f71 [file] [log] [blame]
:linkattrs:
= 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 input link:#change-input[ChangeInput] entity must be
provided in the request body. It is not allowed to create changes
under `refs/tags/` or Gerrit internal ref namespaces such as
`refs/changes/`, `refs/meta/external-ids/`, and `refs/users/`. The
request would fail with `400 Bad Request` in this case.
To create a change the calling user must be allowed to
link:access-control.html#category_push_review[upload to code review].
.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" : "NEW"
}
----
As response a link:#change-info[ChangeInfo] entity is returned that describes
the resulting change.
.Response
----
HTTP/1.1 201 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": "NEW",
"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. The `no-limit` parameter can be used remove the default
limit on queries and return all results (does not apply to anonymous requests).
This might not be supported by all index backends.
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",
"attention_set": [
{
"account": {
"name": "John Doe"
},
"last_update": "2012-07-17 07:19:27.766000000",
"reason": "reviewer or cc replied"
}
]
"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 number of changes matching the query exceeds either the internal
limit or a supplied `n` query parameter, 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.
Administrators can use the `skip-visibility` query parameter to skip visibility filtering.
This can be used to ensure that no changes are missed e.g. when querying for changes which
need to be reindexed. Without this parameter query results the user has no permission to read
are filtered out. REST requests with the skip-visibility option are rejected when the current
user doesn't have the ADMINISTRATE_SERVER capability.
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
****
[[query-options]]
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
as well as all reviewers by state, and reviewers that may
be removed by the current user.
--
[[detailed-labels]]
--
* `DETAILED_LABELS`: detailed label information, including numeric
values of all existing approvals, recognized label values, values
permitted to be set by any reviewer and the change owner, all
reviewers by state, and reviewers that may be removed by the
current user.
--
[[submit-requirements]]
--
* `SUBMIT_REQUIREMENTS`: detailed result of the evaluated submit requirements
for this change.
--
[[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.
--
[[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 and magic files,
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 and magic files,
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.
--
[[reviewer-updates]]
--
* `REVIEWER_UPDATES`: include updates to reviewers set as
link:#review-update-info[ReviewerUpdateInfo] entities.
--
[[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 all of the following are
true:
- the change is open
- the caller is authenticated
- the caller has commented on the change more recently than the last update
from the change owner, i.e. this change would show up in the results of
link:user-search.html#reviewedby[reviewedby:self].
--
[[skip_diffstat]]
--
* `SKIP_DIFFSTAT`: skip the 'insertions' and 'deletions' field in link:#change-info[ChangeInfo].
For large trees, their computation may be expensive.
--
[[submittable]]
--
* `SUBMITTABLE`: include the `submittable` field in link:#change-info[ChangeInfo],
which can be used to tell if the change is reviewed and ready for submit.
--
[[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.
--
[[commit-footers]]
--
* `COMMIT_FOOTERS`: include the full commit message with
Gerrit-specific commit footers in the
link:#revision-info[RevisionInfo].
--
[[push-certificates]]
--
* `PUSH_CERTIFICATES`: include push certificate information in the
link:#revision-info[RevisionInfo]. Ignored if signed push is not
link:config-gerrit.html#receive.enableSignedPush[enabled] on the
server.
--
[[tracking-ids]]
--
* `TRACKING_IDS`: include references to external tracking systems
as link:#tracking-id-info[TrackingIdInfo].
--
.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": {
"kind": "REWORK",
"_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,
"size_delta": -412,
"size": 7782
},
"gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeDetailCache.java": {
"lines_inserted": 1,
"size_delta": 23,
"size": 6762
},
"gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeScreen.java": {
"lines_inserted": 11,
"lines_deleted": 19,
"size_delta": -298,
"size": 47023
},
"gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeTable.java": {
"lines_inserted": 23,
"lines_deleted": 20,
"size_delta": 132,
"size": 17727
},
"gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarCache.java": {
"status": "D",
"lines_deleted": 139,
"size_delta": -5512,
"size": 13098
},
"gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarredChanges.java": {
"status": "A",
"lines_inserted": 204,
"size_delta": 8345,
"size": 8345
},
"gerrit-gwtui/src/main/java/com/google/gerrit/client/ui/Screen.java": {
"lines_deleted": 9,
"size_delta": -343,
"size": 5385
}
}
}
}
}
]
----
[[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",
"attention_set": [
{
"account": {
"name": "John Doe"
},
"last_update": "2013-02-21 11:16:36.775000000",
"reason": "reviewer or cc replied"
}
]
"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"
}
}
----
Historical state of the change can be retrieved by specifying the
`meta=SHA-1` parameter. This will use a historical NoteDb snapshot to
populate ChangeInfo. If the SHA-1 is not reachable as a NoteDb state,
status code 412 is returned.
[[get-meta-diff]]
=== Get Meta Diff
--
'GET /changes/link:#change-id[\{change-id\}]/meta_diff?old=SHA-1&meta=SHA-1'
--
Retrieves the difference between two historical states of a change
by specifying the `old=SHA-1` and the `meta=SHA-1` parameters.
If the `old` parameter is not provided, the parent of the `meta`
SHA-1 is used. If the `meta` parameter is not provided, the current
state of the change is used. If neither are provided, the
difference between the current state of the change and its previous
state is returned.
Additional fields can be obtained by adding `o` parameters, analogous
to link:#get-change[Get Change], and the same concerns for Get Change hold for
this endpoint too. Fields are described in link:#list-changes[Query Changes].
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/meta_diff?old=b083abc34eb6dbdb9e154ba092fc198000e997b4&meta=63b81f2bde703ae07787a940e8fdf9a1828605b1 HTTP/1.0
----
As a response, two link:#change-info[ChangeInfo] entities are returned
that describe information added and removed from the `old` change state, and
the two link:#change-info[ChangeInfo] entities that generated the diff are
returned. Only fields that differ between the change's two states are returned.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"added": {
"attention_set": [
{
"account": {
"name": "John Doe"
},
"last_update": "2013-02-21 11:16:36.775000000",
"reason": "reviewer or cc replied"
}
]
"updated": "2013-02-21 11:16:36.775000000",
"topic": "new-topic"
},
"removed": {
"updated": "2013-02-01 09:59:32.126000000",
"topic": "old-topic"
},
"old_change_info": {
"id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
"project": "myProject",
"branch": "master",
"attention_set": [],
"change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940",
"subject": "Implementing Feature X",
"status": "NEW",
"topic": "old-topic",
"created": "2013-02-01 09:59:32.126000000",
"updated": "2013-02-01 09:59:32.126000000",
"mergeable": true,
"insertions": 34,
"deletions": 101,
"_number": 3965,
"owner": {
"name": "John Doe"
}
},
"new_change_info": {
"id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
"project": "myProject",
"branch": "master",
"attention_set": [
{
"account": {
"name": "John Doe"
},
"last_update": "2013-02-21 11:16:36.775000000",
"reason": "reviewer or cc replied"
}
],
"change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940",
"subject": "Implementing Feature X",
"status": "NEW",
"topic": "new-topic",
"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"
}
},
}
----
If the provided SHA-1 for `meta` is not reachable as a NoteDb
state, the status code 412 is returned. If the SHA-1 for `old`
is not reachable, the difference between the change at state
`meta` and an empty change is returned.
[[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],
link:#reviewer-updates[reviewer updates], 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",
"attention_set": [
{
"account": {
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com",
"username": "jdoe"
},
"last_update": "2013-02-21 11:16:36.775000000",
"reason": "reviewer or cc replied"
}
]
"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"
}
],
"reviewers": {
"REVIEWER": [
{
"_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"
}
]
},
"reviewer_updates": [
{
"state": "REVIEWER",
"reviewer": {
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com",
"username": "jdoe"
},
"updated_by": {
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com",
"username": "jdoe"
},
"updated": "2016-07-21 20:12:39.000000000"
},
{
"state": "REMOVED",
"reviewer": {
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com",
"username": "jdoe"
},
"updated_by": {
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com",
"username": "jdoe"
},
"updated": "2016-07-21 20:12:33.000000000"
},
{
"state": "CC",
"reviewer": {
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com",
"username": "jdoe"
},
"updated_by": {
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com",
"username": "jdoe"
},
"updated": "2016-03-23 21:34:02.419000000",
},
],
"messages": [
{
"id": "YH-egE",
"author": {
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com",
"username": "jdoe"
},
"date": "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"
},
"date": "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
}
]
}
----
[[create-merge-patch-set-for-change]]
=== Create Merge Patch Set For Change
--
'POST /changes/link:#change-id[\{change-id\}]/merge'
--
Update an existing change by using a
link:#merge-patch-set-input[MergePatchSetInput] entity.
Gerrit will create a merge commit based on the information of
MergePatchSetInput and add a new patch set to the change corresponding
to the new merge commit.
.Request
----
POST /changes/test~master~Ic5466d107c5294414710935a8ef3b0180fb848dc/merge HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"subject": "Merge dev_branch into master",
"merge": {
"source": "refs/changes/34/1234/1"
}
}
----
As response a link:#change-info[ChangeInfo] entity with current revision is
returned that describes the resulting change.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "test~master~Ic5466d107c5294414710935a8ef3b0180fb848dc",
"project": "test",
"branch": "master",
"hashtags": [],
"change_id": "Ic5466d107c5294414710935a8ef3b0180fb848dc",
"subject": "Merge dev_branch into master",
"status": "NEW",
"created": "2016-09-23 18:08:53.238000000",
"updated": "2016-09-23 18:09:25.934000000",
"submit_type": "MERGE_IF_NECESSARY",
"mergeable": true,
"insertions": 5,
"deletions": 0,
"_number": 72,
"owner": {
"_account_id": 1000000
},
"current_revision": "27cc4558b5a3d3387dd11ee2df7a117e7e581822"
}
----
[[set-message]]
=== Set Commit Message
--
'PUT /changes/link:#change-id[\{change-id\}]/message'
--
Creates a new patch set with a new commit message.
The new commit message must be provided in the request body inside a
link:#commit-message-input[CommitMessageInput] entity. If a Change-Id
footer is specified, it must match the current Change-Id footer. If
the Change-Id footer is absent, the current Change-Id is added to the
message.
.Request
----
PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/message HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"message": "New Commit message \n\nChange-Id: I10394472cbd17dd12454f229e4f6de00b143a444\n"
}
----
.Notifications
An email will be sent using the "newpatchset" template.
[options="header",cols="1,1"]
|=============================
|WIP State |Default
|Ready for review|owner, reviewers, CCs, stars, NEW_PATCHSETS watchers
|Work in progress|owner
|=============================
[[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. Any leading or trailing whitespace
in the topic name will be removed.
.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.
.Request
----
DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic HTTP/1.0
----
.Response
----
HTTP/1.1 204 No Content
----
[[get-assignee]]
=== Get Assignee
--
'GET /changes/link:#change-id[\{change-id\}]/assignee'
--
Retrieves the account of the user assigned to a change.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/assignee HTTP/1.0
----
As a response an link:rest-api-accounts.html#account-info[AccountInfo] entity
describing the assigned account is returned.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com",
"username": "jdoe"
}
----
If the change has no assignee the response is "`204 No Content`".
[[get-past-assignees]]
=== Get Past Assignees
--
'GET /changes/link:#change-id[\{change-id\}]/past_assignees'
--
Returns a list of every user ever assigned to a change, in the order in which
they were first assigned.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/past_assignees HTTP/1.0
----
As a response a list of link:rest-api-accounts.html#account-info[AccountInfo]
entities is returned.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
[
{
"_account_id": 1000051,
"name": "Jane Doe",
"email": "jane.doe@example.com",
"username": "janed"
},
{
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com",
"username": "jdoe"
}
]
----
[[set-assignee]]
=== Set Assignee
--
'PUT /changes/link:#change-id[\{change-id\}]/assignee'
--
Sets the assignee of a change.
The new assignee must be provided in the request body inside a
link:#assignee-input[AssigneeInput] entity.
.Request
----
PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/assignee HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"assignee": "jdoe"
}
----
As a response an link:rest-api-accounts.html#account-info[AccountInfo] entity
describing the assigned account is returned.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com",
"username": "jdoe"
}
----
[[delete-assignee]]
=== Delete Assignee
--
'DELETE /changes/link:#change-id[\{change-id\}]/assignee'
--
Deletes the assignee of a change.
.Request
----
DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/assignee HTTP/1.0
----
As a response an link:rest-api-accounts.html#account-info[AccountInfo] entity
describing the account of the deleted assignee is returned.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com",
"username": "jdoe"
}
----
If the change had no assignee the response is "`204 No Content`".
[[get-pure-revert]]
=== Get Pure Revert
--
'GET /changes/link:#change-id[\{change-id\}]/pure_revert'
--
Check if the given change is a pure revert of the change it references in `revertOf`.
Optionally, the query parameter `o` can be passed in to specify a commit (SHA-1 in
40 digit hex representation) to check against. It takes precedence over `revertOf`.
If the change has no reference in `revertOf`, the parameter is mandatory.
As response a link:#pure-revert-info[PureRevertInfo] entity is returned.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/pure_revert?o=247bccf56ae47634650bcc08b8aa784c3580ccas HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"is_pure_revert" : false
}
----
[[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.
Abandoning a change also removes all users from the link:#attention-set[attention set].
.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
----
.Notifications
An email will be sent using the "abandon" template. The notify handling is ALL.
Notifications are suppressed on WIP changes that have never started review.
[options="header",cols="1,2"]
|=============================
|WIP State |notify=ALL
|Ready for review|owner, reviewers, CCs, stars, ABANDONED_CHANGES watchers
|Work in progress|not sent
|Reviewable WIP |owner, reviewers, CCs, stars, ABANDONED_CHANGES watchers
|=============================
[[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": {
"kind": "REWORK",
"_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.
----
[[move-change]]
=== Move Change
--
'POST /changes/link:#change-id[\{change-id\}]/move'
--
Move a change.
The destination branch must be provided in the request body inside a
link:#move-input[MoveInput] entity.
Only veto votes that are blocking the change from submission are moved to
the destination branch by default.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/move HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"destination_branch" : "release-branch"
}
----
As response a link:#change-info[ChangeInfo] entity is returned that
describes the moved change.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "myProject~release-branch~I8473b95934b5732ac55d26311a706c9c2bde9940",
"project": "myProject",
"branch": "release-branch",
"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"
}
}
----
Note that this endpoint will not update the change's parents, which is
different from the link:#cherry-pick[cherry-pick] endpoint.
If the change cannot be moved because the change state doesn't
allow moving 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
----
If the change cannot be moved because the user doesn't have
abandon permission on the change or upload permission on the destination,
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
move not permitted
----
[[revert-change]]
=== Revert Change
--
'POST /changes/link:#change-id[\{change-id\}]/revert'
--
Reverts a change.
The subject of the newly created change will be
'Revert "<subject-of-reverted-change>"'. If the subject of the change reverted is
above 63 characters, it will be cut down to 59 characters with "..." in the end.
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~I1ffe09a505e25f15ce1521bcfb222e51e62c2a14/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 user doesn't have revert permission on the change or upload permission on
the destination branch, the response is "`403 Forbidden`", and the error message is
contained in the response body.
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
----
[[revert-submission]]
=== Revert Submission
--
'POST /changes/link:#change-id[\{change-id\}]/revert_submission'
--
Creates open revert changes for all of the changes of a certain submission.
The subject of each revert change will be 'Revert "<subject-of-reverted-change"'.
If the subject is above 60 characters, the subject will be cut to 56 characters
with "..." in the end. However, whenever reverting the submission of a revert
submission, the subject will be shortened from
'Revert "Revert "<subject-of-reverted-change""' to
'Revert^2 "<subject-of-reverted-change"'. Also, for every future revert submission,
the only difference in the subject will be the number of the revert (instead of
Revert^2 the subject will change to Revert^3 and so on).
There are no guarantees about the subjects if the users change the default subjects.
Details for the revert can be specified in the request body inside a link:#revert-input[
RevertInput] The topic of all created revert changes will be
`revert-{submission_id}-{random_string_of_size_10}`.
The changes will not be rebased on onto the destination branch so the users may still
have to manually rebase them to resolve conflicts and make them submittable.
However, the changes that have the same project and branch will be rebased on top
of each other. E.g, the first revert change will have the original change as a
parent, and the second revert change will have the first revert change as a
parent.
There is one special case that involves merge commits; if a user has multiple
changes in the same project and branch, but not in the same change series, those
changes can still get submitted together if they have the same topic and
link:config-gerrit.html#change.submitWholeTopic[`change.submitWholeTopic`] in
gerrit.config is set to true. In the case, Gerrit may create merge commits on
submit (depending on the link:config-project-config.html#submit-type[submit types]
of the project).
The first parent for the reverts will be the most recent merge commit that was
created by Gerrit to merge the different change series into the target branch.
.Request
----
POST /changes/myProject~master~I1ffe09a505e25f15ce1521bcfb222e51e62c2a14/revert_submission HTTP/1.0
----
As response link:#revert-submission-info[RevertSubmissionInfo] entity
is returned. That entity describes the revert changes.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
"revert_changes":
[
{
"id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
"project": "myProject",
"branch": "master",
"topic": "revert--1571043962462-3640749-ABCEEZGHIJ",
"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"
}
},
{
"id": "anyProject~master~1eee2c9d8f352483781e772f35dc586a69ff5646",
"project": "anyProject",
"branch": "master",
"topic": "revert--1571043962462-3640749-ABCEEZGHIJ",
"change_id": "I1eee2c9d8f352483781e772f35dc586a69ff5646",
"subject": "Revert \"Implementing Feature Y\"",
"status": "NEW",
"created": "2013-02-04 09:59:33.126000000",
"updated": "2013-02-21 11:16:37.775000000",
"mergeable": true,
"insertions": 62,
"deletions": 11,
"_number": 3966,
"owner": {
"name": "Jane Doe"
}
}
]
----
If the user doesn't have revert permission on the change or upload permission on
the destination, the response is "`403 Forbidden`", and the error message is
contained in the response body.
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 submitting on behalf of another user.
Submitting a change also removes all users from the link:#attention-set[attention set].
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/submit HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"on_behalf_of": 1001439
}
----
As response a link:#change-info[ChangeInfo] entity is returned that
describes the submitted/merged change.
Submission may submit multiple changes, but we still only return one ChangeInfo
object. To query for all submitted changes, please use the submission_id that is
part of the response.
Changes that will also be submitted:
1. All changes of the same topic if
link:config-gerrit.html#change.submitWholeTopic[`change.submitWholeTopic`]
configuration is set to true.
2. All dependent changes.
3. The closure of the above (e.g if a dependent change has a topic, all changes
of *that* topic will also be submitted).
.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",
"submitted": "2013-02-21 11:16:36.615000000",
"_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
----
[[submitted-together]]
=== Changes Submitted Together
--
'GET /changes/link:#change-id[\{change-id\}]/submitted_together?o=NON_VISIBLE_CHANGES'
--
Computes list of all changes which are submitted when
link:#submit-change[Submit] is called for this change,
including the current change itself.
The list consists of:
* The given change.
* If link:config-gerrit.html#change.submitWholeTopic[`change.submitWholeTopic`]
is enabled, include all open changes with the same topic.
* For each change whose submit type is not CHERRY_PICK, include unmerged
ancestors targeting the same branch.
As a special case, the list is empty if this change would be
submitted by itself (without other changes).
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/submitted_together?o=NON_VISIBLE_CHANGES HTTP/1.0
Content-Type: application/json; charset=UTF-8
----
As a response a link:#submitted-together-info[SubmittedTogetherInfo]
entity is returned that describes what would happen if the change were
submitted. This response contains a list of changes and a count of
changes that are not visible to the caller that are part of the set of
changes to be merged.
The listed changes use the same format as in
link:#list-changes[Query Changes] with the
link:#labels[`LABELS`], link:#detailed-labels[`DETAILED_LABELS`],
link:#current-revision[`CURRENT_REVISION`],and
link:#submittable[`SUBMITTABLE`] options set.
Standard link:#query-options[formatting options] can be specified
with the `o` parameter, as well as the `submitted_together` specific
option `NON_VISIBLE_CHANGES`.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"changes": [
{
"id": "gerrit~master~I1ffe09a505e25f15ce1521bcfb222e51e62c2a14",
"project": "gerrit",
"branch": "master",
"hashtags": [],
"change_id": "I1ffe09a505e25f15ce1521bcfb222e51e62c2a14",
"subject": "ChangeMergeQueue: Rewrite such that it works on set of changes",
"status": "NEW",
"created": "2015-05-01 15:39:57.979000000",
"updated": "2015-05-20 19:25:21.592000000",
"mergeable": true,
"insertions": 303,
"deletions": 210,
"_number": 1779,
"owner": {
"_account_id": 1000000
},
"labels": {
"Code-Review": {
"approved": {
"_account_id": 1000000
},
"all": [
{
"value": 2,
"date": "2015-05-20 19:25:21.592000000",
"_account_id": 1000000
}
],
"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"
},
"default_value": 0
},
"Verified": {
"approved": {
"_account_id": 1000000
},
"all": [
{
"value": 1,
"date": "2015-05-20 19:25:21.592000000",
"_account_id": 1000000
}
],
"values": {
"-1": "Fails",
" 0": "No score",
"+1": "Verified"
},
"default_value": 0
}
},
"permitted_labels": {
"Code-Review": [
"-2",
"-1",
" 0",
"+1",
"+2"
],
"Verified": [
"-1",
" 0",
"+1"
]
},
"removable_reviewers": [
{
"_account_id": 1000000
}
],
"reviewers": {
"REVIEWER": [
{
"_account_id": 1000000
}
]
},
"current_revision": "9adb9f4c7b40eeee0646e235de818d09164d7379",
"revisions": {
"9adb9f4c7b40eeee0646e235de818d09164d7379": {
"kind": "REWORK",
"_number": 1,
"created": "2015-05-01 15:39:57.979000000",
"uploader": {
"_account_id": 1000000
},
"ref": "refs/changes/79/1779/1",
"fetch": {},
}
}
},
{
"id": "gerrit~master~I7fe807e63792b3d26776fd1422e5e790a5697e22",
"project": "gerrit",
"branch": "master",
"hashtags": [],
"change_id": "I7fe807e63792b3d26776fd1422e5e790a5697e22",
"subject": "AbstractSubmoduleSubscription: Split up createSubscription",
"status": "NEW",
"created": "2015-05-01 15:39:57.979000000",
"updated": "2015-05-20 19:25:21.546000000",
"mergeable": true,
"insertions": 15,
"deletions": 6,
"_number": 1780,
"owner": {
"_account_id": 1000000
},
"labels": {
"Code-Review": {
"approved": {
"_account_id": 1000000
},
"all": [
{
"value": 2,
"date": "2015-05-20 19:25:21.546000000",
"_account_id": 1000000
}
],
"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"
},
"default_value": 0
},
"Verified": {
"approved": {
"_account_id": 1000000
},
"all": [
{
"value": 1,
"date": "2015-05-20 19:25:21.546000000",
"_account_id": 1000000
}
],
"values": {
"-1": "Fails",
" 0": "No score",
"+1": "Verified"
},
"default_value": 0
}
},
"permitted_labels": {
"Code-Review": [
"-2",
"-1",
" 0",
"+1",
"+2"
],
"Verified": [
"-1",
" 0",
"+1"
]
},
"removable_reviewers": [
{
"_account_id": 1000000
}
],
"reviewers": {
"REVIEWER": [
{
"_account_id": 1000000
}
]
},
"current_revision": "1bd7c12a38854a2c6de426feec28800623f492c4",
"revisions": {
"1bd7c12a38854a2c6de426feec28800623f492c4": {
"kind": "REWORK",
"_number": 1,
"created": "2015-05-01 15:39:57.979000000",
"uploader": {
"_account_id": 1000000
},
"ref": "refs/changes/80/1780/1",
"fetch": {},
}
}
}
],
"non_visible_changes": 0
}
----
If the `o=NON_VISIBLE_CHANGES` query parameter is not passed, then
instead of a link:#submitted-together-info[SubmittedTogetherInfo]
entity, the response is a list of changes, or a 403 response with a
message if the set of changes to be submitted with this change
includes changes the caller cannot read.
[[delete-change]]
=== Delete Change
--
'DELETE /changes/link:#change-id[\{change-id\}]'
--
Deletes a change.
New or abandoned changes can be deleted by their owner if the user is granted
the link:access-control.html#category_delete_own_changes[Delete Own Changes] permission,
otherwise only by administrators.
.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
----
[[list-change-comments]]
=== List Change Comments
--
'GET /changes/link:#change-id[\{change-id\}]/comments'
--
Lists the published comments of all revisions of the change.
Returns a map of file paths to lists of link:#comment-info[CommentInfo]
entries. The entries in the map are sorted by file path, and the
comments for each path are sorted by patch set number. Each comment has
the `patch_set` and `author` fields set.
If the `enable-context` request parameter is set to true, the comment entries
will contain a list of link:#context-line[ContextLine] containing the lines of
the source file where the comment was written.
The `context-padding` request parameter can be used to specify an extra number
of context lines to be added before and after the comment range. This parameter
only works if `enable-context` is set to true.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/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": [
{
"patch_set": 1,
"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"
}
},
{
"patch_set": 2,
"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"
}
}
]
}
----
[[list-change-robot-comments]]
=== List Change Robot Comments
--
'GET /changes/link:#change-id[\{change-id\}]/robotcomments'
--
Lists the robot comments of all revisions of the change.
Return a map that maps the file path to a list of
link:#robot-comment-info[RobotCommentInfo] entries. The entries in the
map are sorted by file path.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/robotcomments/ 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": "unused import",
"updated": "2016-02-26 15:40:43.986000000",
"author": {
"_account_id": 1000110,
"name": "Code Analyzer",
"email": "code.analyzer@example.com"
},
"robot_id": "importChecker",
"robot_run_id": "76b1375aa8626ea7149792831fe2ed85e80d9e04"
},
{
"id": "TveXwFiA",
"line": 49,
"message": "wrong indention",
"updated": "2016-02-26 15:40:45.328000000",
"author": {
"_account_id": 1000110,
"name": "Code Analyzer",
"email": "code.analyzer@example.com"
},
"robot_id": "styleChecker",
"robot_run_id": "5c606c425dd45184484f9d0a2ffd725a7607839b"
}
]
}
----
[[list-change-drafts]]
=== List Change Drafts
--
'GET /changes/link:#change-id[\{change-id\}]/drafts'
--
Lists the draft comments of all revisions of the change that belong to
the calling user.
Returns a map of file paths to lists of link:#comment-info[CommentInfo]
entries. The entries in the map are sorted by file path, and the
comments for each path are sorted by patch set number. Each comment has
the `patch_set` field set, and no `author`.
The `enable-context` and `context-padding` request parameters can be used to
request comment context. See link:#list-change-comments[List Change Comments]
for more details.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/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": [
{
"patch_set": 1,
"id": "TvcXrmjM",
"line": 23,
"message": "[nit] trailing whitespace",
"updated": "2013-02-26 15:40:43.986000000"
},
{
"patch_set": 2,
"id": "TveXwFiA",
"line": 49,
"in_reply_to": "TfYX-Iuo",
"message": "Done",
"updated": "2013-02-26 15:40:45.328000000"
}
]
}
----
[[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.
Some fixes have options controlling their behavior, which can be set in the
link:#fix-input[FixInput] entity body.
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",
"submitted": "2013-02-21 11:16:36.615000000",
"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"
}
]
}
----
[[set-work-in-pogress]]
=== Set Work-In-Progress
--
'POST /changes/link:#change-id[\{change-id\}]/wip'
--
Marks the change as not ready for review yet. Changes may only be marked not
ready by the owner, project owners or site administrators.
The request body does not need to include a
link:#work-in-progress-input[WorkInProgressInput] entity if no review comment
is added. Actions that create a new patch set in a WIP change default to
notifying *OWNER* instead of *ALL*.
Marking a change work in progress also removes all users from the
link:#attention-set[attention set].
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/wip HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"message": "Refactoring needs to be done before we can proceed here."
}
----
.Response
----
HTTP/1.1 200 OK
----
[[set-ready-for-review]]
=== Set Ready-For-Review
--
'POST /changes/link:#change-id[\{change-id\}]/ready'
--
Marks the change as ready for review (set WIP property to false). Changes may
only be marked ready by the owner, project owners or site administrators.
Activates notifications of reviewer. The request body does not need
to include a link:#work-in-progress-input[WorkInProgressInput] entity
if no review comment is added.
Marking a change ready for review also adds all of the reviewers of the change
to the link:#attention-set[attention set].
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/ready HTTP/1.0
Content-Type: application/json;charset=UTF-8
{
"message": "Refactoring is done."
}
----
.Response
----
HTTP/1.1 200 OK
----
[[mark-private]]
=== Mark Private
--
'POST /changes/link:#change-id[\{change-id\}]/private'
--
Marks the change to be private. Only open changes can be marked private.
Changes may only be marked private by the owner or site administrators.
A message can be specified in the request body inside a
link:#private-input[PrivateInput] entity.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/private HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"message": "After this security fix has been released we can make it public now."
}
----
.Response
----
HTTP/1.1 201 Created
----
If the change was already private the response is "`200 OK`".
[[unmark-private]]
=== Unmark Private
--
'DELETE /changes/link:#change-id[\{change-id\}]/private'
--
Marks the change to be non-private. Note users can only unmark own private
changes.
.Request
----
DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/private HTTP/1.0
----
.Response
----
HTTP/1.1 204 No Content
----
If the change was already not private, the response is "`409 Conflict`".
A message can be specified in the request body inside a
link:#private-input[PrivateInput] entity. Historically, this method allowed
a body in the DELETE, but that behavior is
link:https://www.gerritcodereview.com/releases/2.16.md[deprecated,role=external,window=_blank].
In this case, use a POST request instead:
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/private.delete HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"message": "This is a security fix that must not be public."
}
----
[[ignore]]
=== Ignore
--
'PUT /changes/link:#change-id[\{change-id\}]/ignore'
--
Marks a change as ignored. The change will not be shown in the incoming
reviews dashboard, and email notifications will be suppressed. Ignoring
a change does not cause the change's "updated" timestamp to be modified,
and the owner is not notified.
.Request
----
PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/ignore HTTP/1.0
----
[[unignore]]
=== Unignore
--
'PUT /changes/link:#change-id[\{change-id\}]/unignore'
--
Un-marks a change as ignored.
.Request
----
PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/unignore HTTP/1.0
----
[[get-hashtags]]
=== Get Hashtags
--
'GET /changes/link:#change-id[\{change-id\}]/hashtags'
--
Gets the hashtags associated with a change.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/hashtags HTTP/1.0
----
As response the change's hashtags are returned as a list of strings.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
[
"hashtag1",
"hashtag2"
]
----
[[set-hashtags]]
=== Set Hashtags
--
'POST /changes/link:#change-id[\{change-id\}]/hashtags'
--
Adds and/or removes hashtags from a change.
The hashtags to add or remove must be provided in the request body inside a
link:#hashtags-input[HashtagsInput] entity.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/hashtags HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"add" : [
"hashtag3"
],
"remove" : [
"hashtag2"
]
}
----
As response the change's hashtags are returned as a list of strings.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
[
"hashtag1",
"hashtag3"
]
----
[[list-change-messages]]
=== List Change Messages
--
'GET /changes/link:#change-id[\{change-id\}]/messages'
--
Lists all the messages of a change including link:#detailed-accounts[detailed account information].
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/messages
----
As response a list of link:#change-message-info[ChangeMessageInfo] entities is returned.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
[
{
"id": "YH-egE",
"author": {
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com",
"username": "jdoe"
},
"date": "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"
},
"date": "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-change-message]]
=== Get Change Message
Retrieves a change message including link:#detailed-accounts[detailed account information].
--
'GET /changes/link:#change-id[\{change-id\}]/messages/link:#change-message-id[\{change-message-id\}]'
--
As response a link:#change-message-info[ChangeMessageInfo] entity is returned.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "aaee04dcb46bafc8be24d8aa70b3b1beb7df5780",
"author": {
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com",
"username": "jdoe"
},
"date": "2013-03-23 21:34:02.419000000",
"message": "a change message",
"_revision_number": 1
}
----
[[delete-change-message]]
=== Delete Change Message
--
'DELETE /changes/link:#change-id[\{change-id\}]/messages/link:#change-message-id[\{change-message-id\}]' +
'POST /changes/link:#change-id[\{change-id\}]/messages/link:#change-message-id[\{change-message-id\}]/delete'
--
Deletes a change message by replacing the change message with a new message,
which contains the name of the user who deleted the change message and the
reason why it was deleted. The reason can be provided in the request body as a
link:#delete-change-message-input[DeleteChangeMessageInput] entity.
Note that only users with the
link:access-control.html#capability_administrateServer[Administrate Server]
global capability are permitted to delete a change message.
To delete a change message, send a DELETE request:
.Request
----
DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/messages/aaee04dcb46bafc8be24d8aa70b3b1beb7df5780 HTTP/1.0
----
To provide a reason for the deletion, use a POST request:
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/messages/aaee04dcb46bafc8be24d8aa70b3b1beb7df5780/delete HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"reason": "spam"
}
----
As response a link:#change-message-info[ChangeMessageInfo] entity is returned that
describes the updated change message.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "aaee04dcb46bafc8be24d8aa70b3b1beb7df5780",
"author": {
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com",
"username": "jdoe"
},
"date": "2013-03-23 21:34:02.419000000",
"message": "Change message removed by: Administrator\nReason: spam",
"_revision_number": 1
}
----
[[check-submit-requirement]]
=== Check Submit Requirement
--
'POST /changes/link:#change-id[\{change-id\}]/check.submit_requirement'
--
Tests a submit requirement and returns the result as a
link:#submit-requirement-result-info[SubmitRequirementResultInfo]. The request
body must contain a link:#submit-requirement-input[SubmitRequirementInput].
Note that this endpoint does not modify the change resource.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/check.submit_requirement HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"name": "Code-Review",
"submittability_expression": "label:Code-Review=+2"
}
----
As response a link:#submit-requirement-result-info[SubmitRequirementResultInfo]
entity is returned that describes the submit requirement result.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"name": "Code-Review",
"status": "SATISFIED",
"submittability_expression_result": {
"expression": "label:Code-Review=+2",
"fulfilled": true,
"passingAtoms": [
"label:Code-Review=+2"
]
},
"is_legacy": false
}
----
[[edit-endpoints]]
== Change Edit Endpoints
[[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 ..."
},
"base_patch_set_number": 1,
"base_revision": "c35558e0925e6985c91f3a16921537d5e572b7a3",
"ref": "refs/users/01/1000001/edit-76482/1"
}
----
[[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
----
To upload a file as binary data in the request body:
.Request
----
PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit/foo HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"binary_content": "data:text/plain;base64,SGVsbG8sIFdvcmxkIQ=="
}
----
Note that it must be base-64 encoded data uri.
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
----
When the change edit is a no-op, for example when providing the same file
content that the file already has, '409 no changes were made' is returned.
.Response
----
HTTP/1.1 409 no changes were made
----
[[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.
If the `base` parameter is set to true, the returned content is from the
revision that the edit is based on.
.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.
If the `base` parameter is set to true, the returned message is from the
revision that the edit is based on.
.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.
Options can be provided in the request body as a
link:#publish-change-edit-input[PublishChangeEditInput] entity.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit:publish HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"notify": "NONE"
}
----
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 already
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.
This REST endpoint only suggests accounts that
* are active
* can see the change
* are visible to the calling user
* are not already reviewer on the change
* don't own the change
* are not service users (unless
link:config.html#suggest.skipServiceUsers[skipServiceUsers] is set to `false`)
Groups can be excluded from the results by specifying the 'exclude-groups'
request parameter:
--
'GET /changes/link:#change-id[\{change-id\}]/suggest_reviewers?q=J&n=5&exclude-groups'
--
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"
},
"count": 1
},
{
"group": {
"id": "4fd581c0657268f2bdcc26699fbf9ddb76e3a279",
"name": "Joiner"
},
"count": 5
}
]
----
To suggest CCs `reviewer-state=CC` can be specified as additional URL
parameter. This includes existing reviewers in the result, but excludes
existing CCs.
--
'GET /changes/link:#change-id[\{change-id\}]/suggest_reviewers?q=J&reviewer-state=CC'
--
[[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.
Users can be moved from reviewer to CC and vice versa. This means if a
user is added as CC that is already a reviewer on the change, the
reviewer state of that user is updated to CC. If a user that is already
a CC on the change is added as reviewer, the reviewer state of that
user is updated to reviewer.
Adding a new reviewer also adds that reviewer to the attention set, unless
the change is work in progress.
Also, moving a reviewer to CC removes that user from the attention set.
.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:#reviewer-result[ReviewerResult] 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
)]}'
{
"input": "john.doe@example.com",
"reviewers": [
{
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com"
"approvals": {
"Verified": " 0",
"Code-Review": " 0"
},
}
]
}
----
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.
If a group is added as CC and members of this group are already
reviewers on the change, these members stay reviewers on the change
(they are not downgraded to CC). However if a group is added as
reviewer, all group members become reviewer of the change, even if they
have been added as CC before.
.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
)]}'
{
"input": "MyProjectVerifiers",
"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
{
"input": "MyProjectVerifiers",
"confirmed": true
}
----
If link:config-project-config.html#reviewer.enableByEmail[reviewer.enableByEmail] is set
for the project, reviewers and CCs are not required to have a Gerrit account. If you POST
an email address of a reviewer or CC then, they will be added to the change even if they
don't have a Gerrit account.
If this option is disabled, the request would fail with `400 Bad Request` if the email
address can't be resolved to an active Gerrit account.
Note that the name is optional so both "un.registered@reviewer.com" and
"John Doe <un.registered@reviewer.com>" are valid inputs.
Reviewers without Gerrit accounts can only be added on changes visible to anonymous users.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"reviewer": "John Doe <un.registered@reviewer.com>"
}
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"input": "John Doe <un.registered@reviewer.com>"
}
----
.Notifications
An email will be sent using the "newchange" template.
[options="header",cols="1,1,1"]
|=============================
|WIP State |Default|notify=ALL
|Ready for review|owner, reviewers, CCs|owner, reviewers, CCs
|Work in progress|not sent|owner, reviewers, CCs
|=============================
[[delete-reviewer]]
=== Delete Reviewer
--
'DELETE /changes/link:#change-id[\{change-id\}]/reviewers/link:rest-api-accounts.html#account-id[\{account-id\}]' +
'POST /changes/link:#change-id[\{change-id\}]/reviewers/link:rest-api-accounts.html#account-id[\{account-id\}]/delete'
--
Deletes a reviewer from a change.
Deleting a reviewer also removes that user from the attention set.
.Request
----
DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe HTTP/1.0
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe/delete HTTP/1.0
----
Options can be provided in the request body as a
link:#delete-reviewer-input[DeleteReviewerInput] entity.
Historically, this method allowed a body in the DELETE, but that behavior is
link:https://www.gerritcodereview.com/releases/2.16.md[deprecated,role=external,window=_blank].
In this case, use a POST request instead:
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe/delete HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"notify": "NONE"
}
----
.Response
----
HTTP/1.1 204 No Content
----
.Notifications
An email will be sent using the "deleteReviewer" template. If deleting the
reviewer resulted in one or more approvals being removed, then the deleted
reviewer will also receive a notification (unless notify=NONE).
[options="header",cols="1,5"]
|=============================
|WIP State |Default Recipients
|Ready for review|notify=ALL: deleted reviewer (if voted), owner, reviewers, CCs, stars, ALL_COMMENTS watchers
|Work in progress|notify=NONE: deleted reviewer (if voted)
|=============================
[[list-votes]]
=== List Votes
--
'GET /changes/link:#change-id[\{change-id\}]/reviewers/link:rest-api-accounts.html#account-id[\{account-id\}]/votes/'
--
Lists the votes for a specific reviewer of the change.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe/votes/ HTTP/1.0
----
As result a map is returned that maps the label name to the label value.
The entries in the map are sorted by label name.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
{
"Code-Review": -1,
"Verified": 1
"Work-In-Progress": 1,
}
----
[[delete-vote]]
=== Delete Vote
--
'DELETE /changes/link:#change-id[\{change-id\}]/reviewers/link:rest-api-accounts.html#account-id[\{account-id\}]/votes/link:#label-id[\{label-id\}]' +
'POST /changes/link:#change-id[\{change-id\}]/reviewers/link:rest-api-accounts.html#account-id[\{account-id\}]/votes/link:#label-id[\{label-id\}]/delete'
--
Deletes a single vote from a change. Note, that even when the last vote of
a reviewer is removed the reviewer itself is still listed on the change.
If another user removed a user's vote, the user with the deleted vote will be
added to the attention set.
.Request
----
DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe/votes/Code-Review HTTP/1.0
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe/votes/Code-Review/delete HTTP/1.0
----
Options can be provided in the request body as a
link:#delete-vote-input[DeleteVoteInput] entity.
Historically, this method allowed a body in the DELETE, but that behavior is
link:https://www.gerritcodereview.com/releases/2.16.md[deprecated,role=external,window=_blank].
In this case, use a POST request instead:
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe/votes/Code-Review/delete HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"notify": "NONE"
}
----
.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
)]}'
{
"commit": "674ac754f91e64a0efb8087e59a176484bd534d1",
"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-description]]
=== Get Description
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/description'
--
Retrieves the description of a patch set.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/description HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
"Added Documentation"
----
If the patch set does not have a description an empty string is returned.
[[set-description]]
=== Set Description
--
'PUT /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/description'
--
Sets the description of a patch set.
The new description must be provided in the request body inside a
link:#description-input[DescriptionInput] entity.
.Request
----
PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/description HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"description": "Added Documentation"
}
----
As response the new description is returned.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
"Added Documentation"
----
[[get-merge-list]]
=== Get Merge List
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/mergelist'
--
Returns the list of commits that are being integrated into a target
branch by a merge commit. By default the first parent is assumed to be
uninteresting. By using the `parent` option another parent can be set
as uninteresting (parents are 1-based).
The list of commits is returned as a list of
link:#commit-info[CommitInfo] entities. Web links are only included if
the `links` option was set.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/7e30d802b890ec8d0be45b1cc2a8ef092bcfc858/mergelist HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
[
{
"commit": "674ac754f91e64a0efb8087e59a176484bd534d1",
"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 ..."
}
]
----
[[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 REST endpoint names
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"
}
],
"reviewers": {
"REVIEWER": [
{
"_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": {
"kind": "REWORK",
"_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": [
{
"project": "gerrit",
"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
"status": "NEW"
},
{
"project": "gerrit",
"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
"status": "NEW"
}
]
}
----
[[set-review]]
=== Set Review
--
'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/review'
--
Sets a review on a revision, optionally also publishing draft comments, setting
labels, adding reviewers or CCs, and modifying the work in progress property.
The review must be provided in the request body as a
link:#review-input[ReviewInput] entity.
If the labels are set, the user sending the request will automatically be
added as a reviewer, otherwise (if they only commented) they are added to
the CC list.
Some updates to the attention set occur here. If more than one update should
occur, only the first update in the order of the below documentation occurs:
If a user is part of remove_from_attention_set, the user will be explicitly
removed from the attention set.
If a user is part of add_to_attention_set, the user will be explicitly
added to the attention set.
If the boolean ignore_default_attention_set_rules is set to true, all
other rules below will be ignored:
The user who created the review is removed from the attention set.
If the change is ready for review, the following also apply:
When the uploader replies, the owner is added to the attention set.
When the owner or uploader replies, all the reviewers are added to
the attention set.
When neither the owner nor the uploader replies, add the owner and the
uploader to the attention set.
Then, new reviewers are added to the attention set, and removed reviewers
(by becoming CC) are removed from the attention set.
A review cannot be set on a change edit. Trying to post a review for a
change edit fails with `409 Conflict`.
Here is an example of using this method to set labels:
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/review HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"tag": "jenkins",
"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-result[ReviewResult] entity is returned that
describes the applied labels and any added reviewers (e.g. yourself,
if you set a label but weren't previously a reviewer on this CL).
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"labels": {
"Code-Review": -1
}
}
----
It is also possible to add one or more reviewers or CCs
to a change simultaneously with a review:
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/review HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"message": "I don't have context here. Jane and maybe John and the project leads should take a look.",
"reviewers": [
{
"reviewer": "jane.roe@example.com"
},
{
"reviewer": "john.doe@example.com",
"state": "CC"
}
{
"reviewer": "MyProjectVerifiers",
}
]
}
----
Each element of the `reviewers` list is an instance of
link:#reviewer-input[ReviewerInput]. The corresponding result of
adding each reviewer will be returned in a map of inputs to
link:#reviewer-result[ReviewerResult]s.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"reviewers": {
"jane.roe@example.com": {
"input": "jane.roe@example.com",
"reviewers": [
{
"_account_id": 1000097,
"name": "Jane Roe",
"email": "jane.roe@example.com"
"approvals": {
"Verified": " 0",
"Code-Review": " 0"
},
},
]
},
"john.doe@example.com": {
"input": "john.doe@example.com",
"ccs": [
{
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com"
"approvals": {
"Verified": " 0",
"Code-Review": " 0"
},
}
]
},
"MyProjectVerifiers": {
"input": "MyProjectVerifiers",
"reviewers": [
{
"_account_id": 1000098,
"name": "Alice Ansel",
"email": "alice.ansel@example.com"
"approvals": {
"Verified": " 0",
"Code-Review": " 0"
},
},
{
"_account_id": 1000099,
"name": "Bob Bollard",
"email": "bob.bollard@example.com"
"approvals": {
"Verified": " 0",
"Code-Review": " 0"
},
},
]
}
}
}
----
If there are any errors returned for reviewers, the entire review request will
be rejected with `400 Bad Request`. None of the entries will have the
`reviewers` or `ccs` field set, and those which specifically failed will have
the `errors` field set containing details of why they failed.
.Error Response
----
HTTP/1.1 400 Bad Request
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"reviewers": {
"jane.roe@example.com": {
"input": "jane.roe@example.com",
"error": "Account of jane.roe@example.com is inactive."
},
"john.doe@example.com": {
"input": "john.doe@example.com"
},
"MyProjectVerifiers": {
"input": "MyProjectVerifiers",
"error": "The group My Group has 15 members. Do you want to add them all as reviewers?",
"confirm": true
}
}
}
----
[[set-review-notifications]]
.Notifications
An email will be sent using the "comment" template.
If the top-level notify property is null or not set, then notification behavior
depends on whether the change is WIP, whether it has started review, and whether
the tag property is null.
NOTE: If adding reviewers, the notify property of each ReviewerInput is *ignored*.
Use the notify property of the top-level link:#review-input[ReviewInput] instead.
For the