Google Git
Sign in
gerrit / gerrit / master / . / Documentation / rest-api-changes.txt
blob: 0305aaafb2af3c4bae4263264180c858d7bcd4ad [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"
},
"current_revision_number": 2
}
----
[[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": {
"1000096": {
"account": {
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com"
},
"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"
},
"current_revision_number": 2
},
{
"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"
},
"current_revision_number": 2,
"_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.
The `allow-incomplete-results` query parameter can be used. This is a boolean
parameter that can optionally be set to true. If set, the server can tolerate
handling faulty records when parsed from the change index, for example if a
field contained a value of a wrong format. For faulty records, the server
will return a canonical empty record where only the fields {project, branch,
change_id, _number, owner} are set and the subject will be set to
"\*\**ERROR***". All other fields will be empty.
Note that the handling of this parameter is up to the index implementation.
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": {}
},
"current_revision_number": 2
}
],
[],
[]
]
----
.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`: Includes the `labels` field which contains all information about
labels and approvers that have granted (or rejected) that label. Does not
include the `permitted_voting_range` attribute with the list of
link:#approval-info[ApprovalInfo] of the `all` attribute.
--
[[detailed-labels]]
--
* `DETAILED_LABELS`: Includes the `labels` field which contains all information
about labels and approvers that have granted (or rejected) that label, including
the `permitted_voting_range` attribute with the list of
link:#approval-info[ApprovalInfo] of the `all` attribute.
--
[[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].
--
[[custom-keyed-values]]
--
* `CUSTOM_KEYED_VALUES`: include the custom key-value map
--
[[star]]
--
* `STAR`: include the `starred` field in
link:#change-info[ChangeInfo], which indicates if the change is starred
by the current user or not.
--
[[parents-data]]
--
* `PARENTS`: include the `parents_data` field in
link:#revision-info[RevisionInfo], which provides information of whether the
parent commit of this revision, e.g. if it's merged in the target branch
and whether it points to a patch-set of another change.
--
.Request
----
GET /changes/?q=97&o=CURRENT_REVISION&o=CURRENT_COMMIT&o=CURRENT_FILES&o=DOWNLOAD_COMMANDS HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
[
{
"id": "gerrit~master~I7ea46d2e2ee5c64c0d807677859cfb7d90b8966a",
"project": "gerrit",
"branch": "master",
"change_id": "I7ea46d2e2ee5c64c0d807677859cfb7d90b8966a",
"subject": "Use an EventBus to manage star icons",
"status": "NEW",
"created": "2012-04-25 00:52:25.580000000",
"updated": "2012-04-25 00:52:25.586000000",
"mergeable": true,
"insertions": 16,
"deletions": 7,
"_number": 97,
"owner": {
"name": "Shawn Pearce"
},
"current_revision_number": 1,
"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": {
"1000096": {
"account": {
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com"
},
"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"
},
"current_revision_number": 2
}
----
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": {
"1000096": {
"account": {
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com"
},
"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"
},
"current_revision_number": 2
},
"new_change_info": {
"id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
"project": "myProject",
"branch": "master",
"attention_set": {
"1000096": {
"account": {
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com"
},
"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"
},
"current_revision_number": 2
},
}
----
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": {
"1000096": {
"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 submitted",
"-1": "I would prefer this is not submitted 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_labels": {
"Code-Review": {
"-1": [
{
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com",
"username": "jdoe"
}
],
"+1": [
{
"_account_id": 1000097,
"name": "Jane Roe",
"email": "jane.roe@example.com",
"username": "jroe"
}
]
}
},
"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
}
],
"current_revision_number": 2
}
----
[[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.
If one of the secondary emails associated with the user performing the operation was used as the
committer email in the current patch set, the same email will be used as the committer email in the
new patch set; otherwise, the user's preferred email will be used.
.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_number": 1,
"current_revision": "27cc4558b5a3d3387dd11ee2df7a117e7e581822"
}
----
[[get-message]]
=== Get Commit Message
--
'GET /changes/link:#change-id[\{change-id\}]/message'
--
Returns the commit message of the change (from the current patch set).
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/message HTTP/1.0
----
The commit message is returned as a link:#commit-message-info[
CommitMessageInfo] entity.
Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"subject": "Add feature X",
"full_message": "Add Feature X\n\nFeature X helps with foo.\n\nBug: 123\nChange-Id: I10394472cbd17dd12454f229e4f6de00b143a444\n",
"footers": {
"Bug": "123",
"Change-Id": "I10394472cbd17dd12454f229e4f6de00b143a444"
}
}
----
[[set-message]]
=== Set Commit Message
--
'PUT /changes/link:#change-id[\{change-id\}]/message'
--
Creates a new patch set with a new commit message.
If one of the secondary emails associated with the user performing the operation was used as the
committer email in the current patch set, the same email will be used as the committer email in the
new patch set; otherwise, the user's preferred email will be used.
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-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:user-attention-set.html[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"
},
"current_revision_number": 2
}
----
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"
},
"current_revision_number": 2
}
----
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.
For merge commits always the first parent is rebased. This means the new base becomes the first
parent of the rebased merge commit while the second parent stays intact.
If one of the secondary emails associated with the user performing the operation was used as the
committer email in the current patch set, the same email will be used as the committer email in the
new patch set; otherwise, the user's preferred email will be used.
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_number": 2,
"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.
----
Rebasing a change is allowed for the change owner, users with the
link:access-control.html#category_rebase[Rebase] permission and users
with the link:access-control.html#category_submit[Submit] permission.
In addition, the rebaser or the original uploader, if rebasing is done
on behalf of the uploader (see `rebase_on_behalf_of_uploader` option in
link:#rebase-input[RebaseInput]), needs to have all permissions that
are required to create the new patch set:
* the link:access-control.html#category_push[Push] permission
* the link:access-control.html#category_add_patch_set[Add Patch Set]
permission (only if the user is not the change owner)
* the link:access-control.html#category_forge_author[Forge Author]
permission (only if the commit author is forged)
* the link:access-control.html#category_forge_server[Forge Server]
permission (only if the commit author is the server identity)
The same permissions were required for the upload of the original patch
set. This means if the rebase is done on behalf of the uploader these
permission checks should just pass, unless the uploader lost
permissions after the upload of the original patch set. In this case
rebasing on behalf of the uploader is not possible and a normal rebase
(on behalf of the rebaser) must be done, which means that the rebaser
becomes the uploader and takes over the change. If self approvals are
disallowed, this means that the rebaser can no longer approve the
change (as approvals of the uploader are ignored).
[[rebase-chain]]
=== Rebase Chain
--
'POST /changes/link:#change-id[\{change-id\}]/rebase:chain'
--
Rebases an ancestry chain of changes.
If one of the secondary emails associated with the user performing the operation was used as the
committer email in the current patch set, the same email will be used as the committer email in the
new patch set; otherwise, the user's preferred email will be used.
The operated change is treated as the chain tip. All unsubmitted ancestors are rebased.
Requires a linear ancestry relation (single parenting throughout the chain).
Optionally, the parent revision (of the oldest ancestor to be rebased) can be changed to another
change, revision or branch through the link:#rebase-input[RebaseInput] entity.
Providing a `committer_email` through the link:#rebase-input[RebaseInput] entity is not supported
when rebasing a chain.
If the chain is outdated, i.e., there's a change that depends on an old revision of its parent, the
result is the same as individually rebasing all outdated changes on top of their parent's latest
revision before running the rebase chain action.
.Request
----
POST /changes/myProject~master~I08a021fb07b83fe845140a2c11508b3bdd93b48f/rebase:chain HTTP/1.0
Content-Type: application/json;charset=UTF-8
{
"base" : "1234",
}
----
As response a link:#rebase-chain-info[RebaseChainInfo] entity is returned that
describes the rebased changes. Information about the current patch sets
are included.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"rebased_changes": [
{
"id": "myProject~master~I0e534de9d7f0d6f35b71f7d726acf835b2110c66",
"project": "myProject",
"branch": "master",
"hashtags": [
],
"change_id": "I0e534de9d7f0d6f35b71f7d726acf835b2110c66",
"subject": "456",
"status": "NEW",
"created": "2022-11-21 20: 51: 31.000000000",
"updated": "2022-11-21 20: 56: 49.000000000",
"submit_type": "MERGE_IF_NECESSARY",
"insertions": 0,
"deletions": 0,
"total_comment_count": 0,
"unresolved_comment_count": 0,
"has_review_started": true,
"meta_rev_id": "a2a6692213f546e1045ecf4647439fac8d6d8faa",
"_number": 21,
"owner": {
"_account_id": 1000000
},
"current_revision_number": 2,
"current_revision": "c3b2ba222d42a56e05c90f88d4509a124620517d",
"revisions": {
"c3b2ba222d42a56e05c90f88d4509a124620517d": {
"kind": "NO_CHANGE",
"_number": 2,
"created": "2022-11-21 20: 56: 49.000000000",
"uploader": {
"_account_id": 1000000
},
"ref": "refs/changes/21/21/2",
"fetch": {
},
"commit": {
"parents": [
{
"commit": "7803f427dd7c4a2441466e4d740a1850dcee1af4",
"subject": "123"
}
],
"author": {
"name": "Nitzan Gur-Furman",
"email": "nitzan@google.com",
"date": "2022-11-21 20: 49: 39.000000000",
"tz": 60
},
"committer": {
"name": "Administrator",
"email": "admin@example.com",
"date": "2022-11-21 20: 56: 49.000000000",
"tz": 60
},
"subject": "456",
"message": "456\n"
},
"description": "Rebase"
}
},
"requirements": [
],
"submit_records": [
{
"rule_name": "gerrit~DefaultSubmitRule",
"status": "NOT_READY",
"labels": [
{
"label": "Code-Review",
"status": "NEED"
}
]
}
]
},
{
"id": "myProject~master~I08a021fb07b83fe845140a2c11508b3bdd93b48f",
"project": "myProject",
"branch": "master",
"hashtags": [
],
"change_id": "I08a021fb07b83fe845140a2c11508b3bdd93b48f",
"subject": "789",
"status": "NEW",
"created": "2022-11-21 20: 51: 31.000000000",
"updated": "2022-11-21 20: 56: 49.000000000",
"submit_type": "MERGE_IF_NECESSARY",
"insertions": 0,
"deletions": 0,
"total_comment_count": 0,
"unresolved_comment_count": 0,
"has_review_started": true,
"meta_rev_id": "3bfb843fea471f96e16b9199c3a30fff0285bc45",
"_number": 22,
"owner": {
"_account_id": 1000000
},
"current_revision_number": 2,
"current_revision": "77eb17a9501a5c21963bc6af56085e60f281acbb",
"revisions": {
"77eb17a9501a5c21963bc6af56085e60f281acbb": {
"kind": "NO_CHANGE",
"_number": 2,
"created": "2022-11-21 20: 56: 49.000000000",
"uploader": {
"_account_id": 1000000
},
"ref": "refs/changes/22/22/2",
"fetch": {
},
"commit": {
"parents": [
{
"commit": "c3b2ba222d42a56e05c90f88d4509a124620517d",
"subject": "456"
}
],
"author": {
"name": "Nitzan Gur-Furman",
"email": "nitzan@google.com",
"date": "2022-11-21 20: 51: 07.000000000",
"tz": 60
},
"committer": {
"name": "Administrator",
"email": "admin@example.com",
"date": "2022-11-21 20: 56: 49.000000000",
"tz": 60
},
"subject": "789",
"message": "789\n"
},
"description": "Rebase"
}
},
"requirements": [
],
"submit_records": [
{
"rule_name": "gerrit~DefaultSubmitRule",
"status": "NOT_READY",
"labels": [
{
"label": "Code-Review",
"status": "NEED"
}
]
}
]
}
],
}
----
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
Change I0e534de9d7f0d6f35b71f7d726acf835b2110c66 could not be rebased due to a conflict during
merge.
merge conflict(s):
a.txt
----
[[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"
},
"current_revision_number": 2
}
----
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"
},
"current_revision_number": 2
}
----
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"
},
"current_revision_number": 2
},
{
"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"
},
"current_revision_number": 2
}
]
----
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.
If the submission results in a new patch set (due to a rebase or cherry-pick merge method), the
committer email will remain the same as the one used in the previous commit, provided that one of
the secondary emails associated with the user performing the operation was used as the committer
email in the previous commit. Otherwise, the user's preferred email will be used.
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:user-attention-set.html[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"
},
"current_revision_number": 2
}
----
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 OR if the `o=TOPIC_CLOSURE` query parameter is passed, 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
options `NON_VISIBLE_CHANGES` and `TOPIC_CLOSURE`.
.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 submitted",
"-1": "I would prefer this is not submitted 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_number": 1,
"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 submitted",
"-1": "I would prefer this is not submitted 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_number": 1,
"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
----
[[apply-patch]]
=== Create patch-set from patch
--
'POST /changes/link:#change-id[\{change-id\}]/patch:apply'
--
Creates a new patch set on a destination change from the provided patch.
If one of the secondary emails associated with the user performing the operation was used as the
committer email in the current patch set, the same email will be used as the committer email in the
new patch set; otherwise, the user's preferred email will be used.
The patch must be provided in the request body, inside a
link:#applypatchpatchset-input[ApplyPatchPatchSetInput] entity.
If a base commit is given, the patch is applied on top of it. Otherwise, the
patch is applied on top of the target change's original parent.
Applying the patch will fail if the destination change is closed, or in case of any conflicts.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/patch:apply HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"patch": {
"patch": "new file mode 100644\n--- /dev/null\n+++ b/a_new_file.txt\n@@ -0,0 +1,2 @@ \
+Patch compatible `git diff` output \
+For example: `link:#get-patch[<gerrit patch>] | base64 -d | sed -z 's/\n/\\n/g'`"
}
}
----
As response a link:#change-info[ChangeInfo] entity is returned that
describes the destination change after applying the patch.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9941",
"project": "myProject",
"branch": "release-branch",
"change_id": "I8473b95934b5732ac55d26311a706c9c2bde9941",
"subject": "Original change subject",
"status": "NEW",
"created": "2013-02-01 09:59:32.126000000",
"updated": "2013-02-21 11:16:36.775000000",
"mergeable": true,
"insertions": 12,
"deletions": 11,
"_number": 3965,
"owner": {
"name": "John Doe"
},
"current_revision_number": 1,
"current_revision": "184ebe53805e102605d11f6b143486d15c23a09c"
}
----
[[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 (deprecated)
--
'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"
},
"current_revision_number": 2,
"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"
},
"current_revision_number": 2,
"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:user-attention-set.html[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:user-attention-set.html[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."
}
----
[[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"
]
----
[[get-custom-keyed-values]]
=== Get Custom Keyed Values
--
'GET /changes/link:#change-id[\{change-id\}]/custom_keyed_values'
--
Gets the custom keyed values associated with a change.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/custom_keyed_values HTTP/1.0
----
As response the change's custom keyed values are returned as a map of strings.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"key1": "value1",
"key2": "value2"
}
----
[[set-custom-keyed-values]]
=== Set Custom Keyed Values
--
'POST /changes/link:#change-id[\{change-id\}]/custom_keyed_values'
--
Adds and/or removes custom keyed values from a change.
The custom keyed values to add or remove must be provided in the request body
inside a link:#custom-keyed-values-input[CustomKeyedValuesInput] entity.
Note that custom keyed values are expected to be small in both key and value.
A typical use-case would be storing the ID to some external system, in which
case the key would be something unique to that system and the value would be
the ID.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/custom_keyed_values HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"add" : {
"key1": "value1"
},
"remove" : [
"key2"
]
}
----
As response the change's custom keyed values are returned as a map of strings to strings.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"key1": "value1",
"key3": "value3"
}
----
[[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 submit requirement can be specified in one of the following ways:
* In the request body as a link:#submit-requirement-input[SubmitRequirementInput].
* By passing the two request parameters `sr-name` and
`refs-config-change-id`. The submit requirement will then be loaded from
the project config pointed to by the latest patchset of this change ID.
The `sr-name` should point to an existing submit-requirement and the
`refs-config-change-id` must be a valid change identifier for a change in the
refs/meta/config branch, otherwise the request would fail with
`400 Bad Request`.
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 the details of the change edit done by the caller to the given change.
.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.
If one of the secondary emails associated with the user performing the operation was used as the
committer email in the latest patch set, the same email will be used as the committer email in the
new change edit commit; otherwise, the user's preferred email will be used.
.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==",
"file_mode": 100755
}
----
Note that it must be base-64 encoded data uri.
The "file_mode" field is optional, and if provided must be in octal format. The field
indicates whether the file is executable or not and has a value of either 100755
(executable) or 100644 (not executable). If it's unset, this indicates no change
has been made. New files default to not being executable if this parameter is not
provided
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.
If one of the secondary emails associated with the user performing the operation was used as the
committer email in the latest patch set, the same email will be used as the committer email in the
new change edit commit; otherwise, the user's preferred email will be used.
.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.
If one of the secondary emails associated with the user performing the operation was used as the
committer email in the latest patch set, the same email will be used as the committer email in the
new change edit commit; otherwise, the user's preferred email will be used.
.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.
If one of the secondary emails associated with the user performing the operation was used as the
committer email in the latest patch set, the same email will be used as the committer email in the
new change edit commit; otherwise, the user's preferred email will be used.
.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
----
[[put-change-edit-committer-author-identity]]
=== Change author or committer identity in Change Edit
--
'PUT /changes/link:#change-id[\{change-id\}]/edit:identity'
--
Modify author or committer identity. The request body needs to include a
link:#change-edit-identity-input[ChangeEditIdentityInput]
entity. Either `name` or `email` must be provided. `type` must be either `AUTHOR` or `COMMITTER`.
.Request
----
PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit:identity HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"name": "John Doe",
"email": "john.doe@example.com",
"type": "COMMITTER"
}
----
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
----
[[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.
If one of the secondary emails associated with the user performing the operation was used as the
committer email in the latest patch set, the same email will be used as the committer email in the
new change edit commit; otherwise, the user's preferred email will be used.
.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:
+
Whether an account is visible to the calling user depends on the
link:config-gerrit.html#accounts.visibility[accounts.visibility] setting of the
server. Which account visibility is configured can be checked by opening
`https://<HOST>/config/server/info?pp=1` in a browser (see field `accounts` >
link:rest-api-config.html#accounts-config-info[visibility] in the returned
JSON).
* 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.
NOTE: Adding multiple reviewers at once is possible via the
link:#set-review[Set Review] REST endpoint.
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.
Note, removing votes is generally disallowed for merged changes as this could
remove approvals that were necessary for the submission and it's confusing to
see a merged change which doesn't have the necessary approvals to fulfill the
submit requirements.
The request returns:
* '204 No Content' if the vote is deleted successfully;
* '404 Not Found' when the vote to be deleted is zero or not present.
* '409 Conflict' when the change is merged and hence deleting votes is not
allowed
.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'</