Google Git
Sign in
gerrit / gerrit / c3065f5a6bc5e3a23bf323415db76b3deb954571 / . / 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'
--
Retrieves a review of a revision.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/review HTTP/1.0
----
As response a link:#change-info[ChangeInfo] entity with
link:#detailed-labels[detailed labels] and link:#detailed-accounts[
detailed accounts] is returned that describes the review of the
revision. The revision for which the review is retrieved is contained
in the `revisions` field. In addition the `current_revision` field is
set if the revision for which the review is retrieved is the current
revision of the change. Please note that the returned labels are always
for the current patch set.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
"project": "myProject",
"branch": "master",
"change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940",
"subject": "Implementing Feature X",
"status": "NEW",
"created": "2013-02-01 09:59:32.126000000",
"updated": "2013-02-21 11:16:36.775000000",
"mergeable": true,
"insertions": 34,
"deletions": 45,
"_number": 3965,
"owner": {
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com"
},
"labels": {
"Verified": {
"all": [
{
"value": 0,
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com"
},
{
"value": 0,
"_account_id": 1000097,
"name": "Jane Roe",
"email": "jane.roe@example.com"
}
],
"values": {
"-1": "Fails",
" 0": "No score",
"+1": "Verified"
}
},
"Code-Review": {
"all": [
{
"value": -1,
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com"
},
{
"value": 1,
"_account_id": 1000097,
"name": "Jane Roe",
"email": "jane.roe@example.com"
}
]
"values": {
"-2": "This shall not be 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_reviewers": [
{
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com"
},
{
"_account_id": 1000097,
"name": "Jane Roe",
"email": "jane.roe@example.com"
}
],
"reviewers": {
"REVIEWER": [
{
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com"
},
{
"_account_id": 1000097,
"name": "Jane Roe",
"email": "jane.roe@example.com"
}
]
},
"current_revision_number": 2,
"current_revision": "674ac754f91e64a0efb8087e59a176484bd534d1",
"revisions": {
"674ac754f91e64a0efb8087e59a176484bd534d1": {
"kind": "REWORK",
"_number": 2,
"ref": "refs/changes/65/3965/2",
"fetch": {
"http": {
"url": "http://gerrit/myProject",
"ref": "refs/changes/65/3965/2"
}
}
}
}
}
----
[[get-related-changes]]
=== Get Related Changes
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/related'
--
Retrieves related changes of a revision. Related changes are changes that either
depend on, or are dependencies of the revision.
Additional fields can be obtained by adding `o` parameters. Since these may slow
down processing they are disabled by default. Currently a single parameter is
supported:
[[get-related-changes-submittable]]
--
* `SUBMITTABLE`: Compute the `submittable` field in the returned
link:#related-change-and-commit-info[RelatedChangeAndCommitInfo] entities.
--
.Request
----
GET /changes/gerrit~master~I5e4fc08ce34d33c090c9e0bf320de1b17309f774/revisions/b1cb4caa6be46d12b94c25aa68aebabcbb3f53fe/related HTTP/1.0
----
As result a link:#related-changes-info[RelatedChangesInfo] entity is returned
describing the related changes.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"changes": [
{
"project": "gerrit",
"change_id": "Ic62ae3103fca2214904dbf2faf4c861b5f0ae9b5",
"commit": {
"commit": "78847477532e386f5a2185a4e8c90b2509e354e3",
"parents": [
{
"commit": "bb499510bbcdbc9164d96b0dbabb4aa45f59a87e"
}
],
"author": {
"name": "David Ostrovsky",
"email": "david@ostrovsky.org",
"date": "2014-07-12 15:04:24.000000000",
"tz": 120
},
"subject": "Remove Solr"
},
"_change_number": 58478,
"_revision_number": 2,
"_current_revision_number": 2
"status": "NEW"
},
{
"project": "gerrit",
"change_id": "I5e4fc08ce34d33c090c9e0bf320de1b17309f774",
"commit": {
"commit": "b1cb4caa6be46d12b94c25aa68aebabcbb3f53fe",
"parents": [
{
"commit": "d898f12a9b7a92eb37e7a80636195a1b06417aad"
}
],
"author": {
"name": "David Pursehouse",
"email": "david.pursehouse@sonymobile.com",
"date": "2014-06-24 02:01:28.000000000",
"tz": 540
},
"subject": "Add support for secondary index with Elasticsearch"
},
"_change_number": 58081,
"_revision_number": 10,
"_current_revision_number": 10
"status": "NEW"
}
]
}
----
[[set-review]]
=== Set Review
--
'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/review'
--
Sets a review on a revision, optionally also publishing draft comments, setting
labels, adding reviewers or CCs, and modifying the work in progress property.
The review must be provided in the request body as a
link:#review-input[ReviewInput] entity.
If the labels are set, the user sending the request will automatically be
added as a reviewer, otherwise (if they only commented) they are added to
the CC list.
Posting a review usually updates the link:user-attention-set.html[attention
set].
A review cannot be set on a change edit. Trying to post a review for a
change edit fails with `409 Conflict`.
Here is an example of using this method to set labels:
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/review HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"tag": "jenkins",
"message": "Some nits need to be fixed.",
"labels": {
"Code-Review": -1
},
"comments": {
"gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": [
{
"line": 23,
"message": "[nit] trailing whitespace"
},
{
"line": 49,
"message": "[nit] s/conrtol/control"
},
{
"range": {
"start_line": 50,
"start_character": 0,
"end_line": 55,
"end_character": 20
},
"message": "Incorrect indentation"
}
]
}
}
----
As response a link:#review-result[ReviewResult] entity is returned that
describes the applied labels and any added reviewers (e.g. yourself,
if you set a label but weren't previously a reviewer on this CL).
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"labels": {
"Code-Review": -1
}
}
----
It is also possible to add one or more reviewers or CCs
to a change simultaneously with a review:
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/review HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"message": "I don't have context here. Jane and maybe John and the project leads should take a look.",
"reviewers": [
{
"reviewer": "jane.roe@example.com"
},
{
"reviewer": "john.doe@example.com",
"state": "CC"
}
{
"reviewer": "MyProjectVerifiers",
}
]
}
----
Each element of the `reviewers` list is an instance of
link:#reviewer-input[ReviewerInput]. The corresponding result of
adding each reviewer will be returned in a map of inputs to
link:#reviewer-result[ReviewerResult]s.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"reviewers": {
"jane.roe@example.com": {
"input": "jane.roe@example.com",
"reviewers": [
{
"_account_id": 1000097,
"name": "Jane Roe",
"email": "jane.roe@example.com"
"approvals": {
"Verified": " 0",
"Code-Review": " 0"
},
},
]
},
"john.doe@example.com": {
"input": "john.doe@example.com",
"ccs": [
{
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com"
"approvals": {
"Verified": " 0",
"Code-Review": " 0"
},
}
]
},
"MyProjectVerifiers": {
"input": "MyProjectVerifiers",
"reviewers": [
{
"_account_id": 1000098,
"name": "Alice Ansel",
"email": "alice.ansel@example.com"
"approvals": {
"Verified": " 0",
"Code-Review": " 0"
},
},
{
"_account_id": 1000099,
"name": "Bob Bollard",
"email": "bob.bollard@example.com"
"approvals": {
"Verified": " 0",
"Code-Review": " 0"
},
},
]
}
}
}
----
If there are any errors returned for reviewers, the entire review request will
be rejected with `400 Bad Request`. None of the entries will have the
`reviewers` or `ccs` field set, and those which specifically failed will have
the `errors` field set containing details of why they failed.
.Error Response
----
HTTP/1.1 400 Bad Request
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"reviewers": {
"jane.roe@example.com": {
"input": "jane.roe@example.com",
"error": "Account of jane.roe@example.com is inactive."
},
"john.doe@example.com": {
"input": "john.doe@example.com"
},
"MyProjectVerifiers": {
"input": "MyProjectVerifiers",
"error": "The group My Group has 15 members. Do you want to add them all as reviewers?",
"confirm": true
}
}
}
----
[[set-review-notifications]]
.Notifications
An email will be sent using the "comment" template.
If the top-level notify property is null or not set, then notification behavior
depends on whether the change is WIP, whether it has started review, and whether
the tag property is null.
NOTE: If adding reviewers, the notify property of each ReviewerInput is *ignored*.
Use the notify property of the top-level link:#review-input[ReviewInput] instead.
For the purposes of this table, *everyone* means *owner, reviewers, CCs, stars, and ALL_COMMENTS
watchers*.
[options="header",cols="2,1,1,2,2"]
|=============================
|WIP State |Review Started|Tag Given|Default |notify=ALL
|Ready for review|N/A |N/A |everyone|everyone
|Work in progress|no |no |not sent|everyone
|Work in progress|no |yes |owner |everyone
|Work in progress|yes |no |everyone|everyone
|Work in progress|yes |yes |owner |everyone
|=============================
If reviewers are added, then a second email will be sent using the "newchange"
template. The notification logic for this email is the same as for
link:#add-reviewer[Add Reviewer].
[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
|=============================
[[rebase-revision]]
=== Rebase Revision
--
'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/rebase'
--
Rebases a revision.
Optionally, the parent revision can be changed to another patch set through the
link:#rebase-input[RebaseInput] entity.
.Request
----
POST /changes/myProject~master~I3ea943139cb62e86071996f2480e58bf3eeb9dd2/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/rebase HTTP/1.0
Content-Type: application/json;charset=UTF-8
{
"base" : "1234",
}
----
As response a link:#change-info[ChangeInfo] entity is returned that
describes the rebased change. Information about the current patch set
is included.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "myProject~master~I3ea943139cb62e86071996f2480e58bf3eeb9dd2",
"project": "myProject",
"branch": "master",
"change_id": "I3ea943139cb62e86071996f2480e58bf3eeb9dd2",
"subject": "Implement Feature X",
"status": "NEW",
"created": "2013-02-01 09:59:32.126000000",
"updated": "2013-02-21 11:16:36.775000000",
"mergeable": false,
"insertions": 21,
"deletions": 21,
"_number": 4799,
"owner": {
"name": "John Doe"
},
"current_revision_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 revision cannot be rebased, e.g. due to conflicts, the response is
"`409 Conflict`" and the error message is contained in the response
body.
.Response
----
HTTP/1.1 409 Conflict
Content-Disposition: attachment
Content-Type: text/plain; charset=UTF-8
The change could not be rebased due to a path conflict during merge.
----
[[submit-revision]]
=== Submit Revision
--
'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/submit'
--
Submits a revision.
Submitting a change also removes all users from the link:user-attention-set.html[attention set].
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/submit HTTP/1.0
----
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 revision cannot be submitted, e.g. because the submit rule
doesn't allow submitting the revision or the revision is not the
current revision, the response is "`409 Conflict`" and the error
message is contained in the response body.
.Response
----
HTTP/1.1 409 Conflict
Content-Type: text/plain; charset=UTF-8
"revision 674ac754f91e64a0efb8087e59a176484bd534d1 is not current revision"
----
[[get-patch]]
=== Get Patch
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/patch'
--
Gets the formatted patch for one revision.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/patch HTTP/1.0
----
The formatted patch is returned as text encoded inside base64:
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: text/plain; charset=ISO-8859-1
X-FYI-Content-Encoding: base64
X-FYI-Content-Type: application/mbox
RnJvbSA3ZGFkY2MxNTNmZGVhMTdhYTg0ZmYzMmE2ZTI0NWRiYjY...
----
Adding query parameter `zip` (for example `/changes/.../patch?zip`)
returns the patch as a single file inside of a ZIP archive. Clients
can expand the ZIP to obtain the plain text patch, avoiding the
need for a base64 decoding step. This option implies `download`.
Query parameter `download` (e.g. `/changes/.../patch?download`)
will suggest the browser save the patch as `commitsha1.diff.base64`,
for later processing by command line tools.
If the `path` parameter is set, the returned content is a diff of the single
file that the path refers to.
[[get-mergeable]]
=== Get Mergeable
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/mergeable'
--
Gets the method the server will use to submit (merge) the change and
an indicator if the change is currently mergeable.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/mergeable HTTP/1.0
----
As response a link:#mergeable-info[MergeableInfo] entity is returned.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
submit_type: "MERGE_IF_NECESSARY",
strategy: "recursive",
mergeable: true
}
----
If the `other-branches` parameter is specified, the mergeability will also be
checked for all other branches which are listed in the
link:config-project-config.html#branchOrder-section[branchOrder] section in the
project.config file.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/mergeable?other-branches HTTP/1.0
----
The response will then contain a list of all other branches where this changes
could merge cleanly.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
submit_type: "MERGE_IF_NECESSARY",
mergeable: true,
mergeable_into: [
"refs/heads/stable-2.7",
"refs/heads/stable-2.8",
]
}
----
[[get-submit-type]]
=== Get Submit Type
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/submit_type'
--
Gets the method the server will use to submit (merge) the change.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/submit_type HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
"MERGE_IF_NECESSARY"
----
[[test-submit-type]]
=== Test Submit Type
--
'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/test.submit_type'
--
Tests the submit_type Prolog rule in the project, or the one given.
Request body may be either the Prolog code as `text/plain` or a
link:#rule-input[RuleInput] object. The query parameter `filters`
may be set to `SKIP` to bypass parent project filters while testing
a project-specific rule.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/test.submit_type HTTP/1.0
Content-Type: text/plain; charset=UTF-8
submit_type(cherry_pick).
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
"CHERRY_PICK"
----
[[test-submit-rule]]
=== Test Submit Rule
--
'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/test.submit_rule'
--
Tests the submit_rule Prolog rule in the project, or the one given.
Request body may be either the Prolog code as `text/plain` or a
link:#rule-input[RuleInput] object. The query parameter `filters`
may be set to `SKIP` to bypass parent project filters while testing
a project-specific rule.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/test.submit_rule?filters=SKIP HTTP/1.0
Content-Type: text/plain; charset=UTF-8
submit_rule(submit(R)) :-
R = label('Any-Label-Name', reject(_)).
----
The response is a link:#submit-record[SubmitRecord] describing the
permutations that satisfy the tested submit rule.
If the submit rule was a no-op, the response is "`204 No Content`".
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"status": "NOT_READY",
"reject": {
"Any-Label-Name": {}
}
}
----
When testing with the `curl` command line client the
`--data-binary @rules.pl` flag should be used to ensure
all LFs are included in the Prolog code:
----
curl -X POST \
-H 'Content-Type: text/plain; charset=UTF-8' \
--data-binary @rules.pl \
http://.../test.submit_rule
----
[[list-drafts]]
=== List Revision Drafts
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/drafts/'
--
Lists the draft comments of a revision that belong to the calling
user.
Returns a map of file paths to lists of link:#comment-info[CommentInfo]
entries. The entries in the map are sorted by file path.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/drafts/ HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": [
{
"id": "TvcXrmjM",
"line": 23,
"message": "[nit] trailing whitespace",
"updated": "2013-02-26 15:40:43.986000000"
},
{
"id": "TveXwFiA",
"line": 49,
"in_reply_to": "TfYX-Iuo",
"message": "Done",
"updated": "2013-02-26 15:40:45.328000000"
}
]
}
----
[[create-draft]]
=== Create Draft
--
'PUT /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/drafts'
--
Creates a draft comment on a revision.
The new draft comment must be provided in the request body inside a
link:#comment-input[CommentInput] entity.
.Request
----
PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/drafts HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"line": 23,
"message": "[nit] trailing whitespace"
}
----
As response a link:#comment-info[CommentInfo] entity is returned that
describes the draft comment.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "TvcXrmjM",
"path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"line": 23,
"message": "[nit] trailing whitespace",
"updated": "2013-02-26 15:40:43.986000000"
}
----
[[get-draft]]
=== Get Draft
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/drafts/link:#draft-id[\{draft-id\}]'
--
Retrieves a draft comment of a revision that belongs to the calling
user.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/drafts/TvcXrmjM HTTP/1.0
----
As response a link:#comment-info[CommentInfo] entity is returned that
describes the draft comment.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "TvcXrmjM",
"path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"line": 23,
"message": "[nit] trailing whitespace",
"updated": "2013-02-26 15:40:43.986000000"
}
----
[[update-draft]]
=== Update Draft
--
'PUT /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/drafts/link:#draft-id[\{draft-id\}]'
--
Updates a draft comment on a revision.
The new draft comment must be provided in the request body inside a
link:#comment-input[CommentInput] entity.
.Request
----
PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/drafts/TvcXrmjM HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"line": 23,
"message": "[nit] trailing whitespace"
}
----
As response a link:#comment-info[CommentInfo] entity is returned that
describes the draft comment.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "TvcXrmjM",
"path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"line": 23,
"message": "[nit] trailing whitespace",
"updated": "2013-02-26 15:40:43.986000000"
}
----
[[delete-draft]]
=== Delete Draft
--
'DELETE /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/drafts/link:#draft-id[\{draft-id\}]'
--
Deletes a draft comment from a revision.
.Request
----
DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/drafts/TvcXrmjM HTTP/1.0
----
.Response
----
HTTP/1.1 204 No Content
----
[[list-comments]]
=== List Revision Comments
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/comments/'
--
Lists the published comments of a revision.
As result a map is returned that maps the file path to a list of
link:#comment-info[CommentInfo] entries. The entries in the map are
sorted by file path and only include file (or inline) comments. Use
the link:#get-change-detail[Get Change Detail] endpoint to retrieve
the general change message (or comment).
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/comments/ HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": [
{
"id": "TvcXrmjM",
"line": 23,
"message": "[nit] trailing whitespace",
"updated": "2013-02-26 15:40:43.986000000",
"author": {
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com"
}
},
{
"id": "TveXwFiA",
"line": 49,
"in_reply_to": "TfYX-Iuo",
"message": "Done",
"updated": "2013-02-26 15:40:45.328000000",
"author": {
"_account_id": 1000097,
"name": "Jane Roe",
"email": "jane.roe@example.com"
}
}
]
}
----
[[get-comment]]
=== Get Comment
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/comments/link:#comment-id[\{comment-id\}]'
--
Retrieves a published comment of a revision.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/comments/TvcXrmjM HTTP/1.0
----
As response a link:#comment-info[CommentInfo] entity is returned that
describes the published comment.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "TvcXrmjM",
"path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"line": 23,
"message": "[nit] trailing whitespace",
"updated": "2013-02-26 15:40:43.986000000",
"author": {
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com"
}
}
----
[[delete-comment]]
=== Delete Comment
--
'DELETE /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/comments/link:#comment-id[\{comment-id\}]' +
'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/comments/link:#comment-id[\{comment-id\}]/delete'
--
Deletes a published comment of a revision. Instead of deleting the
whole comment, this endpoint just replaces the comment's message
with a new message, which contains the name of the user who deletes
the comment and the reason why it's deleted.
This endpoint also marks the comment as resolved since deleted comments are not
actionable.
Note that only users with the
link:access-control.html#capability_administrateServer[Administrate Server]
global capability are permitted to delete a comment.
Deletion reason can be provided in the request body as a
link:#delete-comment-input[DeleteCommentInput] 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/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/comments/TvcXrmjM/delete HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"reason": "contains confidential information"
}
----
As response a link:#comment-info[CommentInfo] entity is returned that
describes the updated comment.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "TvcXrmjM",
"path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"line": 23,
"message": "Comment removed by: Administrator; Reason: contains confidential information",
"updated": "2013-02-26 15:40:43.986000000",
"author": {
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com"
}
}
----
[[list-robot-comments]]
=== List Robot Comments (deprecated)
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/robotcomments/'
--
Lists the link:config-robot-comments.html[robot comments] of a
revision.
As result a map is returned 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/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/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"
}
]
}
----
[[get-robot-comment]]
=== Get Robot Comment (deprecated)
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/robotcomments/link:#comment-id[\{comment-id\}]'
--
Retrieves a link:config-robot-comments.html[robot comment] of a
revision.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/robotcomments/TvcXrmjM HTTP/1.0
----
As response a link:#robot-comment-info[RobotCommentInfo] entity is
returned that describes the robot comment.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"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"
}
----
[[list-ported-comments]]
=== List Ported Comments
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/ported_comments'
--
Ports comments of other revisions to the requested revision.
Only comments added on earlier patchsets are ported. That set of comments is filtered even further
due to some additional rules. Callers of this endpoint shouldn't rely on the exact logic of which
comments are ported as that logic might change in the future. Instead, callers must be able to
handle any smaller/larger set of comments returned by this endpoint.
Typically, a comment thread is returned fully or excluded fully. However, draft comments and
robot comments are ignored and not returned via this endpoint. Hence, it's possible to get ported
comments from this endpoint which are a reply to a non-ported robot comment. Callers must be
able to deal with this situation.
The returned comments are organized in a map of file path to link:#comment-info[CommentInfo] entries
in the same fashion as for the link:#list-comments[List Revision Comments] endpoint.
The map is filled with the original comment attributes except for these attributes: `path`, `line`,
and `range` point to the computed position in the target revision. If the exactly correct position
can't be determined, those fields will be filled with the next best position. That can also mean
not filling the `line` or `range` attribute anymore and thus converting the comment to a file
comment (or even moving the comment to a different file or the patchset level). Callers of this
endpoint must be able to deal with this and not rely on the original comment position.
It's possible that this endpoint returns different link:#comment-info[CommentInfo] entries with
the same comment UUID. This is not a bug but a feature. If a comment appears on a file which Gerrit
recognizes as copied between patchsets, the ported version of this comment consists of two ported
instances having the same UUID but different `file`/`line`/`range` positions. Callers must be able
to handle this situation.
Repeated calls of this endpoint might produce different results. Internal errors during the
position computation are mapped to fallback locations for affected comments. Those errors might
have vanished on later calls, upon which this endpoint returns the actually mapped position. In
addition, comments can be deleted and draft comments can be published, upon which the set of ported
comments may change.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/4/ported_comments/ HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": [
{
"id": "TvcXrmjM",
"patch_set": 2,
"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"
},
"unresolved": true
},
{
"id": "TveXwFiA",
"patch_set": 2,
"line": 23,
"in_reply_to": "TvcXrmjM",
"message": "Done",
"updated": "2013-02-26 15:40:45.328000000",
"author": {
"_account_id": 1000097,
"name": "Jane Roe",
"email": "jane.roe@example.com"
},
"unresolved": true
}
]
}
----
[[list-ported-drafts]]
=== List Ported Drafts
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/ported_drafts'
--
Ports draft comments of other revisions to the requested revision.
This endpoint behaves similarly to the link:#list-ported-comments[List Ported Comments] endpoint.
With this endpoint, only draft comments of the calling user are ported, though. If a draft comment
is a reply to a published comment, only the ported draft comment is returned.
Depending on the filtering rules, it's possible that this endpoint returns a draft comment which is
a reply to a comment thread which is not returned by the
link:#list-ported-comments[List Ported Comments] endpoint. That's intended behavior. Callers must be
able to handle this situation. The same holds for drafts which are a reply to a robot comment.
Different than the link:#list-ported-comments[List Ported Comments] endpoint, the `author` of the
returned comments is not filled for this endpoint as only comments of the calling user are returned.
This endpoint requires authentication.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/ported_drafts/ HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": [
{
"id": "TveXwFiA",
"patch_set": 2,
"line": 23,
"in_reply_to": "TvcXrmjM",
"message": "Done",
"updated": "2013-02-26 15:40:45.328000000",
"unresolved": true
}
]
}
----
[[apply-stored-fix]]
=== Apply Stored Fix
--
'POST /changes/<<change-id,\{change-id\}>>/revisions/<<revision-id,\{revision-id\}>>/fixes/<<fix-id,\{fix-id\}>>/apply'
--
Applies a suggested fix by creating a change edit which includes the
modifications indicated by the fix suggestion. If a change edit already exists,
it will be updated accordingly. A fix can only be applied if no change edit
exists and the fix refers to the current patch set, or the fix refers to the
patch set on which the change edit is based.
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 change edit commit; otherwise, the user's preferred email will be used.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/fixes/8f605a55_f6aa4ecc/apply HTTP/1.0
----
If the fix was successfully applied, an <<edit-info,EditInfo>> describing the
resulting change edit is returned.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"commit": {
"parents": [
{
"commit": "1eee2c9d8f352483781e772f35dc586a69ff5646",
}
],
"author": {
"name": "John Doe",
"email": "john.doe@example.com",
"date": "2013-05-07 15:21:27.000000000",
"tz": 120
},
"committer": {
"name": "Jane Doe",
"email": "jane.doe@example.com",
"date": "2013-05-07 15:35:43.000000000",
"tz": 120
},
"subject": "Implement feature X",
"message": "Implement feature X\n\nWith this feature ..."
},
"base_patch_set_number": 1,
"base_revision": "674ac754f91e64a0efb8087e59a176484bd534d1"
"ref": "refs/users/01/1000001/edit-42622/1"
}
----
If the application failed e.g. due to conflicts with an existing change edit,
the response "`409 Conflict`" including an error message in the response body
is returned.
.Response
----
HTTP/1.1 409 Conflict
Content-Disposition: attachment
Content-Type: text/plain; charset=UTF-8
Rebasing change edit onto another patchset results in merge conflicts. Download the edit patchset and rebase manually to preserve changes.
----
[[apply-provided-fix]]
==== Apply Provided Fix
--
'POST /changes/<<change-id,\{change-id\}>>/revisions/<<revision-id,\{revision-id\}>>/fix:apply'
--
Applies a list of <<fix-replacement-info,FixReplacementInfo>> loaded from the
<<apply-provided-fix-input,ApplyProvidedFixInput>> entity. The fixes are passed as part of the request body. The
application of the fixes creates a new change edit. `Apply Provided Fix` can only be applied on the current
patchset.
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 change edit commit; otherwise, the user's preferred email will be used.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/fix:apply HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"fix_replacement_infos": [
{
"path": "abcd.txt",
"range": {
"start_line": 2,
"start_character": 2,
"end_line": 2,
"end_character": 5
},
"replacement": "abcdefg"
}
]
}
----
If the `ApplyProvidedFixInput` was successfully applied, an link:#edit-info[EditInfo] describing the
resulting change edit is returned.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"commit": {
"commit": "bd43e48c33d2b1a03485040eba38cefc505f7997",
"parents": [
{
"commit": "9825962f8ab6da89afebad3f5034db05fb4b7560"
}
],
"author": {
"name": "John Doe",
"email": "john.doe@example.com",
"date": "2022-05-07 15:21:27.000000000",
"tz": 120
},
"committer": {
"name": "Jane Doe",
"email": "jane.doe@example.com",
"date": "2022-05-07 15:35:43.000000000",
"tz": 120
},
"subject": "Implement feature X",
"message": "Implement feature X\n\nWith this feature ..."
},
"base_patch_set_number": 1,
"base_revision": "86d87686ce0ef7f7c536bfc7e9a66f5a6fa5d658",
"ref": "refs/users/01/1000001/edit-1/1"
}
----
If the application failed due to presence of an existing change edit,
the response "`400 Bad Request`" including an error message in the response body
is returned.
.Response
----
HTTP/1.1 400 Bad Request
Content-Disposition: attachment
Content-Type: text/plain; charset=UTF-8
Change edit already exists. A new change edit can't be created
----
If the application failed due to application on a previous patch set, the response
"`409 Conflict`" including an error message in the response body is returned.
.Response
----
HTTP/1.1 409 Conflict
Content-Disposition: attachment
Content-Type: text/plain; charset=UTF-8
A change edit may only be created for the current patch set 1,2 (and not for 1,1)
----
[[list-files]]
=== List Files
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/files/'
--
Lists the files that were modified, added or deleted in a revision.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/ HTTP/1.0
----
As result a map is returned that maps the link:#file-id[file path] to a
link:#file-info[FileInfo] entry. The entries in the map are
sorted by file path.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"/COMMIT_MSG": {
"status": "A",
"lines_inserted": 7,
"size_delta": 551,
"size": 551
},
"gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": {
"lines_inserted": 5,
"lines_deleted": 3,
"size_delta": 98,
"size": 23348
}
}
----
The request parameter `reviewed` changes the response to return a list
of the paths the caller has marked as reviewed. Clients that also
need the FileInfo should make two requests.
The request parameter `q` changes the response to return a list
of all files (modified or unmodified) that contain that substring
in the path name. This is useful to implement suggestion services
finding a file by partial name. Clients that also need the FileInfo
should make two requests.
For merge commits only, the integer-valued request parameter `parent`
changes the response to return a map of the files which are different
in this commit compared to the given parent commit. The value is the
1-based index of the parent's position in the commit object,
with the first parent always belonging to the target branch. If not
specified, the response contains a map of the files different in the
auto merge result.
The request parameter `base` changes the response to return a map of the
files which are different in this commit compared to the given revision. The
revision must correspond to a patch set in the change.
The `reviewed`, `q`, `parent`, and `base` options are mutually exclusive.
That is, only one of them may be used at a time.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/?reviewed HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
[
"/COMMIT_MSG",
"gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
]
----
[[get-content]]
=== Get Content
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/files/link:#file-id[\{file-id\}]/content'
--
Gets the content of a file from a certain revision.
The optional, integer-valued `parent` parameter can be specified to request
the named file from a parent commit of the specified revision. The value is
the 1-based index of the parent's position in the commit object. If the
parameter is omitted or the value is non-positive, the patch set is referenced.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/content HTTP/1.0
----
The content is returned as base64 encoded string. The HTTP response
Content-Type is always `text/plain`, reflecting the base64 wrapping.
A Gerrit-specific `X-FYI-Content-Type` header is returned describing
the server detected content type of the file.
If only the content type is required, callers should use HEAD to
avoid downloading the encoded file contents.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: text/plain; charset=ISO-8859-1
X-FYI-Content-Encoding: base64
X-FYI-Content-Type: text/xml
Ly8gQ29weXJpZ2h0IChDKSAyMDEwIFRoZSBBbmRyb2lkIE9wZW4gU291cmNlIFByb2plY...
----
Alternatively, if the only value of the Accept request header is
`application/json` the content is returned as JSON string and
`X-FYI-Content-Encoding` is set to `json`.
[[get-safe-content]]
=== Download Content
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/files/link:#file-id[\{file-id\}]/download'
--
Downloads the content of a file from a certain revision, in a safe format
that poses no risk for inadvertent execution of untrusted code.
If the content type is defined as safe, the binary file content is returned
verbatim. If the content type is not safe, the file is stored inside a ZIP
file, containing a single entry with a random, unpredictable name having the
same base and suffix as the true filename. The ZIP file is returned in
verbatim binary form.
See link:config-gerrit.html#mimetype.name.safe[Gerrit config documentation]
for information about safe file type configuration.
The HTTP resource Content-Type is dependent on the file type: the
applicable type for safe files, or "application/zip" for unsafe files.
The optional, integer-valued `parent` parameter can be specified to request
the named file from a parent commit of the specified revision. The value is
the 1-based index of the parent's position in the commit object. If the
parameter is omitted or the value non-positive, the patch set is referenced.
Filenames are decorated with a suffix of `_new` for the current patch,
`_old` for the only parent, or `_oldN` for the Nth parent of many.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/website%2Freleases%2Flogo.png/download HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment; filename="logo.png"
Content-Type: image/png
`[binary data for logo.png]`
----
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/download?suffix=new HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: Content-Disposition:attachment; filename="RefControl_new-931cdb73ae9d97eb500a3533455b055d90b99944.java.zip"
Content-Type:application/zip
`[binary ZIP archive containing a single file, "RefControl_new-cb218df1337df48a0e7ab30a49a8067ac7321881.java"]`
----
[[get-diff]]
=== Get Diff
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/files/link:#file-id[\{file-id\}]/diff'
--
Gets the diff of a file from a certain revision.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/diff HTTP/1.0
----
As response a link:#diff-info[DiffInfo] entity is returned that describes the diff.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]
{
"meta_a": {
"name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"content_type": "text/x-java-source",
"lines": 372
},
"meta_b": {
"name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"content_type": "text/x-java-source",
"lines": 578
},
"change_type": "MODIFIED",
"diff_header": [
"diff --git a/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java b/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"index 59b7670..9faf81c 100644",
"--- a/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"+++ b/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java"
],
"content": [
{
"ab": [
"// Copyright (C) 2010 The Android Open Source Project",
"//",
"// Licensed under the Apache License, Version 2.0 (the \"License\");",
"// you may not use this file except in compliance with the License.",
"// You may obtain a copy of the License at",
"//",
"// http://www.apache.org/licenses/LICENSE-2.0",
"//",
"// Unless required by applicable law or agreed to in writing, software",
"// distributed under the License is distributed on an \"AS IS\" BASIS,",
"// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.",
"// See the License for the specific language governing permissions and",
"// limitations under the License."
]
},
{
"b": [
"//",
"// Add some more lines in the header."
]
},
{
"ab": [
"",
"package com.google.gerrit.server.project;",
"",
"import com.google.common.collect.Maps;",
...
]
}
...
]
}
----
If the `intraline` parameter is specified, intraline differences are included in the diff.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/b6b9c10649b9041884046119ab794374470a1b45/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/diff?intraline HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]
{
"meta_a": {
"name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"content_type": "text/x-java-source",
"lines": 372
},
"meta_b": {
"name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"content_type": "text/x-java-source",
"lines": 578
},
"change_type": "MODIFIED",
"diff_header": [
"diff --git a/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java b/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"index 59b7670..9faf81c 100644",
"--- a/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"+++ b/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java"
],
"content": [
...
{
"a": [
"/** Manages access control for Git references (aka branches, tags). */"
],
"b": [
"/** Manages access control for the Git references (aka branches, tags). */"
],
"edit_a": [],
"edit_b": [
[
31,
4
]
]
}
]
}
----
The `base` parameter can be specified to control the base patch set from which the diff should
be generated.
The integer-valued request parameter `parent` can be specified to control the
parent commit number against which the diff should be generated. This is useful
for supporting review of merge commits. The value is the 1-based index of the
parent's position in the commit object.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/b6b9c10649b9041884046119ab794374470a1b45/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/diff?base=2 HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]
{
"meta_a": {
"name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"content_type": "text/x-java-source",
"lines": 578
},
"meta_b": {
"name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
"content_type": "text/x-java-source",
"lines": 578
},
"change_type": "MODIFIED",
"content": [
{
"skip": 578
}
]
}
----
The `whitespace` parameter can be specified to control how whitespace
differences are reported in the result. Valid values are `IGNORE_NONE`,
`IGNORE_TRAILING`, `IGNORE_LEADING_AND_TRAILING` or `IGNORE_ALL`.
[[preview-stored-fix]]
=== Preview Stored Fix
--
'GET /changes/<<change-id,\{change-id\}>>/revisions/<<revision-id,\{revision-id\}>>/fixes/<<fix-id,\{fix-id\}>>/preview'
--
Gets the diffs of all files for a certain <<fix-id,\{fix-id\}>>.
As response, a map of link:#diff-info[DiffInfo] entities is returned that describes the diffs.
Each link:#diff-info[DiffInfo] is the differences between the patch set indicated by revision-id and a virtual patch set with the applied fix.
[[preview-provided-fix]]
=== Preview Provided fix
--
'POST /changes/<<change-id,\{change-id\}>>/revisions/<<revision-id,\{revision-id\}>>/fix:preview'
--
Gets the diffs of all files for a list of <<fix-replacement-info,FixReplacementInfo>> loaded from
the <<apply-provided-fix-input,ApplyProvidedFixInput>> entity. The fixes are passed as part of the
request body.
As response, a map of link:#diff-info[DiffInfo] is returned that describes the diffs.
Each link:#diff-info[DiffInfo] is the differences between the patch set indicated by revision-id
and a virtual patch set with the applied fix. No content on the server will be modified as part of this request.
.Request
----
POST /changes/myProject~master~Id6f0b9d946791f8aba90ace53074eda565983452/revisions/1/fix:preview HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"fix_replacement_infos": [
{
"path": "abcd.txt",
"range": {
"start_line": 2,
"start_character": 2,
"end_line": 2,
"end_character": 5
},
"replacement": "abcdefg"
}
]
}
----
If the `Preview Provided Fix` operation was successful, a link:#diff-info[DiffInfo] previewing the
change is returned.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"abcd.txt": {
"meta_a": {
"name": "abcd.txt",
"content_type": "text/plain",
"lines": 3
},
"meta_b": {
"name": "abcd.txt",
"content_type": "text/plain",
"lines": 3
},
"intraline_status": "OK",
"change_type": "MODIFIED",
"content": [
{
"ab": [
"ABCDEFGHI"
]
},
{
"a": [
"JKLMNOPQR"
],
"b": [
"JKabcdefgOPQR"
],
"edit_a": [
[
2,
3
]
],
"edit_b": [
[
2,
7
]
]
},
{
"ab": [
""
]
}
]
}
}
----
[[get-blame]]
=== Get Blame
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/files/link:#file-id[\{file-id\}]/blame'
--
Gets the blame of a file from a certain revision.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/blame HTTP/1.0
----
As response a link:#blame-info[BlameInfo] entity is returned that describes the
blame.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]
{
[
{
"author": "Joe Daw",
"id": "64e140b4de5883a4dd74d06c2b62ccd7ffd224a7",
"time": 1421441349,
"commit_msg": "RST test\n\nChange-Id: I11e9e24bd122253f4bb10c36dce825ac2410d646\n",
"ranges": [
{
"start": 1,
"end": 10
},
{
"start": 16,
"end": 296
}
]
},
{
"author": "Jane Daw",
"id": "8d52621a0e2ac6adec73bd3a49f2371cd53137a7",
"time": 1421825421,
"commit_msg": "add banner\n\nChange-Id: I2eced9b2691015ae3c5138f4d0c4ca2b8fb15be9\n",
"ranges": [
{
"start": 13,
"end": 13
}
]
}
]
}
----
The `base` parameter can be specified to control the base patch set from which
the blame should be generated.
[[set-reviewed]]
=== Set Reviewed
--
'PUT /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/files/link:#file-id[\{file-id\}]/reviewed'
--
Marks a file of a revision as reviewed by the calling user.
.Request
----
PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/reviewed HTTP/1.0
----
.Response
----
HTTP/1.1 201 Created
----
If the file was already marked as reviewed by the calling user the
response is "`200 OK`".
[[delete-reviewed]]
=== Delete Reviewed
--
'DELETE /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/files/link:#file-id[\{file-id\}]/reviewed'
--
Deletes the reviewed flag of the calling user from a file of a revision.
.Request
----
DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/reviewed HTTP/1.0
----
.Response
----
HTTP/1.1 204 No Content
----
[[cherry-pick]]
=== Cherry Pick Revision
--
'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/cherrypick'
--
Cherry picks a revision to a destination branch.
If one of the secondary emails associated with the user performing the operation was used as the
committer email in the original revision, the same email will be used as the committer email
in the new patch set; otherwise, the user's preferred email will be used.
To cherry pick a commit with no change-id associated with it, see
link:rest-api-projects.html#cherry-pick-commit[CherryPickCommit].
The commit message and destination branch must be provided in the request body inside a
link:#cherrypick-input[CherryPickInput] entity. If the commit message
does not specify a Change-Id, a new one is picked for the destination change.
When cherry-picking a change into a branch that already contains the Change-Id
that we want to cherry-pick, the cherry-pick will create a new patch-set on the
destination's branch's appropriate Change-Id. If the change is closed on the
destination branch, the cherry-pick will fail.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/cherrypick HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"message" : "Implementing Feature X",
"destination" : "release-branch"
}
----
As response a link:#change-info[ChangeInfo] entity is returned that
describes the resulting cherry-pick change.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9941",
"project": "myProject",
"branch": "release-branch",
"change_id": "I8473b95934b5732ac55d26311a706c9c2bde9941",
"subject": "Implementing Feature X",
"status": "NEW",
"created": "2013-02-01 09:59:32.126000000",
"updated": "2013-02-21 11:16:36.775000000",
"mergeable": true,
"insertions": 12,
"deletions": 11,
"_number": 3965,
"owner": {
"name": "John Doe"
},
"current_revision_number": 2
}
----
[[revision-reviewer-endpoints]]
== Revision Reviewer Endpoints
[[list-revision-reviewers]]
=== List Revision Reviewers
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/reviewers/'
--
Lists the reviewers of a revision.
Please note that only the current revision is supported.
As result a list of link:#reviewer-info[ReviewerInfo] entries is returned.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/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"
}
]
----
[[list-revision-votes]]
=== List Revision Votes
--
'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/reviewers/link:rest-api-accounts.html#account-id[\{account-id\}]/votes/'
--
Lists the votes for a specific reviewer of the revision.
Please note that only the current revision is supported.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/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-revision-vote]]
=== Delete Revision Vote
--
'DELETE /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]
/reviewers/link:rest-api-accounts.html#account-id[\{account-id\}]/votes/link:#label-id[\{label-id\}]' +
'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]
/reviewers/link:rest-api-accounts.html#account-id[\{account-id\}]/votes/link:#label-id[\{label-id\}]/delete'
--
Deletes a single vote from a revision. The deletion will be possible only
if the revision is the current revision. By using this endpoint you can prevent
deleting the vote (with same label) from a newer patch set by mistake.
Note, that even when the last vote of a reviewer is removed the reviewer itself
is still listed on the change.
If another user removed a user's vote, the user with the deleted vote will be
added to the attention set.
.Request
----
DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/reviewers/John%20Doe/votes/Code-Review HTTP/1.0
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/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/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/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
----
[[attention-set-endpoints]]
== Attention Set Endpoints
[[get-attention-set]]
=== Get Attention Set
--
'GET /changes/link:#change-id[\{change-id\}]/attention'
--
Returns all users that are currently in the attention set.
As response a list of link:#attention-set-info[AttentionSetInfo]
entity is returned.
.Request
----
GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/attention HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
[
{
"account": {
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com",
"username": "jdoe"
},
"last_update": "2013-02-01 09:59:32.126000000",
"reason": "reviewer or cc replied"
},
{
"account": {
"_account_id": 1000097,
"name": "Jane Doe",
"email": "jane.doe@example.com",
"username": "janedoe"
},
"last_update": "2013-02-01 09:59:32.126000000",
"reason": "Reviewer was added"
}
]
----
[[add-to-attention-set]]
=== Add To Attention Set
--
'POST /changes/link:#change-id[\{change-id\}]/attention'
--
Adds a single user to the attention set of a change.
A user can only be added if they are not in the attention set.
If a user is added while already in the attention set, the
request is silently ignored.
The user must be a reviewer, cc, uploader, or owner on the change.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/attention HTTP/1.0
----
Details should be provided in the request body as an
link:#attention-set-input[AttentionSetInput] entity.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/attention HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"user": "John Doe",
"reason": "reason"
}
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"_account_id": 1000096,
"name": "John Doe",
"email": "john.doe@example.com",
"username": "jdoe"
}
----
[[remove-from-attention-set]]
=== Remove from Attention Set
--
'DELETE /changes/link:#change-id[\{change-id\}]/attention/link:rest-api-accounts.html#account-id[\{account-id\}]' +
'POST /changes/link:#change-id[\{change-id\}]/attention/link:rest-api-accounts.html#account-id[\{account-id\}]/delete'
--
Deletes a single user from the attention set of a change.
A user can only be removed from the attention set if they
are currently in the attention set. Otherwise, the request
is silently ignored.
.Request
----
DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/attention/John%20Doe HTTP/1.0
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/attention/John%20Doe/delete HTTP/1.0
----
Reason can be provided in the request body as an
link:#attention-set-input[AttentionSetInput] entity.
User must be left empty, or the user must be exactly
the same user as in the request header.
.Request
----
POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/attention/John%20Doe/delete HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"reason": "reason"
}
----
.Response
----
HTTP/1.1 204 No Content
----
[[ids]]
== IDs
[[account-id]]
=== link:rest-api-accounts.html#account-id[\{account-id\}]
--
--
[[change-id]]
=== \{change-id\}
Identifier that uniquely identifies one change. It contains the URL-encoded
project name as well as the change number: "<project>~<changeNumber>"
==== Alternative identifiers
Gerrit also supports an array of other change identifiers.
[NOTE]
Even though these identifiers will work in the majority of cases it is highly
recommended to use "<project>~<changeNumber>" whenever possible.
Since these identifiers require additional lookups from index and caches, to
be translated to the "<project>~<changeNumber>" identifier, they
may result in both false-positives and false-negatives.
Furthermore the additional lookup mean that they come with a performance penalty.
* an ID of the change in the format "<project>\~<branch>~<Change-Id>",
where for the branch the `refs/heads/` prefix can be omitted
("myProject\~master~I8473b95934b5732ac55d26311a706c9c2bde9940")
* a Change-Id if it uniquely identifies one change
("I8473b95934b5732ac55d26311a706c9c2bde9940")
* a change number if it uniquely identifies one change ("4247")
[[change-message-id]]
=== \{change-message-id\}
ID of a change message returned in a link:#change-message-info[ChangeMessageInfo].
[[comment-id]]
=== \{comment-id\}
UUID of a published comment.
[[draft-id]]
=== \{draft-id\}
UUID of a draft comment.
[[label-id]]
=== \{label-id\}
The name of the label.
[[file-id]]
=== \{file-id\}
The path of the file.
The following magic paths are supported:
* `/COMMIT_MSG`:
+
The commit message and headers with the parent commit(s), the author
information and the committer information.
* `/MERGE_LIST` (for merge commits only):
+
The list of commits that are being integrated into the destination
branch by submitting the merge commit.
* `/PATCHSET_LEVEL`:
+
This file path is used exclusively for posting and indicating
patchset-level comments, thus not relevant for other use-cases.
[[fix-id]]
=== \{fix-id\}
UUID of a suggested fix.
[[revision-id]]
=== \{revision-id\}
Identifier that uniquely identifies one revision of a change.
This can be:
* the literal `current` to name the current patch set/revision
* a commit ID ("674ac754f91e64a0efb8087e59a176484bd534d1")
* an abbreviated commit ID that uniquely identifies one revision of the
change ("674ac754"), at least 4 digits are required
* a numeric patch number ("1" for first patch set of the change)
* "0" or the literal `edit` for a change edit
[[json-entities]]
== JSON Entities
[[abandon-input]]
=== AbandonInput
The `AbandonInput` entity contains information for abandoning a change.
[options="header",cols="1,^1,5"]
|=============================
|Field Name ||Description
|`message` |optional|
Message to be added as review comment to the change when abandoning the
change.
|`notify` |optional|
Notify handling that defines to whom email notifications should be sent after
the change is abandoned. +
Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. +
If not set, the default is `ALL`.
|`notify_details`|optional|
Additional information about whom to notify about the update as a map
of link:user-notify.html#recipient-types[recipient type] to
link:#notify-info[NotifyInfo] entity.
|=============================
[[action-info]]
=== ActionInfo
The `ActionInfo` entity describes a REST API call the client can
make to manipulate a resource. These are frequently implemented by
plugins and may be discovered at runtime.
[options="header",cols="1,^1,5"]
|====================================
|Field Name ||Description
|`method` |optional|
HTTP method to use with the action. Most actions use `POST`, `PUT`
or `DELETE` to cause state changes.
|`label` |optional|
Short title to display to a user describing the action. In the
Gerrit web interface the label is used as the text on the button
presented in the UI.
|`title` |optional|
Longer text to display describing the action. In a web UI this
should be the title attribute of the element, displaying when
the user hovers the mouse.
|`enabled` |optional|
If true the action is permitted at this time and the caller is
likely allowed to execute it. This may change if state is updated
at the server or permissions are modified. Not present if false.
|`enabled_options` |optional|
Optional list of enabled options. +
See the list of suppported options link:#action-options[below].
|====================================
[[action-options]]
==== Action Options
Options that are returned via the `enabled_options` field of
link:#action-info[ActionInfo].
[options="header",cols="1,^1,5"]
|===================================
|REST view |Option |Description
|`rebase` |`rebase`|
Present if the user can rebase the change. +
This is the case for the change owner and users with the
link:access-control.html#category_submit[Submit] or
link:access-control.html#category_rebase[Rebase] permission if they
have the link:access-control.html#category_push[Push] permission.
|`rebase` |`rebase_on_behalf_of_uploader`|
Present if the user can rebase the change on behalf of the uploader. +
This is the case for the change owner and users with the
link:access-control.html#category_submit[Submit] or
link:access-control.html#category_rebase[Rebase] permission.
|`rebase:chain`|`rebase`|
Present if the user can rebase the chain. +
This is the case if the calling user can rebase each change in the
chain.
Rebasing a change is allowed for the change owner and users with the
link:access-control.html#category_submit[Submit] or
link:access-control.html#category_rebase[Rebase] permission if they
have the link:access-control.html#category_push[Push] permission.
|`rebase:chain`|`rebase_on_behalf_of_uploader`|
Present if the user can rebase the chain on behalf of the uploader. +
This is the case if the calling user can rebase each change in the
chain on behalf of the uploader.
Rebasing a change on behalf of the uploader is allowed for the change
owner and users with the link:access-control.html#category_submit[Submit]
or link:access-control.html#category_rebase[Rebase] permission.
|===================================
For all other REST views no options are returned.
[[applypatch-input]]
=== ApplyPatchInput
The `ApplyPatchInput` entity contains information about a patch to apply.
A new commit will be created from the patch, and saved as a new patch set.
[options="header",cols="1,^1,5"]
|=================================
|Field Name ||Description
|`patch` |required|
The patch to be applied. Must be compatible with `git diff` output.
For example, link:#get-patch[Get Patch] output.
The patch must be provided as UTF-8 text, either directly or base64-encoded.
|`allow_conflicts` |optional|
If true, tolerate conflicts and add conflict markers where required.
|=================================
[[applypatchpatchset-input]]
=== ApplyPatchPatchSetInput
The `ApplyPatchPatchSetInput` entity contains information for creating a new patch set from a
given patch.
[options="header",cols="1,^1,5"]
|=================================
|Field Name ||Description
|`patch` |required|
The details of the patch to be applied as a link:#applypatch-input[ApplyPatchInput] entity.
|`commit_message` |optional|
The commit message for the new patch set. If not specified, the latest patch-set message will be
used.
|`base` |optional|
40-hex digit SHA-1 of the commit which will be the parent commit of the newly created patch set.
If set, it must be a merged commit or a change revision on the destination branch.
Otherwise, the target change's branch tip will be used.
|`author` |optional|
The author of the commit to create. Must be an
link:rest-api-accounts.html#account-input[AccountInput] entity with at least
the `name` and `email` fields set.
The caller needs "Forge Author" permission when using this field, unless specifies their own details.
This field does not affect the owner of the change, which will continue to use the identity of the
caller.
|`response_format_options` |optional|
List of link:#query-options[query options] to format the response.
|`amend` |optional|
If true, the revision from the URL will be amended by the patch. This will use the tree of the
revision, apply the patch and create a new commit whose tree is the resulting tree of the operation
and whose parent(s) are the parent(s) of the revision. Cannot be used together with `base`.
|=================================
[[approval-info]]
=== ApprovalInfo
The `ApprovalInfo` entity contains information about an approval from a
user for a label on a change.
`ApprovalInfo` has the same fields as
link:rest-api-accounts.html#account-info[AccountInfo].
In addition `ApprovalInfo` has the following fields:
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`value` |optional|
The vote that the user has given for the label. If present and zero, the
user is permitted to vote on the label. If absent, the user is not
permitted to vote on that label.
|`permitted_voting_range` |optional|
The link:#voting-range-info[VotingRangeInfo] the user is authorized to vote
on that label. If present, the user is permitted to vote on the label
regarding the range values. If absent, the user is not permitted to vote
on that label.
|`date` |optional|
The time and date describing when the approval was made.
|`tag` |optional|
Value of the `tag` field from link:#review-input[ReviewInput] set
while posting the review. Votes/comments that contain `tag` with
'autogenerated:' prefix can be filtered out in the web UI.
NOTE: To apply different tags on different votes/comments multiple
invocations of the REST call are required.
|`post_submit` |not set if `false`|
If true, this vote was made after the change was submitted.
|===========================
[[attention-set-info]]
=== AttentionSetInfo
The `AttentionSetInfo` entity contains details of users that are in
the link:user-attention-set.html[attention set].
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`account` || link:rest-api-accounts.html#account-info[AccountInfo] entity.
|`last_update` || The link:rest-api.html#timestamp[timestamp] of the last update.
|`reason` ||
The reason for adding or removing the user.
If the update was caused by another user, that account is represented by
account ID in reason as `<GERRIT_ACCOUNT_18419>` and the corresponding
link:rest-api-accounts.html#account-info[AccountInfo] can be found in `reason_account` field.
|`reason_account` ||
link:rest-api-accounts.html#account-info[AccountInfo] of the user who caused the update.
|===========================
[[attention-set-input]]
=== AttentionSetInput
The `AttentionSetInput` entity contains details for adding users to the
link:user-attention-set.html[attention set] and removing them from it.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`user` |optional| link:rest-api-accounts.html#account-id[ID]
of the account that should be added to the attention set. For removals,
this field should be empty or the same as the field in the request header.
|`reason` || The reason of for adding or removing the user.
|`notify` |optional|
Notify handling that defines to whom email notifications should be sent
after the change is created. +
Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. +
If not set, the default is `OWNER`.
|`notify_details` |optional|
Additional information about whom to notify about the change creation
as a map of link:user-notify.html#recipient-types[recipient type] to
link:#notify-info[NotifyInfo] entity.
|===========================
[[blame-info]]
=== BlameInfo
The `BlameInfo` entity stores the commit metadata with the row coordinates where
it applies.
[options="header",cols="1,6"]
|===========================
|Field Name | Description
|`author` | The author of the commit.
|`id` | The id of the commit.
|`time` | Commit time.
|`commit_msg` | The commit message.
|`ranges` |
The blame row coordinates as link:#range-info[RangeInfo] entities.
|===========================
[[change-edit-input]]
=== ChangeEditInput
The `ChangeEditInput` entity contains information for restoring a
path within change edit.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`restore_path`|optional|Path to file to restore.
|`old_path` |optional|Old path to file to rename.
|`new_path` |optional|New path to file to rename.
|===========================
[[change-edit-message-input]]
=== ChangeEditMessageInput
The `ChangeEditMessageInput` entity contains information for changing
the commit message within a change edit.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`message` ||New commit message.
|===========================
[[change-edit-identity-input]]
=== ChangeEditIdentityInput
The `ChangeEditIdentityInput` entity contains information for changing
the author or committer identity within a change edit.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`name` |optional|The name of the author/committer. If not specified, the existing name will be used.
|`email` |optional|The email of the author/committer. If not specified, the existing email will be used.
|`type` ||Type of the identity being edited. Must be either `AUTHOR` or `COMMITTER`.
|===========================
[[change-info]]
=== ChangeInfo
The `ChangeInfo` entity contains information about a change.
[options="header",cols="1,^1,5"]
|==================================
|Field Name ||Description
|`id` ||
The ID of the change. The format is "'<project>\~<_number>'".
'project' and '_number' are URL encoded. The callers must not rely on the format.
|`triplet_id` ||
The ID of the change in the format "'<project>\~<branch>~<Change-Id>'",
where 'project' and 'branch' are URL encoded. For 'branch' the
`refs/heads/` prefix is omitted.
|`project` ||The name of the project.
|`branch` ||
The name of the target branch. +
The `refs/heads/` prefix is omitted.
|`topic` |optional|The topic to which this change belongs.
|`attention_set` |optional|
The map that maps link:rest-api-accounts.html#account-id[account IDs]
to link:#attention-set-info[AttentionSetInfo] of that account. Those are all
accounts that are currently in the attention set.
|`removed_from_attention_set` |optional|
The map that maps link:rest-api-accounts.html#account-id[account IDs]
to link:#attention-set-info[AttentionSetInfo] of that account. Those are all
accounts that were in the attention set but were removed. The
link:#attention-set-info[AttentionSetInfo] is the latest and most recent removal
of the account from the attention set.
|`hashtags` |optional|
List of hashtags that are set on the change.
|`custom_keyed_values` |optional|
A map that maps custom keys to custom values that are tied to a specific change,
both in the form of strings. Only set if link:#custom-keyed-values[custom keyed
values] are requested.
|`change_id` ||The Change-Id of the change.
|`subject` ||
The subject of the change (header line of the commit message).
|`status` ||
The status of the change (`NEW`, `MERGED`, `ABANDONED`).
|`created` ||
The link:rest-api.html#timestamp[timestamp] of when the change was
created.
|`updated` ||
The link:rest-api.html#timestamp[timestamp] of when the change was last
updated.
|`submitted` |only set for merged changes|
The link:rest-api.html#timestamp[timestamp] of when the change was
submitted.
|`submitter` |only set for merged changes|
The user who submitted the change, as an
link:rest-api-accounts.html#account-info[ AccountInfo] entity.
|`starred` |not set if `false`|
Whether the calling user has starred this change.
Only set if link:#star[requested].
|`reviewed` |not set if `false`|
Whether the change was reviewed by the calling user.
Only set if link:#reviewed[reviewed] is requested.
|`submit_type` |optional|
The link:config-project-config.html#submit-type[submit type] of the change. +
Not set for merged changes.
|`mergeable` |optional|
Whether the change is mergeable. +
Only set for open changes if
link:config-gerrit.html#change.mergeabilityComputationBehavior[change.mergeabilityComputationBehavior]
is `API_REF_UPDATED_AND_CHANGE_REINDEX`.
|`submittable` |optional|
Whether the change has been approved by the project submit rules. +
Only set if link:#submittable[requested].
|`insertions` ||
Number of inserted lines.
|`deletions` ||
Number of deleted lines.
|`total_comment_count` ||
Total number of inline comments across all patch sets.
|`unresolved_comment_count` ||
Number of unresolved inline comment threads across all patch sets.
|`_number` ||
The change number. (The underscore is just a relict of a prior
attempt to deprecate the change number.)
|`virtual_id_number` ||
The virtual id number is globally unique. For local changes, it is equal to the
`_number` attribute. For imported changes, the original `_number` is processed
through a function designed to prevent conflicts with local change numbers.
Note that its usage is intended solely for Gerrit's internals and UI, and
adoption outside these scenarios is not advised.
|`owner` ||
The owner of the change as an link:rest-api-accounts.html#account-info[
AccountInfo] entity.
|`actions` |optional|
Actions the caller might be able to perform on this revision. The
information is a map of view name to link:#action-info[ActionInfo]
entities.
|`submit_records` ||
List of the link:rest-api-changes.html#submit-record-info[SubmitRecordInfo]
containing the submit records for the change at the latest patchset.
|`requirements` |optional|
List of the link:rest-api-changes.html#requirement[requirements] to be met before this change
can be submitted. This field is deprecated in favour of `submit_requirements`.
|`submit_requirements` |optional|
List of the link:#submit-requirement-result-info[SubmitRequirementResultInfo]
containing the evaluated submit requirements for the change.
Only set if link:#submit-requirements[`SUBMIT_REQUIREMENTS`] is requested.
|`labels` |optional|
The labels of the change as a map that maps the label names to
link:#label-info[LabelInfo] entries. +
Only set if link:#labels[labels] or link:#detailed-labels[detailed
labels] are requested.
|`permitted_labels` |optional|
A map of the permitted labels that maps a label name to the list of
values that are allowed for that label. +
Only set if link:#detailed-labels[detailed labels] are requested.
|`removable_labels` |optional|
A map of the removable labels that maps a label name to the map of
values and reviewers (
link:rest-api-accounts.html#account-info[AccountInfo] entities)
that are allowed to be removed from the change. +
Only set if link:#labels[labels] or
link:#detailed-labels[detailed labels] are requested.
|`removable_reviewers`|optional|
The reviewers that can be removed by the calling user as a list of
link:rest-api-accounts.html#account-info[AccountInfo] entities. +
Only set if link:#labels[labels] or
link:#detailed-labels[detailed labels] are requested.
|`reviewers` |optional|
The reviewers as a map that maps a reviewer state to a list of
link:rest-api-accounts.html#account-info[AccountInfo] entities.
Possible reviewer states are `REVIEWER`, `CC`. +
`REVIEWER`: Users with at least one non-zero vote on the change. +
`CC`: Users that were added to the change, but have not voted. +
Only set if link:#labels[labels] or
link:#detailed-labels[detailed labels] are requested.
|`pending_reviewers` |optional|
Updates to `reviewers` that have been made while the change was in the
WIP state. Only present on WIP changes and only if there are pending
reviewer updates to report. These are reviewers who have not yet been
notified about being added to or removed from the change. +
Only set if link:#labels[labels] or
link:#detailed-labels[detailed labels] are requested.
Possible states are `REVIEWER`, `CC` and `REMOVED`. +
`REVIEWER`: Users with at least one non-zero vote on the change. +
`CC`: Users that were added to the change, but have not voted. +
`REMOVED`: Users that were previously reviewers on the change, but have
been removed.
|`reviewer_updates`|optional|
Updates to reviewers set for the change as
link:#review-update-info[ReviewerUpdateInfo] entities.
Only set if link:#reviewer-updates[reviewer updates] are requested.
|`messages`|optional|
Messages associated with the change as a list of
link:#change-message-info[ChangeMessageInfo] entities. +
Only set if link:#messages[messages] are requested.
|`current_revision_number`||The number of the current patch set of this
change. +
|`current_revision` |optional|
The commit ID of the current patch set of this change. +
Only set if link:#current-revision[the current revision] is requested
or if link:#all-revisions[all revisions] are requested.
|`revisions` |optional|
All patch sets of this change as a map that maps the commit ID of the
patch set to a link:#revision-info[RevisionInfo] entity. +
Only set if link:#current-revision[the current revision] is requested
(in which case it will only contain a key for the current revision) or
if link:#all-revisions[all revisions] are requested.
|`meta_rev_id` |optional|
The SHA-1 of the NoteDb meta ref.
|`tracking_ids` |optional|
A list of link:#tracking-id-info[TrackingIdInfo] entities describing
references to external tracking systems. Only set if
link:#tracking-ids[tracking ids] are requested.
|`_more_changes` |optional, not set if `false`|
Whether the query would deliver more results if not limited. +
Only set on the last change that is returned.
|`problems` |optional|
A list of link:#problem-info[ProblemInfo] entities describing potential
problems with this change. Only set if link:#check[CHECK] is set.
|`is_private` |optional, not set if `false`|
When present, change is marked as private.
|`work_in_progress` |optional, not set if `false`|
When present, change is marked as Work In Progress.
|`has_review_started` |optional, not set if `false`|
When present, change has been marked Ready at some point in time.
|`revert_of` |optional|
The change number of the change that this change reverts.
|`submission_id` |optional|
ID of the submission of this change. Only set if the status is `MERGED`.
This ID is equal to the change number of the change that triggered the
submission. If the change that triggered the submission also has a topic,
it will be "<id>-<topic>" of the change that triggered the submission.
The callers must not rely on the format of the submission ID.
|`cherry_pick_of_change` |optional|
The change number of the change that this change was cherry-picked from.
Only set if the cherry-pick has been done through the Gerrit REST API (and
not if a cherry-picked commit was pushed).
|`cherry_pick_of_patch_set`|optional|
The patchset number of the change that this change was cherry-picked from.
Only set if the cherry-pick has been done through the Gerrit REST API (and
not if a cherry-picked commit was pushed).
|`contains_git_conflicts` |optional, not set if `false`|
Whether the change contains conflicts. +
If `true`, some of the file contents of the change contain git conflict
markers to indicate the conflicts. +
Only set if this change info is returned in response to a request that
creates a new change or patch set and conflicts are allowed. In
particular this field is only populated if the change info is returned
by one of the following REST endpoints:link:#apply-patch[Apply Patch],
link:#create-change[Create Change],
link:#create-merge-patch-set-for-change[Create Merge Patch Set For Change],
link:#cherry-pick[Cherry Pick Revision],
link:rest-api-project.html#cherry-pick-commit[Cherry Pick Commit],
link:#rebase-change[Rebase Change]
|==================================
[[change-input]]
=== ChangeInput
The `ChangeInput` entity contains information about creating a new change.
[options="header",cols="1,^1,5"]
|==================================
|Field Name ||Description
|`project` ||The name of the project.
|`branch` ||
The name of the target branch. +
The `refs/heads/` prefix is omitted.
|`subject` ||
The commit message of the change. Comment lines (beginning with `#`)
will be removed. If the commit message contains a Change-Id (as a
"Change-Id: I..." footer) that Change-Id will be used for the newly
created changed. If a change with this Change-Id already exists for
same repository and branch, the request is rejected since Change-Ids
must be unique per repository and branch. If the commit message doesn't
contain a Change-Id, a newly generated Change-Id is automatically
inserted into the commit message.
|`topic` |optional|The topic to which this change belongs.
Topic can't contain quotation marks.
|`status` |optional, default to `NEW`|
The status of the change (only `NEW` accepted here).
|`is_private` |optional, default to `false`|
Whether the new change should be marked as private.
|`work_in_progress` |optional, default to `false`|
Whether the new change should be set to work in progress.
|`base_change` |optional|
A link:#change-id[\{change-id\}] that identifies the base change for a create
change operation. +
Mutually exclusive with `base_commit`. +
If neither `base_commit` nor `base_change` are set, the target branch tip will
be used as the parent commit.
|`base_commit` |optional|
A 40-digit hex SHA-1 of the commit which will be the parent commit of the newly
created change. If set, it must be a merged commit on the destination branch. +
Mutually exclusive with `base_change`. +
If neither `base_commit` nor `base_change` are set, the target branch tip will
be used as the parent commit.
|`new_branch` |optional, default to `false`|
Allow creating a new branch when set to `true`. Using this option is
only possible for non-merge commits (if the `merge` field is not set).
|`validation_options` |optional|
Map with key-value pairs that are forwarded as options to the commit validation
listeners (e.g. can be used to skip certain validations). Which validation
options are supported depends on the installed commit validation listeners.
Gerrit core doesn't support any validation options, but commit validation
listeners that are implemented in plugins may. Please refer to the
documentation of the installed plugins to learn whether they support validation
options. Unknown validation options are silently ignored.
|`custom_keyed_values`|optional|Custom keyed values as a
map from custom keys to values.
|`merge` |optional|
The detail of a merge commit as a link:#merge-input[MergeInput] entity.
If set, the target branch (see `branch` field) must exist (it is not
possible to create it automatically by setting the `new_branch` field
to `true`.
|`patch` |optional|
The detail of a patch to be applied as an link:#applypatch-input[ApplyPatchInput] entity.
|`author` |optional|
The author of the commit to create. Must be an
link:rest-api-accounts.html#account-input[AccountInput] entity with at least
the `name` and `email` fields set.
The caller needs "Forge Author" permission when using this field.
This field does not affect the owner of the change, which will
continue to use the identity of the caller.
|`notify` |optional|
Notify handling that defines to whom email notifications should be sent
after the change is created. +
Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. +
If not set, the default is `ALL`.
|`notify_details` |optional|
Additional information about whom to notify about the change creation
as a map of link:user-notify.html#recipient-types[recipient type] to
link:#notify-info[NotifyInfo] entity.
|`response_format_options` |optional|
List of link:#query-options[query options] to format the response.
|==================================
[[change-message-info]]
=== ChangeMessageInfo
The `ChangeMessageInfo` entity contains information about a message
attached to a change.
[options="header",cols="1,^1,5"]
|==================================
|Field Name ||Description
|`id` ||The ID of the message.
|`author` |optional|
Author of the message as an
link:rest-api-accounts.html#account-info[AccountInfo] entity. +
Unset if written by the Gerrit system.
|`real_author` |optional|
Real author of the message as an
link:rest-api-accounts.html#account-info[AccountInfo] entity. +
Only set if the message was posted on behalf of another user.
|`date` ||
The link:rest-api.html#timestamp[timestamp] this message was posted.
|`message` ||
The text left by the user or Gerrit system. Accounts are served as account IDs
inlined in the text as `<GERRIT_ACCOUNT_18419>`.
All accounts, used in message, can be found in `accounts_in_message`
field.
|`accounts_in_message` ||
link:rest-api-accounts.html#account-info[AccountInfo] list, used in `message`.
|`tag` |optional|
Value of the `tag` field from link:#review-input[ReviewInput] set
while posting the review. Votes/comments that contain `tag` with
'autogenerated:' prefix can be filtered out in the web UI.
NOTE: To apply different tags on different votes/comments multiple
invocations of the REST call are required.
|`_revision_number` |optional|
Which patchset (if any) generated this message.
|==================================
[[cherrypick-input]]
=== CherryPickInput
The `CherryPickInput` entity contains information for cherry-picking a change to a new branch.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`message` |optional|
Commit message for the cherry-pick change. If not set, the commit message of
the cherry-picked commit is used.
|`destination` ||Destination branch
|`base` |optional|
40-hex digit SHA-1 of the commit which will be the parent commit of the newly created change.
If set, it must be a merged commit or a change revision on the destination branch.
|`parent` |optional, defaults to 1|
Number of the parent relative to which the cherry-pick should be considered.
|`notify` |optional|
Notify handling that defines to whom email notifications should be sent
after the cherry-pick. +
Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. +
If not set, the default is `ALL`.
|`notify_details` |optional|
Additional information about whom to notify about the update as a map
of link:user-notify.html#recipient-types[recipient type] to
link:#notify-info[NotifyInfo] entity.
|`keep_reviewers` |optional, defaults to false|
If `true`, carries reviewers and ccs over from original change to newly created one.
|`allow_conflicts` |optional, defaults to false|
If `true`, the cherry-pick uses content merge and succeeds also if
there are conflicts. If there are conflicts the file contents of the
created change contain git conflict markers to indicate the conflicts.
Callers can find out if there were conflicts by checking the
`contains_git_conflicts` field in the link:#change-info[ChangeInfo]. If
there are conflicts the cherry-pick change is marked as
work-in-progress.
|`topic` |optional|
The topic of the created cherry-picked change. If not set, the default depends
on the source. If the source is a change with a topic, the resulting topic
of the cherry-picked change will be {source_change_topic}-{destination_branch}.
Otherwise, if the source change has no topic, or the source is a commit,
the created change will have no topic.
If the change already exists, the topic will not change if not set. If set, the
topic will be overridden.
|`allow_empty` |optional, defaults to false|
If `true`, the cherry-pick succeeds also if the created commit will be empty.
If `false`, a cherry-pick that would create an empty commit fails without creating
the commit.
|`committer_email`|optional|
Cherry-pick is committed using this email address. Only the registered emails
of the calling user are considered valid. Defaults to source commit's committer
email if it is a registered email of the calling user, else defaults to calling
user's preferred email.
|`validation_options`|optional|
Map with key-value pairs that are forwarded as options to the commit validation
listeners (e.g. can be used to skip certain validations). Which validation
options are supported depends on the installed commit validation listeners.
Gerrit core doesn't support any validation options, but commit validation
listeners that are implemented in plugins may. Please refer to the
documentation of the installed plugins to learn whether they support validation
options. Unknown validation options are silently ignored.
|===========================
[[comment-info]]
=== CommentInfo
The `CommentInfo` entity contains information about an inline comment.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`patch_set` |optional|
The patch set number for the comment; only set in contexts where +
comments may be returned for multiple patch sets.
|`id` ||The URL encoded UUID of the comment.
|`path` |optional|
link:#file-id[The file path] for which the inline comment was done. +
Not set if returned in a map where the key is the file path.
|`side` |optional|
The side on which the comment was added. +
Allowed values are `REVISION` and `PARENT`. +
If not set, the default is `REVISION`.
|`parent` |optional|
The 1-based parent number. Used only for merge commits when `side == PARENT`.
When not set the comment is for the auto-merge tree.
|`line` |optional|
The number of the line for which the comment was done. +
If range is set, this equals the end line of the range. +
If neither line nor range is set, it's a file comment.
|`range` |optional|
The range of the comment as a link:#comment-range[CommentRange]
entity.
|`in_reply_to` |optional|
The URL encoded UUID of the comment to which this comment is a reply.
|`message` |optional|The comment message.
|`updated` ||
The link:rest-api.html#timestamp[timestamp] of when this comment was
written.
|`author` |optional|
The author of the message as an
link:rest-api-accounts.html#account-info[AccountInfo] entity. +
Unset for draft comments, assumed to be the calling user.
|`tag` |optional|
Value of the `tag` field from link:#review-input[ReviewInput] set
while posting the review.
NOTE: To apply different tags on different votes/comments multiple
invocations of the REST call are required.
|`unresolved` |optional|
Whether or not the comment must be addressed by the user. The state of
resolution of a comment thread is stored in the last comment in that thread
chronologically.
|`change_message_id` |optional|
Available with the link:#list-change-comments[list change comments] endpoint.
Contains the link:rest-api-changes.html#change-message-info[id] of the change
message that this comment is linked to.
|`commit_id` |optional|
Hex commit SHA-1 (40 characters string) of the commit of the patchset to which
this comment applies.
|`context_lines` |optional|
A list of link:#context-line[ContextLine] containing the lines of the source
file where the comment was written. Available only if the "enable-context"
parameter (see link:#list-change-comments[List Change Comments]) is set.
|`source_content_type` |optional|
Mime type of the file where the comment is written. Available only if the
"enable-context" parameter (see link:#list-change-comments[List Change Comments])
is set.
|`fix_suggestions`|optional|Suggested fixes for this comment as a list of
<<fix-suggestion-info,FixSuggestionInfo>> entities.
|===========================
[[comment-input]]
=== CommentInput
The `CommentInput` entity contains information for creating an inline
comment.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`id` |optional|
The URL encoded UUID of the comment if an existing draft comment should
be updated.
|`path` |optional|
link:#file-id[The file path] for which the inline comment should be added. +
Doesn't need to be set if contained in a map where the key is the file
path.
|`side` |optional|
The side on which the comment should be added. +
Allowed values are `REVISION` and `PARENT`. +
If not set, the default is `REVISION`.
|`line` |optional|
The number of the line for which the comment should be added. +
`0` if it is a file comment. +
If neither line nor range is set, a file comment is added. +
If range is set, this value is ignored in favor of the `end_line` of the range.
|`range` |optional|
The range of the comment as a link:#comment-range[CommentRange]
entity.
|`in_reply_to` |optional|
The URL encoded UUID of the comment to which this comment is a reply.
|`updated` |optional|
The link:rest-api.html#timestamp[timestamp] of this comment. +
Accepted but ignored.
|`message` |optional|
The comment message. +
If not set and an existing draft comment is updated, the existing draft
comment is deleted.
|`tag` |optional, drafts only|
Value of the `tag` field. Only allowed on link:#create-draft[draft comment] +
inputs; for published comments, use the `tag` field in +
link:#review-input[ReviewInput]. Votes/comments that contain `tag` with
'autogenerated:' prefix can be filtered out in the web UI.
|`unresolved` |optional|
Whether or not the comment must be addressed by the user. This value will
default to false if the comment is an orphan, or the value of the `in_reply_to`
comment if it is supplied.
|`fix_suggestions`|optional|Suggested fixes for this comment as a list of
<<fix-suggestion-info,FixSuggestionInfo>> entities.
|===========================
[[comment-range]]
=== CommentRange
The `CommentRange` entity describes the range of an inline comment.
The comment range is a range from the start position, specified by `start_line`
and `start_character`, to the end position, specified by `end_line` and
`end_character`. The start position is *inclusive* and the end position is
*exclusive*.
So, a range over part of a line will have `start_line` equal to
`end_line`; however a range with `end_line` set to 5 and `end_character` equal
to 0 will not include any characters on line 5,
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`start_line` ||The start line number of the range. (1-based)
|`start_character` ||The character position in the start line. (0-based)
|`end_line` ||The end line number of the range. (1-based)
|`end_character` ||The character position in the end line. (0-based)
|===========================
[[context-line]]
=== ContextLine
The `ContextLine` entity contains the line number and line text of a single
line of the source file content.
[options="header",cols="1,6"]
|===========================
|Field Name |Description
|`line_number` |The line number of the source line.
|`context_line` |String containing the line text.
|===========================
[[commit-info]]
=== CommitInfo
The `CommitInfo` entity contains information about a commit.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`commit` |Optional|
The commit ID. Not set if included in a link:#revision-info[
RevisionInfo] entity that is contained in a map which has the commit ID
as key.
|`parents` ||
The parent commits of this commit as a list of
link:#commit-info[CommitInfo] entities. In each parent
only the `commit` and `subject` fields are populated.
|`author` ||The author of the commit as a
link:#git-person-info[GitPersonInfo] entity.
|`committer` ||The committer of the commit as a
link:#git-person-info[GitPersonInfo] entity.
|`subject` ||
The subject of the commit (header line of the commit message).
|`message` ||The commit message.
|`web_links` |optional|
Links to the patch set in external sites as a list of
link:#web-link-info[WebLinkInfo] entities.
|`resolve_conflicts_web_links` |optional|
Links to the commit in external sites for resolving conflicts as a list of
link:#web-link-info[WebLinkInfo] entities.
|===========================
[[commit-message-info]]
=== CommitMessageInfo
The `CommitMessageInfo` entity contains information about the commit
message of a change.
[options="header",cols="1,6"]
|============================
|Field Name |Description
|`subject` |The subject of the change (first line of the commit
message).
|`full_message` |Full commit message of the change.
|`footers` |The footers from the commit message as a map of
key-value pairs. If there are multiple footers with the same key, only the last
footer with that key is returned.
|============================
[[commit-message-input]]
=== CommitMessageInput
The `CommitMessageInput` entity contains information for changing
the commit message of a change.
[options="header",cols="1,^1,5"]
|=============================
|Field Name ||Description
|`message` ||New commit message.
|`committer_email`|optional|
New message is committed using this email address. Only the
registered emails of the calling user are considered valid.
|`notify` |optional|
Notify handling that defines to whom email notifications should be sent
after the commit message was updated. +
Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. +
If not set, the default is `OWNER` for WIP changes and `ALL` otherwise.
|`notify_details`|optional|
Additional information about whom to notify about the update as a map
of link:user-notify.html#recipient-types[recipient type] to
link:#notify-info[NotifyInfo] entity.
|=============================
[[delete-change-message-input]]
=== DeleteChangeMessageInput
The `DeleteChangeMessageInput` entity contains the options for deleting a change message.
[options="header",cols="1,^1,5"]
|=============================
|Field Name ||Description
|`reason` |optional|
The reason why the change message should be deleted. +
If set, the change message will be replaced with
"Change message removed by: `name`\nReason: `reason`",
or just "Change message removed by: `name`." if not set.
|=============================
[[delete-comment-input]]
=== DeleteCommentInput
The `DeleteCommentInput` entity contains the option for deleting a comment.
[options="header",cols="1,^1,5"]
|=============================
|Field Name ||Description
|`reason` |optional|
The reason why the comment should be deleted. +
If set, the comment's message will be replaced with
"Comment removed by: `name`; Reason: `reason`",
or just "Comment removed by: `name`." if not set.
|=============================
[[delete-reviewer-input]]
=== DeleteReviewerInput
The `DeleteReviewerInput` entity contains options for the deletion of a
reviewer.
[options="header",cols="1,^1,5"]
|=============================
|Field Name ||Description
|`notify` |optional|
Notify handling that defines to whom email notifications should be sent
after the reviewer is deleted. +
Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. +
If not set, the default is `ALL`.
|`notify_details`|optional|
Additional information about whom to notify about the update as a map
of link:user-notify.html#recipient-types[recipient type] to
link:#notify-info[NotifyInfo] entity.
|=============================
[[delete-vote-input]]
=== DeleteVoteInput
The `DeleteVoteInput` entity contains options for the deletion of a
vote.
[options="header",cols="1,^1,5"]
|=============================
|Field Name ||Description
|`label` |optional|
The label for which the vote should be deleted. +
If set, must match the label in the URL.
|`notify` |optional|
Notify handling that defines to whom email notifications should be sent
after the vote is deleted. +
Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. +
If not set, the default is `ALL`.
|`notify_details`|optional|
Additional information about whom to notify about the update as a map
of link:user-notify.html#recipient-types[recipient type] to
link:#notify-info[NotifyInfo] entity.
|`ignore_automatic_attention_set_rules`|optional|
If set to true, ignore all automatic attention set rules described in the
link:user-attention-set.html[attention set]. When not set, the default is false.
|`reason` |optional|
The reason why this vote is deleted. Will +
go into the change message.
|=============================
[[description-input]]
=== DescriptionInput
The `DescriptionInput` entity contains information for setting a description.
[options="header",cols="1,6"]
|===========================
|Field Name |Description
|`description` |The description text.
|===========================
[[diff-content]]
=== DiffContent
The `DiffContent` entity contains information about the content differences
in a file.
[options="header",cols="1,^1,5"]
|==========================
|Field Name ||Description
|`a` |optional|Content only in the file on side A (deleted in B).
|`b` |optional|Content only in the file on side B (added in B).
|`ab` |optional|Content in the file on both sides (unchanged).
|`edit_a` |only present when the `intraline` parameter is set and the
DiffContent is a replace, i.e. both `a` and `b` are present|
Text sections deleted from side A as a
link:#diff-intraline-info[DiffIntralineInfo] entity.
|`edit_b` |only present when the `intraline` parameter is set and the
DiffContent is a replace, i.e. both `a` and `b` are present|
Text sections inserted in side B as a
link:#diff-intraline-info[DiffIntralineInfo] entity.
|`due_to_rebase`|not set if `false`|Indicates whether this entry was introduced by a
rebase.
|`due_to_move`|not set if `false`|Indicates whether this entry was introduced by a
move operation.
|`skip` |optional|count of lines skipped on both sides when the file is
too large to include all common lines.
|`common` |optional|Set to `true` if the region is common according
to the requested ignore-whitespace parameter, but a and b contain
differing amounts of whitespace. When present and true a and b are
used instead of ab.
|==========================
[[diff-file-meta-info]]
=== DiffFileMetaInfo
The `DiffFileMetaInfo` entity contains meta information about a file diff.
[options="header",cols="1,^1,5"]
|==========================
|Field Name ||Description
|`name` ||The name of the file.
|`content_type`||The content type of the file. For the commit message and merge
list the value is `text/x-gerrit-commit-message` and `text/x-gerrit-merge-list`
respectively. For git links the value is `x-git/gitlink`. For symlinks the value
is `x-git/symlink`. For regular files the value is the file mime type (e.g.
`text/x-java`, `text/x-c++src`, etc...).
|`lines` ||The total number of lines in the file.
|`web_links` |optional|
Links to the file in external sites as a list of
link:rest-api-changes.html#web-link-info[WebLinkInfo] entries.
|==========================
[[diff-info]]
=== DiffInfo
The `DiffInfo` entity contains information about the diff of a file
in a revision.
If the link:#weblinks-only[weblinks-only] parameter is specified, only
the `web_links` field is set.
[options="header",cols="1,^1,5"]
|==========================
|Field Name ||Description
|`meta_a` |not present when the file is added|
Meta information about the file on side A as a
link:#diff-file-meta-info[DiffFileMetaInfo] entity.
|`meta_b` |not present when the file is deleted|
Meta information about the file on side B as a
link:#diff-file-meta-info[DiffFileMetaInfo] entity.
|`change_type` ||The type of change (`ADDED`, `MODIFIED`, `DELETED`, `RENAMED`
`COPIED`, `REWRITE`).
|`intraline_status`|only set when the `intraline` parameter was specified in the request|
Intraline status (`OK`, `ERROR`, `TIMEOUT`).
|`diff_header` ||A list of strings representing the patch set diff header.
|`content` ||The content differences in the file as a list of
link:#diff-content[DiffContent] entities.
|`web_links` |optional|
Links to the file diff in external sites as a list of
link:rest-api-changes.html#diff-web-link-info[DiffWebLinkInfo] entries.
|`edit_web_links` |optional|
Links to edit the file in external sites as a list of
link:rest-api-changes.html#web-link-info[WebLinkInfo] entries.
|`binary` |not set if `false`|Whether the file is binary.
|==========================
[[diff-intraline-info]]
=== DiffIntralineInfo
The `DiffIntralineInfo` entity contains information about intraline edits in a
file.
The information consists of a list of `<skip length, edit length>` pairs, where
the skip length is the number of characters between the end of the previous edit
and the start of this edit, and the edit length is the number of edited characters
following the skip. The start of the edits is from the beginning of the related
diff content lines. If the list is empty, the entire DiffContent should be considered
as unedited.
Note that the implied newline character at the end of each line is included in
the length calculation, and thus it is possible for the edits to span newlines.
[[diff-web-link-info]]
=== DiffWebLinkInfo
The `DiffWebLinkInfo` entity extends link:#web-link-info[WebLinkInfo] and
describes a link on a diff screen to an external site.
[options="header",cols="1,^1,5"]
|=======================
|Field Name||Description
|`name` ||See link:#web-link-info[WebLinkInfo]
|`tooltip` |optional|See link:#web-link-info[WebLinkInfo]
|`url` ||See link:#web-link-info[WebLinkInfo]
|`image_url`|optional|See link:#web-link-info[WebLinkInfo]
|show_on_side_by_side_diff_view||
Whether the web link should be shown on the side-by-side diff screen.
|show_on_unified_diff_view||
Whether the web link should be shown on the unified diff screen.
|=======================
[[apply-provided-fix-input]]
=== ApplyProvidedFixInput
The `ApplyProvidedFixInput` entity contains the fixes to be applied on a review.
[[custom-keyed-values-input]]
=== CustomKeyedValuesInput
The `CustomKeyedValuesInput` entity contains information about custom keyed values
to add to, and/or remove from, a change.
[options="header",cols="1,^1,5"]
|=======================
|Field Name||Description
|`add` |optional|The map of custom keyed values to be added to the change.
|`remove` |optional|The list of custom keys to be removed from the change.
|=======================
[options="header",cols="1,6"]
|=======================
|Field Name |Description
|`fix_replacement_infos` |A list of <<fix-replacement-info,FixReplacementInfo>>.
|=======================
[[edit-file-info]]
=== EditFileInfo
The `EditFileInfo` entity contains additional information
of a file within a change edit.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`web_links` |optional|
Links to the diff info in external sites as a list of
link:#web-link-info[WebLinkInfo] entities.
|===========================
[[edit-info]]
=== EditInfo
The `EditInfo` entity contains information about a change edit.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`commit` ||The commit of change edit as
link:#commit-info[CommitInfo] entity.
|`base_patch_set_number`||The patch set number of the patch set the change edit is based on.
|`base_revision` ||The revision of the patch set the change edit is based on.
|`ref` ||The ref of the change edit.
|`fetch` |optional|
Information about how to fetch this patch set. The fetch information is
provided as a map that maps the protocol name ("`git`", "`http`",
"`ssh`") to link:#fetch-info[FetchInfo] entities.
|`files` |optional|
The files of the change edit as a map that maps the file names to
link:#file-info[FileInfo] entities.
|===========================
[[fetch-info]]
=== FetchInfo
The `FetchInfo` entity contains information about how to fetch a patch
set via a certain protocol.
[options="header",cols="1,^1,5"]
|==========================
|Field Name ||Description
|`url` ||The URL of the project.
|`ref` ||The ref of the patch set.
|`commands` |optional|
The download commands for this patch set as a map that maps the command
names to the commands. +
Only set if link:#download-commands[download commands] are requested.
|==========================
[[file-info]]
=== FileInfo
The `FileInfo` entity contains information about a file in a patch set.
[options="header",cols="1,^1,5"]
|=============================
|Field Name ||Description
|`status` |optional|
The status of the file ("`A`"=Added, "`D`"=Deleted, "`R`"=Renamed,
"`C`"=Copied, "`W`"=Rewritten). +
Not set if the file was Modified ("`M`").
|`binary` |not set if `false`|Whether the file is binary.
|`old_path` |optional|
The old file path. +
Only set if the file was renamed or copied.
|`lines_inserted`|optional|
Number of inserted lines. +
Not set for binary files or if no lines were inserted. +
An empty last line is not included in the count and hence this number can
differ by one from details provided in <<diff-info,DiffInfo>>.
|`lines_deleted` |optional|
Number of deleted lines. +
Not set for binary files or if no lines were deleted. +
An empty last line is not included in the count and hence this number can
differ by one from details provided in <<diff-info,DiffInfo>>.
|`size_delta` ||
Number of bytes by which the file size increased/decreased.
|`size` || File size in bytes.
|`old_mode` |optional|File mode in octal (e.g. 100644) at the old commit.
The first three digits indicate the file type and the last three digits contain
the file permission bits. For added files, this field will not be present.
|`new_mode` |optional|File mode in octal (e.g. 100644) at the new commit.
The first three digits indicate the file type and the last three digits contain
the file permission bits. For deleted files, this field will not be present.
|=============================
[[fix-input]]
=== FixInput
The `FixInput` entity contains options for fixing commits using the
link:#fix-change[fix change] endpoint.
[options="header",cols="1,6"]
|==========================
|Field Name |Description
|`delete_patch_set_if_commit_missing`|If true, delete patch sets from the
database if they refer to missing commit options.
|`expect_merged_as` |If set, check that the change is
merged into the destination branch as this exact SHA-1. If not, insert
a new patch set referring to this commit.
|==========================
[[fix-suggestion-info]]
=== FixSuggestionInfo
The `FixSuggestionInfo` entity represents a suggested fix.
[options="header",cols="1,^1,5"]
|==========================
|Field Name ||Description
|`fix_id` |generated, don't set|The <<fix-id,UUID>> of the suggested
fix. It will be generated automatically and hence will be ignored if it's set
for input objects.
|`description` ||A description of the suggested fix.
|`replacements` ||A list of <<fix-replacement-info,FixReplacementInfo>>
entities indicating how the content of one or several files should be modified.
Within a file, they should refer to non-overlapping regions.
|==========================
[[fix-replacement-info]]
=== FixReplacementInfo
The `FixReplacementInfo` entity describes how the content of a file should be
replaced by another content.
[options="header",cols="1,6"]
|==========================
|Field Name |Description
|`path` |The path of the file which should be modified. Any file in
the repository may be modified. The commit message can be modified via the
magic file `/COMMIT_MSG` though only the part below the generated header of
that magic file can be modified. References to the header lines will result in
errors when the fix is applied.
|`range` |A <<comment-range,CommentRange>> indicating which content
of the file should be replaced. Lines in the file are assumed to be separated
by the line feed character.
|`replacement` |The content which should be used instead of the current one.
|==========================
[[git-person-info]]
=== GitPersonInfo
The `GitPersonInfo` entity contains information about the
author/committer of a commit.
[options="header",cols="1,6"]
|==========================
|Field Name |Description
|`name` |The name of the author/committer.
|`email` |The email address of the author/committer.
|`date` |The link:rest-api.html#timestamp[timestamp] of when
this identity was constructed.
|`tz` |The timezone offset from UTC of when this identity was
constructed.
|==========================
[[group-base-info]]
=== GroupBaseInfo
The `GroupBaseInfo` entity contains base information about the group.
[options="header",cols="1,6"]
|==========================
|Field Name |Description
|`id` |The UUID of the group.
|`name` |The name of the group.
|==========================
[[hashtags-input]]
=== HashtagsInput
The `HashtagsInput` entity contains information about hashtags to add to,
and/or remove from, a change.
[options="header",cols="1,^1,5"]
|=======================
|Field Name||Description
|`add` |optional|The list of hashtags to be added to the change.
|`remove` |optional|The list of hashtags to be removed from the change.
|=======================
[[included-in-info]]
=== IncludedInInfo
The `IncludedInInfo` entity contains information about the branches a
change was merged into and tags it was tagged with. The branch or tag
must have 'refs/head/' or 'refs/tags/' prefix respectively.
[options="header",cols="1,^1,5"]
|=======================
|Field Name||Description
|`branches`||The list of branches this change was merged into.
Each branch is listed without the 'refs/head/' prefix.
|`tags` ||The list of tags this change was tagged with.
Each tag is listed without the 'refs/tags/' prefix.
|`external`|optional|A map that maps a name to a list of external
systems that include this change, e.g. a list of servers on which this
change is deployed.
|=======================
[[label-info]]
=== LabelInfo
The `LabelInfo` entity contains information about a label on a change, always
corresponding to the current patch set.
There are two options that control the contents of `LabelInfo`:
link:#labels[`LABELS`] and link:#detailed-labels[`DETAILED_LABELS`].
* Using `LABELS` will skip the `all.permitted_voting_range` attribute.
* Using `DETAILED_LABELS` will include the `all.permitted_voting_range`
attribute.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`optional` |not set if `false`|
Whether the label is optional. Optional means the label may be set, but
it's neither necessary for submission nor does it block submission if
set.
|`description` |optional| The description of the label.
|`approved` |optional|One user who approved this label on the change
(voted the maximum value) as an
link:rest-api-accounts.html#account-info[AccountInfo] entity.
|`rejected` |optional|One user who rejected this label on the change
(voted the minimum value) as an
link:rest-api-accounts.html#account-info[AccountInfo] entity.
|`recommended` |optional|One user who recommended this label on the
change (voted positively, but not the maximum value) as an
link:rest-api-accounts.html#account-info[AccountInfo] entity.
|`disliked` |optional|One user who disliked this label on the change
(voted negatively, but not the minimum value) as an
link:rest-api-accounts.html#account-info[AccountInfo] entity.
|`blocking` |optional|If `true`, the label blocks submit operation.
If not set, the default is false.
|`value` |optional|The voting value of the user who
recommended/disliked this label on the change if it is not
"`+1`"/"`-1`".
|`default_value`|optional|The default voting value for the label.
This value may be outside the range specified in permitted_labels.
|votes|optional|A list of integers containing the vote values applied to this
label at the latest patchset.
|`all` |optional|List of all approvals for this label as a list
of link:#approval-info[ApprovalInfo] entities. Items in this list may
not represent actual votes cast by users; if a user votes on any label,
a corresponding ApprovalInfo will appear in this list for all labels. +
The `permitted_voting_range` attribute is only set if the `DETAILED_LABELS`
option is requested.
|`values` |optional|A map of all values that are allowed for this
label. The map maps the values ("`-2`", "`-1`", " `0`", "`+1`", "`+2`")
to the value descriptions.
|===========================
[[mergeable-info]]
=== MergeableInfo
The `MergeableInfo` entity contains information about the mergeability of a
change.
[options="header",cols="1,^1,5"]
|============================
|Field Name ||Description
|`submit_type` ||
Submit type used for this change, can be `MERGE_IF_NECESSARY`,
`FAST_FORWARD_ONLY`, `REBASE_IF_NECESSARY`, `REBASE_ALWAYS`, `MERGE_ALWAYS` or
`CHERRY_PICK`.
|`strategy` |optional|
The strategy of the merge, can be `recursive`, `resolve`,
`simple-two-way-in-core`, `ours` or `theirs`.
|`mergeable` ||
`true` if this change is cleanly mergeable, `false` otherwise
|`commit_merged` |optional|
`true` if this change is already merged, `false` otherwise
|`content_merged`|optional|
`true` if the content of this change is already merged, `false` otherwise
|`conflicts` |optional|
A list of paths with conflicts
|`mergeable_into`|optional|
A list of other branch names where this change could merge cleanly
|============================
[[merge-input]]
=== MergeInput
The `MergeInput` entity contains information about the merge
[options="header",cols="1,^1,5"]
|==============================
|Field Name ||Description
|`source` ||
The source to merge from, e.g. a complete or abbreviated commit SHA-1,
a complete reference name, a short reference name under `refs/heads`, `refs/tags`,
or `refs/remotes` namespace, etc.
|`source_branch` |optional|
A branch from which `source` is reachable. If specified,
`source` is checked for visibility and reachability against only this
branch. This speeds up the operation, especially for large repos with
many branches.
|`strategy` |optional|
The strategy of the merge, can be `recursive`, `resolve`,
`simple-two-way-in-core`, `ours` or `theirs`, default will use project settings.
|`allow_conflicts`|optional, defaults to false|
If `true`, creating the merge succeeds also if there are conflicts. +
If there are conflicts the file contents of the created change contain
git conflict markers to indicate the conflicts. +
Callers can find out whether there were conflicts by checking the
`contains_git_conflicts` field in the link:#change-info[ChangeInfo]. +
If there are conflicts the change is marked as work-in-progress. +
This option is not supported for all merge strategies (e.g. it's
supported for `recursive` and `resolve`, but not for
`simple-two-way-in-core`).
|==============================
[[merge-patch-set-input]]
=== MergePatchSetInput
The `MergePatchSetInput` entity contains information about updating a new
change by creating a new merge commit.
[options="header",cols="1,^1,5"]
|==================================
|Field Name ||Description
|`subject` |optional|
The new subject for the change, if not specified, will reuse the current patch
set's subject
|`inherit_parent` |optional, default to `false`|
Use the current patch set's first parent as the merge tip when set to `true`.
|`base_change` |optional|
A link:#change-id[\{change-id\}] that identifies a change. When `inherit_parent`
is `false`, the merge tip will be the current patch set of the `base_change` if
it's set. Otherwise, the current branch tip of the destination branch will be used.
|`merge` ||
The detail of the source commit for merge as a link:#merge-input[MergeInput]
entity.
|`author` |optional|
The author of the commit to create. Must be an
link:rest-api-accounts.html#account-input[AccountInput] entity with at least
the `name` and `email` fields set.
The caller needs "Forge Author" permission when using this field.
This field does not affect the owner or the committer of the change, which will
continue to use the identity of the caller.
|`validation_options` |optional|
Map with key-value pairs that are forwarded as options to the commit validation
listeners (e.g. can be used to skip certain validations). Which validation
options are supported depends on the installed commit validation listeners.
Gerrit core doesn't support any validation options, but commit validation
listeners that are implemented in plugins may. Please refer to the
documentation of the installed plugins to learn whether they support validation
options. Unknown validation options are silently ignored.
|==================================
[[move-input]]
=== MoveInput
The `MoveInput` entity contains information for moving a change to a new branch.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`destination_branch`||Destination branch
|`message` |optional|
A message to be posted in this change's comments
|`keep_all_votes` |optional, defaults to false|
By default, only veto votes that are blocking the change from submission are moved to
the destination branch. Using this option is only allowed for administrators,
because it can affect the submission behaviour of the change (depending on the label access
configuration and submissions rules).
|===========================
[[notify-info]]
=== NotifyInfo
The `NotifyInfo` entity contains detailed information about who should
be notified about an update. These notifications are sent out even if a
`notify` option in the request input disables normal notifications.
`NotifyInfo` entities are normally contained in a `notify_details` map
in the request input where the key is the
link:user-notify.html#recipient-types[recipient type].
[options="header",cols="1,^1,5"]
|=======================
|Field Name||Description
|`accounts`|optional|
A list of link:rest-api-accounts.html#account-id[account IDs] that
identify the accounts that should be should be notified.
|=======================
[[parent-info]]
=== ParentInfo
The `ParentInfo` entity contains information about the parent commit of a
patch-set.
[options="header",cols="1,^1,5"]
|=======================
|Field Name||Description
|`branch_name` |optional|Name of the target branch into which the parent commit
is merged.
|`commit_id` |optional|The commit SHA-1 of the parent commit, or null if the
current commit is root.
|`is_merged_in_target_branch` |optional, default to false| Set to true if the
parent commit is merged into the target branch.
|`change_id` |optional| If the parent commit is a patch-set of another gerrit
change, this field will hold the change ID of the parent change. Otherwise,
will be null.
|`change_number` |optional|If the parent commit is a patch-set of another gerrit
change, this field will hold the change number of the parent change. Otherwise,
will be null.
|`patch_set_number` |optional|If the parent commit is a patch-set of another gerrit
change, this field will hold the patch-set number of the parent change. Otherwise,
will be null.
|`change_status` |optional|If the parent commit is a patch-set of another gerrit
change, this field will hold the change status of the parent change. Otherwise,
will be null.
|=======================
[[private-input]]
=== PrivateInput
The `PrivateInput` entity contains information for changing the private
flag on a change.
[options="header",cols="1,^1,5"]
|=======================
|Field Name||Description
|`message` |optional|Message describing why the private flag was changed.
|=======================
[[problem-info]]
=== ProblemInfo
The `ProblemInfo` entity contains a description of a potential consistency problem
with a change. These are not related to the code review process, but rather
indicate some inconsistency in Gerrit's database or repository metadata related
to the enclosing change.
[options="header",cols="1,^1,5"]
|===========================
|Field Name||Description
|`message` ||Plaintext message describing the problem with the change.
|`status` |optional|
The status of fixing the problem (`FIXED`, `FIX_FAILED`). Only set if a
fix was attempted.
|`outcome` |optional|
If `status` is set, an additional plaintext message describing the
outcome of the fix.
|===========================
[[publish-change-edit-input]]
=== PublishChangeEditInput
The `PublishChangeEditInput` entity contains options for the publishing of
change edit.
[options="header",cols="1,^1,5"]
|=============================
|Field Name ||Description
|`notify` |optional|
Notify handling that defines to whom email notifications should be sent
after the change edit is published. +
Allowed values are `NONE` and `ALL`. +
If not set, the default is `ALL`.
|`notify_details`|optional|
Additional information about whom to notify about the update as a map
of link:user-notify.html#recipient-types[recipient type] to
link:#notify-info[NotifyInfo] entity.
|=============================
[[pure-revert-info]]
=== PureRevertInfo
The `PureRevertInfo` entity describes the result of a pure revert check.
[options="header",cols="1,6"]
|======================
|Field Name |Description
|`is_pure_revert` |Outcome of the check as boolean.
|======================
[[push-certificate-info]]
=== PushCertificateInfo
The `PushCertificateInfo` entity contains information about a push
certificate provided when the user pushed for review with `git push
--signed HEAD:refs/for/<branch>`. Only used when signed push is
link:config-gerrit.html#receive.enableSignedPush[enabled] on the server.
[options="header",cols="1,6"]
|===========================
|Field Name|Description
|`certificate`|Signed certificate payload and GPG signature block.
|`key` |
Information about the key that signed the push, along with any problems
found while checking the signature or the key itself, as a
link:rest-api-accounts.html#gpg-key-info[GpgKeyInfo] entity.
|===========================
[[range-info]]
=== RangeInfo
The `RangeInfo` entity stores the coordinates of a range.
[options="header",cols="1,6"]
|===========================
|Field Name | Description
|`start` | First index.
|`end` | Last index.
|===========================
[[rebase-input]]
=== RebaseInput
The `RebaseInput` entity contains information for changing parent when rebasing.
[options="header",cols="1,^1,5"]
|====================================
|Field Name ||Description
|`base` |optional|
The new parent revision. This can be a ref or a SHA-1 to a concrete patchset. +
Alternatively, a change number can be specified, in which case the current
patch set is inferred. +
Empty string is used for rebasing directly on top of the target branch,
which effectively breaks dependency towards a parent change.
|`strategy` |optional|
The strategy of the merge, can be `recursive`, `resolve`,
`simple-two-way-in-core`, `ours` or `theirs`, default will use project settings.
|`allow_conflicts` |optional, defaults to false|
If `true`, the rebase also succeeds if there are conflicts. +
If there are conflicts the file contents of the rebased patch set contain
git conflict markers to indicate the conflicts. +
Callers can find out whether there were conflicts by checking the
`contains_git_conflicts` field in the returned link:#change-info[ChangeInfo]. +
If there are conflicts the change is marked as work-in-progress. +
Cannot be combined with the `on_behalf_of_uploader` option.
|`on_behalf_of_uploader`|optional, defaults to false|
If `true`, the rebase is done on behalf of the uploader. +
This means the uploader of the current patch set will also be the uploader of
the rebased patch set. The calling user will be recorded as the real user. +
Rebasing on behalf of the uploader is only supported for trivial rebases.
This means this option cannot be combined with the `allow_conflicts` option. +
In addition, rebasing on behalf of the uploader is only supported for the
current patch set of a change. +
If the caller is the uploader this flag is ignored and a normal rebase is done.
|`committer_email`|optional|
Rebase is committed using this email address. Only the registered emails
of the calling user or uploader (when `on_behalf_of_uploader` is `true`) are
considered valid. This option is not supported when rebasing a chain.
|`validation_options` |optional|
Map with key-value pairs that are forwarded as options to the commit validation
listeners (e.g. can be used to skip certain validations). Which validation
options are supported depends on the installed commit validation listeners.
Gerrit core doesn't support any validation options, but commit validation
listeners that are implemented in plugins may. Please refer to the
documentation of the installed plugins to learn whether they support validation
options. Unknown validation options are silently ignored.
|====================================
[[rebase-chain-info]]
=== RebaseChainInfo
The `RebaseChainInfo` entity contains information about a chain of changes
that were rebased.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`rebased_changes` ||List of the unsubmitted ancestors, as link:#change-info[ChangeInfo]
entities. Includes both rebased changes, and previously up-to-date ancestors. The list is ordered by
ancestry, where the oldest ancestor is the first.
|`contains_git_conflicts` ||Whether any of the rebased changes has conflicts
due to rebasing.
|===========================
[[related-change-and-commit-info]]
=== RelatedChangeAndCommitInfo
The `RelatedChangeAndCommitInfo` entity contains information about
a related change and commit.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`project` ||The project of the change or commit.
|`change_id` |optional|The Change-Id of the change.
|`commit` ||The commit as a
link:#commit-info[CommitInfo] entity.
|`_change_number` |optional|The change number.
|`_revision_number` |optional|The revision number.
|`_current_revision_number`|optional|The current revision number.
|`status` |optional|The status of the change. The status of
the change is one of (`NEW`, `MERGED`, `ABANDONED`).
|`submittable` |optional|Boolean indicating whether the change is
submittable. +
Only populated if link:#get-related-changes-submittable[requested].
|===========================
[[related-changes-info]]
=== RelatedChangesInfo
The `RelatedChangesInfo` entity contains information about related
changes.
[options="header",cols="1,6"]
|===========================
|Field Name |Description
|`changes` |A list of
link:#related-change-and-commit-info[RelatedChangeAndCommitInfo] entities
describing the related changes. Sorted by git commit order, newest to
oldest. Empty if there are no related changes.
|===========================
[[requirement]]
=== Requirement
The `Requirement` entity contains information about a requirement relative to a change.
[options="header",cols="1,^1,5"]
|===========================
|Field Name | |Description
|`status` | | Status of the requirement. Can be either `OK`, `NOT_READY` or `RULE_ERROR`.
|`fallback_text` | | A human readable reason
|`type` | |
Alphanumerical (plus hyphens or underscores) string to identify what the requirement is and why it
was triggered. Can be seen as a class: requirements sharing the same type were created for a similar
reason, and the data structure will follow one set of rules.
|===========================
[[restore-input]]
=== RestoreInput
The `RestoreInput` entity contains information for restoring a change.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`message` |optional|
Message to be added as review comment to the change when restoring the
change.
|===========================
[[revert-input]]
=== RevertInput
The `RevertInput` entity contains information for reverting a change.
[options="header",cols="1,^1,5"]
|=================================
|Field Name ||Description
|`message` |optional|
Message to be added as review comment to the change when reverting the
change.
|`notify` |optional|
Notify handling that defines to whom email notifications should be sent
for reverting the change. +
Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. +
If not set, the default is `ALL`.
|`notify_details` |optional|
Additional information about whom to notify about the revert as a map
of link:user-notify.html#recipient-types[recipient type] to
link:#notify-info[NotifyInfo] entity.
|`topic` |optional|
Name of the topic for the revert change. If not set, the default for Revert
endpoint is the topic of the change being reverted, and the default for the
RevertSubmission endpoint is `revert-{submission_id}-{timestamp.now}`.
Topic can't contain quotation marks.
|`work_in_progress` |optional|
When present, change is marked as Work In Progress. The `notify` input is
used if it's present, otherwise it will be overridden to `NONE`. +
Notifications for the reverted change will only sent once the result change is
no longer WIP. +
If not set, the default is false.
|`validation_options`|optional|
Map with key-value pairs that are forwarded as options to the commit validation
listeners (e.g. can be used to skip certain validations). Which validation
options are supported depends on the installed commit validation listeners.
Gerrit core doesn't support any validation options, but commit validation
listeners that are implemented in plugins may. Please refer to the
documentation of the installed plugins to learn whether they support validation
options. Unknown validation options are silently ignored.
|=================================
[[revert-submission-info]]
=== RevertSubmissionInfo
The `RevertSubmissionInfo` entity describes the revert changes.
[options="header",cols="1,6"]
|==============================
|Field Name | Description
|`revert_changes` |
A list of link:#change-info[ChangeInfo] that describes the revert changes. Each
entity in that list is a revert change that was created in that revert
submission.
|==============================
[[review-info]]
=== ReviewInfo
The `ReviewInfo` entity contains information about a review.
[options="header",cols="1,6"]
|===========================
|Field Name |Description
|`labels` |
The labels of the review as a map that maps the label names to the
voting values.
|===========================
[[review-update-info]]
=== ReviewerUpdateInfo
The `ReviewerUpdateInfo` entity contains information about updates to
change's reviewers set.
[options="header",cols="1,6"]
|===========================
|Field Name |Description
|`updated`|
Timestamp of the update.
|`updated_by`|
The account which modified state of the reviewer in question as
link:rest-api-accounts.html#account-info[AccountInfo] entity.
|`reviewer`|
The reviewer added or removed from the change as an
link:rest-api-accounts.html#account-info[AccountInfo] entity. For
reviewers by email the `AccountInfo` doesn't contain an account ID but
only the email and optionally a name.
|`state`|
The reviewer state, one of `REVIEWER`, `CC` or `REMOVED`.
|===========================
[[review-input]]
=== ReviewInput
The `ReviewInput` entity contains information for adding a review to a
revision.
[options="header",cols="1,^1,5"]
|============================
|Field Name ||Description
|`message` |optional|
The message to be added as review comment.
|`tag` |optional|
Apply this tag to the review comment message, votes, and inline
comments. Tags with an 'autogenerated:' prefix may be used by CI or other
automated systems to distinguish them from human reviews. If another
message was posted on a newer patchset, but with the same tag, then the older
message will be hidden in the UI. Suffixes starting with `~` are not considered,
so `autogenerated:my-ci-system~trigger` and `autogenerated:my-ci-system~result`
will be considered being the same tag with regards to the hiding rule.
|`labels` |optional|
The votes that should be added to the revision as a map that maps the
label names to the voting values.
|`comments` |optional|
The comments that should be added as a map that maps a file path to a
list of link:#comment-input[CommentInput] entities.
|`robot_comments` |optional, deprecated|
The robot comments that should be added as a map that maps a file path
to a list of link:#robot-comment-input[RobotCommentInput] entities.
|`drafts` |optional|
Draft handling that defines how draft comments are handled that are
already in the database but that were not also described in this
input. +
Allowed values are `PUBLISH`, `PUBLISH_ALL_REVISIONS` and `KEEP`. All values
except `PUBLISH_ALL_REVISIONS` operate only on drafts for a single revision. +
Only `KEEP` is allowed when used in conjunction with `on_behalf_of`. +
If not set, the default is `KEEP`. If `on_behalf_of` is set, then no other value
besides `KEEP` is allowed.
|`draft_ids_to_publish` |optional|
List of draft IDs to be published. The draft IDs should belong to the current
user and be valid. If `drafts` is set to `PUBLISH`, then draft IDs should
contain drafts for the same revision that is requested for review. If `drafts`
is set to `KEEP`, then `draft_ids_to_publish` will be ignored and no draft
comments will be published. +
If not set, the default is to publish all drafts according to the `drafts` field.
|`notify` |optional|
Notify handling that defines to whom email notifications should be sent
after the review is stored. +
Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. +
If not set, the default is `ALL`.
|`notify_details` |optional|
Additional information about whom to notify about the update as a map
of link:user-notify.html#recipient-types[recipient type] to
link:#notify-info[NotifyInfo] entity.
|`omit_duplicate_comments` |optional|
If `true`, comments with the same content at the same place will be omitted.
|`on_behalf_of` |optional|
link:rest-api-accounts.html#account-id[\{account-id\}] the review
should be posted on behalf of. To use this option the caller must
have been granted `labelAs-NAME` permission for all keys of labels.
|`reviewers` |optional|
A list of link:rest-api-changes.html#reviewer-input[ReviewerInput]
representing reviewers that should be added/removed to/from the change.
|`ready` |optional|
If true, and if the change is work in progress, then start review.
It is an error for both `ready` and `work_in_progress` to be true.
|`work_in_progress` |optional|
If true, mark the change as work in progress. It is an error for both
`ready` and `work_in_progress` to be true.
|`add_to_attention_set` |optional|
list of link:#attention-set-input[AttentionSetInput] entities to add
to the link:user-attention-set.html[attention set]. Users that are not reviewers,
ccs, owner, or uploader are silently ignored.
|`remove_from_attention_set` |optional|
list of link:#attention-set-input[AttentionSetInput] entities to remove
from the link:user-attention-set.html[attention set].
|`ignore_automatic_attention_set_rules`|optional|
If set to true, ignore all automatic attention set rules described in the
link:user-attention-set.html[attention set]. Updates in add_to_attention_set
and remove_from_attention_set are not ignored.
|`response_format_options` |optional|
List of link:#query-options[query options] to format the response.
|============================
[[review-result]]
=== ReviewResult
The `ReviewResult` entity contains information regarding the updates
that were made to a review.
[options="header",cols="1,^1,5"]
|============================
|Field Name ||Description
|`labels` |optional|
Map of labels to values after the review was posted. Null if any reviewer
additions were rejected.
|`reviewers` |optional|
Map of account or group identifier to
link:rest-api-changes.html#reviewer-result[ReviewerResult]
representing the outcome of adding/removing a reviewer.
Absent if no reviewer additions were requested.
|`ready` |optional|
If true, the change was moved from WIP to ready for review as a result of this
action. Not set if false.
|`error` |optional|
Error message for non-200 responses.
|`change_info` ||
Post-update change information.
|============================
[[reviewer-info]]
=== ReviewerInfo
The `ReviewerInfo` entity contains information about a reviewer and its
votes on a change.
`ReviewerInfo` has the same fields as
link:rest-api-accounts.html#account-info[AccountInfo] and includes
link:#detailed-accounts[detailed account information].
In addition `ReviewerInfo` has the following fields:
[options="header",cols="1,6"]
|==========================
|Field Name |Description
|`approvals` |
The approvals of the reviewer as a map that maps the label names to the
approval values ("`-2`", "`-1`", "`0`", "`+1`", "`+2`").
|`_account_id` |
This field is inherited from `AccountInfo` but is optional here if an
unregistered reviewer was added by email. See
link:rest-api-changes.html#add-reviewer[add-reviewer] for details.
|==========================
[[reviewer-input]]
=== ReviewerInput
The `ReviewerInput` entity contains information for adding or removing
reviewers to/from the change.
[options="header",cols="1,^1,5"]
|=============================
|Field Name ||Description
|`reviewer` ||
The link:rest-api-accounts.html#account-id[ID] of one account that
should be added/removed as reviewer or the link:rest-api-groups.html#group-id[
ID] of one internal group for which all members should be added as reviewers. +
If an ID identifies both an account and a group, only the account is
added as reviewer to the change.
External groups, such as LDAP groups, will be silently omitted from a
link:#set-review[set-review] or
link:rest-api-changes.html#add-reviewer[add-reviewer] call. A group can only be
specified for adding reviewers, not for removing them.
|`state` |optional|
Add reviewer in this state. Possible reviewer states are `REVIEWER`,
`CC` and `REMOVED`. If not given, defaults to `REVIEWER`.
|`confirmed` |optional|
Whether adding the reviewer is confirmed. +
The Gerrit server may be configured to
link:config-gerrit.html#addreviewer.maxWithoutConfirmation[require a
confirmation] when adding a group as reviewer that has many members.
|`notify` |optional|
Notify handling that defines to whom email notifications should be sent
after the reviewer is added. +
Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. +
If not set, the default is `ALL`.
|`notify_details`|optional|
Additional information about whom to notify about the update as a map
of link:user-notify.html#recipient-types[recipient type] to
link:#notify-info[NotifyInfo] entity.
|=============================
[[reviewer-result]]
=== ReviewerResult
The `ReviewerResult` entity describes the result of modifying reviewers of
a change.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`input` ||
Value of the `reviewer` field from link:#reviewer-input[ReviewerInput]
set while adding the reviewer.
|`reviewers` |optional|
The newly added reviewers as a list of link:#reviewer-info[
ReviewerInfo] entities.
|`ccs` |optional|
The newly CCed accounts as a list of
link:rest-api-accounts.html#account-info[AccountInfo] entities. This field will
only appear if the requested `state` for the reviewer was `CC`.
|`removed` |optional|
The newly removed accounts as a list of
link:rest-api-accounts.html#account-info[AccountInfo] entities.
This field will only appear if the requested `state` for the reviewer was
`REMOVED`.
|`error` |optional|
Error message explaining why the reviewer could not be added. +
If a group was specified in the input and an error is returned, it
means that none of the members were added as reviewer.
|`confirm` |`false` if not set|
Whether adding the reviewer requires confirmation.
|===========================
[[revision-info]]
=== RevisionInfo
The `RevisionInfo` entity contains information about a patch set.
Not all fields are returned by default. Additional fields can
be obtained by adding `o` parameters as described in
link:#list-changes[Query Changes].
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`kind` ||The change kind. Valid values are `REWORK`, `TRIVIAL_REBASE`,
`TRIVIAL_REBASE_WITH_MESSAGE_UPDATE`, `MERGE_FIRST_PARENT_UPDATE`,
`NO_CODE_CHANGE`, and `NO_CHANGE`.
|`_number` ||The patch set number, or `edit` if the patch set is an edit.
|`created` ||
The link:rest-api.html#timestamp[timestamp] of when the patch set was
created.
|`uploader` ||
The uploader of the patch set as an
link:rest-api-accounts.html#account-info[AccountInfo] entity.
|`real_uploader`|optional|
The real uploader of the patch set as an
link:rest-api-accounts.html#account-info[AccountInfo] entity. +
Only set if the upload was done on behalf of another user.
|`ref` ||The Git reference for the patch set.
|`fetch` ||
Information about how to fetch this patch set. The fetch information is
provided as a map that maps the protocol name ("`git`", "`http`",
"`ssh`") to link:#fetch-info[FetchInfo] entities. This information is
only included if a plugin implementing the
link:intro-project-owner.html#download-commands[download commands]
interface is installed.
|`commit` |optional|The commit of the patch set as
link:#commit-info[CommitInfo] entity.
|`parents_data` |optional|
The parent commits of this patch-set commit as a list of
link:#parent-info[ParentInfo] entities. In each parent, we include the target
branch name if the parent is a merged commit in the target branch. Otherwise,
we include the change and patch-set numbers of the parent change. +
Only set if the `PARENTS` option is set.
|`branch` | optional|The name of the target branch that this revision is
set to be merged into. +
Note that if the change is moved with the link:#move-change[Move Change]
endpoint, this field can be different for different patchsets. For example,
if the change is moved and a new patchset is uploaded afterwards, the
link:#revision-info[RevisionInfo] of the previous patchset will contain the old
`branch`, but the newer patchset will contain the new `branch`.
|`files` |optional|
The files of the patch set as a map that maps the file names to
link:#file-info[FileInfo] entities. Only set if
link:#current-files[CURRENT_FILES] or link:#all-files[ALL_FILES]
option is requested.
|`actions` |optional|
Actions the caller might be able to perform on this revision. The
information is a map of view name to link:#action-info[ActionInfo]
entities.
|`reviewed` |optional|
Indicates whether the caller is authenticated and has commented on the
current revision. Only set if link:#reviewed[REVIEWED] option is requested.
|`commit_with_footers` |optional|
If the link:#commit-footers[COMMIT_FOOTERS] option is requested and
this is the current patch set, contains the full commit message with
Gerrit-specific commit footers, as if this revision were submitted
using the link:project-configuration.html#cherry_pick[Cherry Pick]
submit type.
|`push_certificate` |optional|
If the link:#push-certificates[PUSH_CERTIFICATES] option is requested,
contains the push certificate provided by the user when uploading this
patch set as a link:#push-certificate-info[PushCertificateInfo] entity.
This field is always set if the option is requested; if no push
certificate was provided, it is set to an empty object.
|`description` |optional|
The description of this patchset, as displayed in the patchset
selector menu. May be null if no description is set.
|===========================
[[robot-comment-info]]
=== RobotCommentInfo (deprecated)
The `RobotCommentInfo` entity contains information about a robot inline
comment.
`RobotCommentInfo` has the same fields as <<comment-info,CommentInfo>>
except for the `unresolved` field which doesn't exist for robot comments.
In addition `RobotCommentInfo` has the following fields:
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`robot_id` ||The ID of the robot that generated this comment.
|`robot_run_id` ||An ID of the run of the robot.
|`url` |optional|URL to more information.
|`properties` |optional|Robot specific properties as map that maps arbitrary
keys to values.
|===========================
[[robot-comment-input]]
=== RobotCommentInput (deprecated)
The `RobotCommentInput` entity contains information for creating an inline
robot comment.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`path` ||
link:#file-id[The file path] for which the inline comment should be added.
|`side` |optional|
The side on which the comment should be added. +
Allowed values are `REVISION` and `PARENT`. +
If not set, the default is `REVISION`.
|`line` |optional|
The number of the line for which the comment should be added. +
`0` if it is a file comment. +
If neither line nor range is set, a file comment is added. +
If range is set, this value is ignored in favor of the `end_line` of the range.
|`range` |optional|
The range of the comment as a link:#comment-range[CommentRange]
entity.
|`in_reply_to` |optional|
The URL encoded UUID of the comment to which this comment is a reply.
|`message` |optional|
The comment message.
|`robot_id` ||The ID of the robot that generated this comment.
|`robot_run_id` ||An ID of the run of the robot.
|`url` |optional|URL to more information.
|`properties` |optional|Robot specific properties as map that maps arbitrary
keys to values.
|===========================
[[rule-input]]
=== RuleInput
The `RuleInput` entity contains information to test a Prolog rule.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`rule`||
Prolog code to execute instead of the code in `refs/meta/config`.
|`filters`|`RUN` if not set|
When `RUN` filter rules in the parent projects are called to
post-process the results of the project specific rule. This
behavior matches how the rule will execute if installed. +
If `SKIP` the parent filters are not called, allowing the test
to return results from the input rule.
|===========================
[[submit-input]]
=== SubmitInput
The `SubmitInput` entity contains information for submitting a change.
[options="header",cols="1,^1,5"]
|=============================
|Field Name ||Description
|`on_behalf_of` |optional|
If set, submit the change on behalf of the given user. The value may take any
format link:rest-api-accounts.html#account-id[accepted by the accounts REST
API]. Using this option requires
link:access-control.html#category_submit_on_behalf_of[Submit (On Behalf Of)]
permission on the branch.
|`notify` |optional|
Notify handling that defines to whom email notifications should be sent after
the change is submitted. +
Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. +
If not set, the default is `ALL`.+
Ignored if a post approval diff is present (i.e. if the change is submitted
with copied approvals), because in this case everyone should be informed
about the non-reviewed diff which has been applied after the change has been
approved so that they can take action if the post approval diff looks
unexpected. In other words if a post approval diff is present `ALL` is
enforced.
|`notify_details`|optional|
Additional information about whom to notify about the update as a map
of link:user-notify.html#recipient-types[recipient type] to
link:#notify-info[NotifyInfo] entity.
|=============================
[[submit-record]]
=== SubmitRecord
The `SubmitRecord` entity describes results from a submit_rule.
Fields in this entity roughly correspond to the fields set by `LABELS`
in link:#label-info[LabelInfo].
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`status`||
`OK`, the change can be submitted. +
`NOT_READY`, additional labels are required before submit. +
`CLOSED`, closed changes cannot be submitted. +
`RULE_ERROR`, rule code failed with an error.
|`ok`|optional|
Map of labels that are approved; an
link:rest-api-accounts.html#account-info[AccountInfo] identifies the
voter chosen by the rule.
|`reject`|optional|
Map of labels that are preventing submit;
link:rest-api-accounts.html#account-info[AccountInfo] identifies voter.
|`need`|optional|
Map of labels that need to be given to submit. The value is
currently an empty object.
|`may`|optional|
Map of labels that can be used, but do not affect submit.
link:rest-api-accounts.html#account-info[AccountInfo] identifies voter,
if the label has been applied.
|`impossible`|optional|
Map of labels that should have been in `need` but cannot be
used by any user because of access restrictions. The value
is currently an empty object.
|`error_message`|optional|
When status is RULE_ERROR this message provides some text describing
the failure of the rule predicate.
|===========================
[[submit-record-info]]
=== SubmitRecordInfo
The `SubmitRecordInfo` entity describes results from a submit_rule.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`rule_name`||
The name of the submit rule that created this submit record. The submit rule is
specified in the form of "$plugin~$rule" where `$plugin` is the plugin name
and `$rule` is the name of the class that implemented the submit rule.
|`status`||
`OK`, the change can be submitted. +
`NOT_READY`, additional labels are required before submit. +
`CLOSED`, closed changes cannot be submitted. +
`FORCED`, the change was submitted bypassing the submit rule. +
`RULE_ERROR`, rule code failed with an error.
|`labels`|optional|
A list of labels, each containing the following fields. +
* `label`: the label name. +
* `status`: the label status: {`OK`, `REJECT`, `MAY`, `NEED`, `IMPOSSIBLE`}. +
* `appliedBy`: the link:rest-api-accounts.html#account-info[AccountInfo]
that applied the vote to the label.
|`requirements`|optional|
List of the link:rest-api-changes.html#requirement[requirements] to be met
before this change can be submitted.
|`error_message`|optional|
When status is RULE_ERROR this message provides some text describing
the failure of the rule predicate.
|===========================
[[submit-requirement-expression-info]]
=== SubmitRequirementExpressionInfo
The `SubmitRequirementExpressionInfo` describes the result of evaluating a
single submit requirement expression, for example `label:code-review=+2`.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`expression`|optional|
The submit requirement expression as a string, for example
`branch:refs/heads/foo and label:verified=+1`.
|`fulfilled`||
True if the submit requirement is fulfilled for the change.
|`status`||
A string containing the status of evaluating the expression which can be one
of the following: +
* `PASS` - expression was evaluated and result is true. +
* `FAIL` - expression was evaluated and result is false. +
* `ERROR` - an error occurred while evaluating the expression. +
* `NOT_EVALUATED` - expression was not evaluated.
|`passing_atoms`|optional|
A list of passing atoms as strings. For the above expression,
`passing_atoms` can contain ["branch:refs/heads/foo"] if the branch predicate is
fulfilled for the change.
|`failing_atoms`|optional|
A list of failing atoms. This is similar to `passing_atoms` except that it
contains the list of predicates that are not fulfilled for the change.
|`error_message`|optional|
If the submit requirement fails during evaluation, this string will contain
an error message describing why it failed.
|===========================
[[submit-requirement-input]]
=== SubmitRequirementInput
The `SubmitRequirementInput` entity describes a submit requirement.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`name`||
The submit requirement name.
|`description`|optional|
Description of the submit requirement.
|`applicability_expression`|optional|
Query expression that can be evaluated on any change. If evaluated to true on a
change, the submit requirement is then applicable for this change.
If not specified, the submit requirement is applicable for all changes.
|`submittability_expression`||
Query expression that can be evaluated on any change. If evaluated to true on a
change, the submit requirement is fulfilled and not blocking change submission.
|`override_expression`|optional|
Query expression that can be evaluated on any change. If evaluated to true on a
change, the submit requirement is overridden and not blocking change submission.
|`allow_override_in_child_projects`|optional|
Whether this submit requirement can be overridden in child projects. Default is
`true`.
|===========================
[[submit-requirement-result-info]]
=== SubmitRequirementResultInfo
The `SubmitRequirementResultInfo` describes the result of evaluating a
submit requirement on a change.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`name`||
The submit requirement name.
|`description`|optional|
Description of the submit requirement.
|`status`||
Status describing the result of evaluating the submit requirement. The status
is one of (`SATISFIED`, `UNSATISFIED`, `OVERRIDDEN`, `NOT_APPLICABLE`, `ERROR`,
`FORCED`).
|`is_legacy`||
If true, this submit requirement result was created from a legacy
link:#submit-record[SubmitRecord]. Otherwise, it was created by evaluating a
submit requirement.
|`applicability_expression_result`|optional|
A link:#submit-requirement-expression-info[SubmitRequirementExpressionInfo]
containing the result of evaluating the applicability expression. Not set if the
submit requirement did not define an applicability expression.
Note that fields `expression`, `passing_atoms` and `failing_atoms` are always
omitted for the `applicability_expression_result`.
|`submittability_expression_result`||
A link:#submit-requirement-expression-info[SubmitRequirementExpressionInfo]
containing the result of evaluating the submittability expression. +
If the submit requirement does not apply, the `status` field of the result
will be set to `NOT_EVALUATED`.
|`override_expression_result`|optional|
A link:#submit-requirement-expression-info[SubmitRequirementExpressionInfo]
containing the result of evaluating the override expression. +
Not set if the submit requirement did not define an override expression. If the
submit requirement does not apply, the `status` field of the result will be set
to `NOT_EVALUATED`.
|===========================
[[submitted-together-info]]
=== SubmittedTogetherInfo
The `SubmittedTogetherInfo` entity contains information about a
collection of changes that would be submitted together.
[options="header",cols="1,6"]
|===========================
|Field Name |Description
|`changes` |
A list of ChangeInfo entities representing the changes to be submitted together.
|`non_visible_changes`|
The number of changes to be submitted together that the current user
cannot see. (This count includes changes that are visible to the
current user when their reason for being submitted together involves
changes the user cannot see.)
|===========================
[[suggested-reviewer-info]]
=== SuggestedReviewerInfo
The `SuggestedReviewerInfo` entity contains information about a reviewer
that can be added to a change (an account or a group).
`SuggestedReviewerInfo` has either the `account` field that contains
the link:rest-api-accounts.html#account-info[AccountInfo] entity, or
the `group` field that contains the
link:rest-api-changes.html#group-base-info[GroupBaseInfo] entity.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`account` |optional|
An link:rest-api-accounts.html#account-info[AccountInfo] entity, if the
suggestion is an account.
|`group` |optional|
A link:rest-api-changes.html#group-base-info[GroupBaseInfo] entity, if the
suggestion is a group.
|`count` ||
The total number of accounts in the suggestion. This is `1` if `account` is
present. If `group` is present, the total number of accounts that are
members of the group is returned (this count includes members of nested
groups).
|`confirm` |optional|
True if `group` is present and `count` is above the threshold where the
`confirmed` flag must be passed to add the group as a reviewer.
|===========================
[[topic-input]]
=== TopicInput
The `TopicInput` entity contains information for setting a topic.
[options="header",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`topic` |optional|The topic. +
The topic will be deleted if not set.
Topic can't contain quotation marks.
|===========================
[[tracking-id-info]]
=== TrackingIdInfo
The `TrackingIdInfo` entity describes a reference to an external tracking system.
[options="header",cols="1,6"]
|======================
|Field Name|Description
|`system` |The name of the external tracking system.
|`id` |The tracking id.
|======================
[[voting-range-info]]
=== VotingRangeInfo
The `VotingRangeInfo` entity describes the continuous voting range from min
to max values.
[options="header",cols="1,6"]
|======================
|Field Name|Description
|`min` |The minimum voting value.
|`max` |The maximum voting value.
|======================
[[web-link-info]]
=== WebLinkInfo
The `WebLinkInfo` entity describes a link to an external site. Depending on the
context and the provided data the UI may decide to show the link as a text link,
a linkified icon, or both.
If the `tooltip` is not provided, then the UI may fall back to showing something
like "Open in External Tool".
Weblinks will always be opened in a new tab.
[options="header",cols="1,^1,5"]
|========================
|Field Name ||Description
|`name` ||The text to be linkified.
|`tooltip` |optional|Tooltip to show when hovering over the link. Using "Open
in $NAME_OF_EXTERNAL_TOOL" is a good option here.
|`url` ||The link URL.
|`image_url`|optional|URL to the icon of the link.
|========================
[[work-in-progress-input]]
=== WorkInProgressInput
The `WorkInProgressInput` entity contains additional information for a change
set to WorkInProgress/ReadyForReview.
[options="header",cols="1,^1,5"]
|=============================
|Field Name ||Description
|`message` |optional|
Message to be added as a review comment to the change being set WorkInProgress/ReadyForReview.
|=============================
GERRIT
------
Part of link:index.html[Gerrit Code Review]
SEARCHBOX
---------