diff options
Diffstat (limited to 'Documentation/rest-api-changes.txt')
| -rw-r--r-- | Documentation/rest-api-changes.txt | 2153 |
1 files changed, 2153 insertions, 0 deletions
diff --git a/Documentation/rest-api-changes.txt b/Documentation/rest-api-changes.txt new file mode 100644 index 0000000000..696a1746d5 --- /dev/null +++ b/Documentation/rest-api-changes.txt @@ -0,0 +1,2153 @@ +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 +---------------- + +[[list-changes]] +Query Changes +~~~~~~~~~~~~~ +[verse] +'GET /changes/' + +Queries changes visible to the caller. The query string must be +provided by the `q` parameter. The `n` parameter can be used to limit +the returned results. + +As result a list of link:#change-info[ChangeInfo] entries is returned. +The change output is sorted by the last update time, most recently +updated to oldest updated. + +Query for open changes of watched projects: + +.Request +---- + GET /changes/?q=status:open+is:watched&n=2 HTTP/1.0 +---- + +.Response +---- + HTTP/1.1 200 OK + Content-Disposition: attachment + Content-Type: application/json;charset=UTF-8 + + )]}' + [ + { + "kind": "gerritcodereview#change", + "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", + "reviewed": true, + "mergeable": true, + "_sortkey": "001e7057000006dc", + "_number": 1756, + "owner": { + "name": "John Doe" + }, + }, + { + "kind": "gerritcodereview#change", + "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, + "_sortkey": "001e7056000006dd", + "_number": 1757, + "owner": { + "name": "John Doe" + }, + "_more_changes": true + } + ] +---- + +If the `n` query parameter is supplied and additional changes exist +that match the query beyond the end, the last change object has a +`_more_changes: true` JSON field set. Callers can resume a query with +the `N` query parameter, supplying the last change's `_sortkey` field +as the value. When going in the reverse direction with the `P` query +parameter a `_more_changes: true` is put in the first change object if +there are results *before* the first change returned. + +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 + + )]}' + [ + [ + { + "kind": "gerritcodereview#change", + "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", + "reviewed": true, + "mergeable": true, + "_sortkey": "001e7057000006dc", + "_number": 1756, + "owner": { + "name": "John Doe" + }, + "labels": { + "Verified": {}, + "Code-Review": {} + } + } + ], + [], + [] + ] +---- + +.Query the changes for your user dashboard +**** +get::/changes/?q=is:open+owner:self&q=is:open+reviewer:self+-owner:self&q=is:closed+owner:self+limit:5&o=LABELS +**** + +Additional fields can be obtained by adding `o` parameters, each +option requires more database lookups and slows down the query +response time to the client so they are generally disabled by +default. Optional fields are: + +[[labels]] +-- +* `LABELS`: a summary of each label required for submit, and + approvers that have granted (or rejected) with that label. +-- + +[[detailed-labels]] +-- +* `DETAILED_LABELS`: detailed label information, including numeric + values of all existing approvals, recognized label values, values + permitted to be set by the current user, and reviewers that may be + removed by the current user. +-- + +[[current-revision]] +-- +* `CURRENT_REVISION`: describe the current revision (patch set) + of the change, including the commit SHA-1 and URLs to fetch from. +-- + +[[all-revisions]] +-- +* `ALL_REVISIONS`: describe all revisions, not just current. +-- + +[[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 are selected. +-- + +[[all-commits]] +-- +* `ALL_COMMITS`: parse and output all header fields from the + output revisions. If only `CURRENT_REVISION` was requested + then only the current revision's commit data will be output. +-- + +[[current-files]] +-- +* `CURRENT_FILES`: list files modified by the commit, including + basic line counts inserted/deleted per file. Only valid when + the current revision or all revisions are selected. +-- + +[[all-files]] +-- +* `ALL_FILES`: list files modified by the commit, including + basic line counts inserted/deleted per file. If only the + `CURRENT_REVISION` was requested the only that commit's + modified files will be output. +-- + +[[detailed-accounts]] +-- +* `DETAILED_ACCOUNTS`: include `_account_id` and `email` fields when + referencing accounts. +-- + +.Request +---- + GET /changes/?q=97&o=CURRENT_REVISION&o=CURRENT_COMMIT&o=CURRENT_FILES HTTP/1.0 +---- + +.Response +---- + HTTP/1.1 200 OK + Content-Disposition: attachment + Content-Type: application/json;charset=UTF-8 + + )]}' + [ + { + "kind": "gerritcodereview#change", + "id": "demo~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, + "_sortkey": "001c9bf400000061", + "_number": 97, + "owner": { + "name": "Shawn Pearce" + }, + "current_revision": "184ebe53805e102605d11f6b143486d15c23a09c", + "revisions": { + "184ebe53805e102605d11f6b143486d15c23a09c": { + "_number": 1, + "fetch": { + "git": { + "url": "git://localhost/gerrit", + "ref": "refs/changes/97/97/1" + }, + "http": { + "url": "http://127.0.0.1:8080/gerrit", + "ref": "refs/changes/97/97/1" + } + }, + "commit": { + "parents": [ + { + "commit": "1eee2c9d8f352483781e772f35dc586a69ff5646", + "subject": "Migrate contributor agreements to All-Projects." + } + ], + "author": { + "name": "Shawn O. Pearce", + "email": "sop@google.com", + "date": "2012-04-24 18:08:08.000000000", + "tz": -420 + }, + "committer": { + "name": "Shawn O. Pearce", + "email": "sop@google.com", + "date": "2012-04-24 18:08:08.000000000", + "tz": -420 + }, + "subject": "Use an EventBus to manage star icons", + "message": "Use an EventBus to manage star icons\n\nImage widgets that need to ..." + }, + "files": { + "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeCache.java": { + "lines_deleted": 8 + }, + "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeDetailCache.java": { + "lines_inserted": 1 + }, + "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeScreen.java": { + "lines_inserted": 11, + "lines_deleted": 19 + }, + "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeTable.java": { + "lines_inserted": 23, + "lines_deleted": 20 + }, + "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarCache.java": { + "status": "D", + "lines_deleted": 139 + }, + "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarredChanges.java": { + "status": "A", + "lines_inserted": 204 + }, + "gerrit-gwtui/src/main/java/com/google/gerrit/client/ui/Screen.java": { + "lines_deleted": 9 + } + } + } + } + } + ] +---- + +[[get-change]] +Get Change +~~~~~~~~~~ +[verse] +'GET /changes/link:#change-id[\{change-id\}]' + +Retrieves a change. + +.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 + + )]}' + { + "kind": "gerritcodereview#change", + "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", + "reviewed": true, + "mergeable": true, + "_sortkey": "0023412400000f7d", + "_number": 3965, + "owner": { + "name": "John Doe" + } + } +---- + +[[get-change-detail]] +Get Change Detail +~~~~~~~~~~~~~~~~~ +[verse] +'GET /changes/link:#change-id[\{change-id\}]/detail' + +Retrieves a change with link:#labels[labels], link:#detailed-labels[ +detailed labels] and link:#detailed-accounts[detailed accounts]. + +.Request +---- + GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/detail 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 + + )]}' + { + "kind": "gerritcodereview#change", + "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", + "reviewed": true, + "mergeable": true, + "_sortkey": "0023412400000f7d", + "_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": { + "recommended": { + "_account_id": 1000097, + "name": "Jane Roe", + "email": "jane.roe@example.com" + }, + "disliked": { + "_account_id": 1000096, + "name": "John Doe", + "email": "john.doe@example.com" + }, + "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": "Do not submit", + "-1": "I would prefer that you didn\u0027t submit this", + " 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" + } + ] + } +---- + +[[get-topic]] +Get Topic +~~~~~~~~~ +[verse] +'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 +~~~~~~~~~ +[verse] +'PUT /changes/link:#change-id[\{change-id\}]/topic' + +Sets the topic of a change. + +The new topic must be provided in the request body inside a +link:#topic-input[TopicInput] entity. + +.Request +---- + PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic HTTP/1.0 + Content-Type: application/json;charset=UTF-8 + + { + "topic": "Documentation" + } +---- + +As response the new topic is returned. + +.Response +---- + HTTP/1.1 200 OK + Content-Disposition: attachment + Content-Type: application/json;charset=UTF-8 + + )]}' + "Documentation" +---- + +If the topic was deleted the response is "`204 No Content`". + +[[delete-topic]] +Delete Topic +~~~~~~~~~~~~ +[verse] +'DELETE /changes/link:#change-id[\{change-id\}]/topic' + +Deletes the topic of a change. + +The request body does not need to include a link:#topic-input[ +TopicInput] entity if no review comment is added. + +Please note that some proxies prohibit request bodies for DELETE +requests. In this case, if you want to specify a commit message, use +link:#set-topic[PUT] to delete the topic. + +.Request +---- + DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic HTTP/1.0 +---- + +.Response +---- + HTTP/1.1 204 No Content +---- + +[[abandon-change]] +Abandon Change +~~~~~~~~~~~~~~ +[verse] +'POST /changes/link:#change-id[\{change-id\}]/abandon' + +Abandons a change. + +The request body does not need to include a link:#abandon-input[ +AbandonInput] entity if no review comment is added. + +.Request +---- + POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/abandon HTTP/1.0 +---- + +As response a link:#change-info[ChangeInfo] entity is returned that +describes the abandoned change. + +.Response +---- + HTTP/1.1 200 OK + Content-Disposition: attachment + Content-Type: application/json;charset=UTF-8 + + )]}' + { + "kind": "gerritcodereview#change", + "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", + "reviewed": true, + "mergeable": true, + "_sortkey": "0023412400000f7d", + "_number": 3965, + "owner": { + "name": "John Doe" + } + } +---- + +If the change cannot be abandoned because the change state doesn't +allow abandoning of the change, the response is "`409 Conflict`" and +the error message is contained in the response body. + +.Response +---- + HTTP/1.1 409 Conflict + Content-Disposition: attachment + Content-Type: text/plain;charset=UTF-8 + + change is merged +---- + +[[restore-change]] +Restore Change +~~~~~~~~~~~~~~ +[verse] +'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 + + )]}' + { + "kind": "gerritcodereview#change", + "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", + "reviewed": true, + "mergeable": true, + "_sortkey": "0023412400000f7d", + "_number": 3965, + "owner": { + "name": "John Doe" + } + } +---- + +If the change cannot be restored because the change state doesn't +allow restoring the change, the response is "`409 Conflict`" and +the error message is contained in the response body. + +.Response +---- + HTTP/1.1 409 Conflict + Content-Disposition: attachment + Content-Type: text/plain;charset=UTF-8 + + change is new +---- + +[[revert-change]] +Revert Change +~~~~~~~~~~~~~ +[verse] +'POST /changes/link:#change-id[\{change-id\}]/revert' + +Reverts a change. + +The request body does not need to include a link:#revert-input[ +RevertInput] entity if no review comment is added. + +.Request +---- + POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revert HTTP/1.0 +---- + +As response a link:#change-info[ChangeInfo] entity is returned that +describes the reverting change. + +.Response +---- + HTTP/1.1 200 OK + Content-Disposition: attachment + Content-Type: application/json;charset=UTF-8 + + )]}' + { + "kind": "gerritcodereview#change", + "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", + "reviewed": true, + "mergeable": true, + "_sortkey": "0023412400000f7d", + "_number": 3965, + "owner": { + "name": "John Doe" + } + } +---- + +If the change cannot be reverted because the change state doesn't +allow reverting the change, the response is "`409 Conflict`" and +the error message is contained in the response body. + +.Response +---- + HTTP/1.1 409 Conflict + Content-Disposition: attachment + Content-Type: text/plain;charset=UTF-8 + + change is new +---- + +[[submit-change]] +Submit Change +~~~~~~~~~~~~~ +[verse] +'POST /changes/link:#change-id[\{change-id\}]/submit' + +Submits a change. + +The request body only needs to include a link:#submit-input[ +SubmitInput] entity if the request should wait for the merge to +complete. + +.Request +---- + POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/submit HTTP/1.0 + Content-Type: application/json;charset=UTF-8 + + { + "wait_for_merge": true + } +---- + +As response a link:#change-info[ChangeInfo] entity is returned that +describes the submitted/merged change. + +.Response +---- + HTTP/1.1 200 OK + Content-Disposition: attachment + Content-Type: application/json;charset=UTF-8 + + )]}' + { + "kind": "gerritcodereview#change", + "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", + "reviewed": true, + "_sortkey": "0023412400000f7d", + "_number": 3965, + "owner": { + "name": "John Doe" + } + } +---- + +If the change cannot be submitted because the submit rule doesn't allow +submitting the change, the response is "`409 Conflict`" and the error +message is contained in the response body. + +.Response +---- + HTTP/1.1 409 Conflict + Content-Disposition: attachment + Content-Type: text/plain;charset=UTF-8 + + blocked by Verified +---- + +[[reviewer-endpoints]] +Reviewer Endpoints +------------------ + +[[list-reviewers]] +List Reviewers +~~~~~~~~~~~~~~ +[verse] +'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 + + )]}' + [ + { + "kind": "gerritcodereview#reviewer", + "approvals": { + "Verified": "+1", + "Code-Review": "+2" + }, + "_account_id": 1000096, + "name": "John Doe", + "email": "john.doe@example.com" + }, + { + "kind": "gerritcodereview#reviewer", + "approvals": { + "Verified": " 0", + "Code-Review": "-1" + }, + "_account_id": 1000097, + "name": "Jane Roe", + "email": "jane.roe@example.com" + } + ] +---- + +[[get-reviewer]] +Get Reviewer +~~~~~~~~~~~~ +[verse] +'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 + + )]}' + { + "kind": "gerritcodereview#reviewer", + "approvals": { + "Verified": "+1", + "Code-Review": "+2" + }, + "_account_id": 1000096, + "name": "John Doe", + "email": "john.doe@example.com" + } +---- + +[[add-reviewer]] +Add Reviewer +~~~~~~~~~~~~ +[verse] +'POST /changes/link:#change-id[\{change-id\}]/reviewers' + +Adds one user or all members of one group as reviewer to the change. + +The reviewer to be added to the change must be provided in the request +body as a link:#reviewer-input[ReviewerInput] entity. + +.Request +---- + POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers HTTP/1.0 + Content-Type: application/json;charset=UTF-8 + + { + "reviewer": "john.doe@example.com" + } +---- + +As response an link:#add-reviewer-result[AddReviewerResult] entity is +returned that describes the newly added reviewers. + +.Response +---- + HTTP/1.1 200 OK + Content-Disposition: attachment + Content-Type: application/json;charset=UTF-8 + + )]}' + { + "reviewers": [ + { + "kind": "gerritcodereview#reviewer", + "approvals": { + "Verified": " 0", + "Code-Review": " 0" + }, + "_account_id": 1000096, + "name": "John Doe", + "email": "john.doe@example.com" + } + ] + } +---- + +If a group is specified, adding the group members as reviewers is an +atomic operation. This means if an error is returned, none of the +members are added as reviewer. + +If a group with many members is added as reviewer a confirmation may be +required. + +.Request +---- + POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers HTTP/1.0 + Content-Type: application/json;charset=UTF-8 + + { + "reviewer": "MyProjectVerifiers" + } +---- + +.Response +---- + HTTP/1.1 200 OK + Content-Disposition: attachment + Content-Type: application/json;charset=UTF-8 + + )]}' + { + "error": "The group My Group has 15 members. Do you want to add them all as reviewers?", + "confirm": true + } +---- + +To confirm the addition of the reviewers, resend the request with the +`confirmed` flag being set. + +.Request +---- + POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers HTTP/1.0 + Content-Type: application/json;charset=UTF-8 + + { + "reviewer": "MyProjectVerifiers", + "confirmed": true + } +---- + +[[delete-reviewer]] +Delete Reviewer +~~~~~~~~~~~~~~~ +[verse] +'DELETE /changes/link:#change-id[\{change-id\}]/reviewers/link:rest-api-accounts.html#account-id[\{account-id\}]' + +Deletes a reviewer from a change. + +.Request +---- + DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe HTTP/1.0 +---- + +.Response +---- + HTTP/1.1 204 No Content +---- + +[[revision-endpoints]] +Revision Endpoints +------------------ + +[[get-review]] +Get Review +~~~~~~~~~~ +[verse] +'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 + + )]}' + { + "kind": "gerritcodereview#change", + "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", + "reviewed": true, + "mergeable": true, + "_sortkey": "0023412400000f7d", + "_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": "Do not submit", + "-1": "I would prefer that you didn\u0027t submit this", + " 0": "No score", + "+1": "Looks good to me, but someone else must approve", + "+2": "Looks good to me, approved" + } + } + }, + "permitted_labels": { + "Verified": [ + "-1", + " 0", + "+1" + ], + "Code-Review": [ + "-2", + "-1", + " 0", + "+1", + "+2" + ] + }, + "removable_reviewers": [ + { + "_account_id": 1000096, + "name": "John Doe", + "email": "john.doe@example.com" + }, + { + "_account_id": 1000097, + "name": "Jane Roe", + "email": "jane.roe@example.com" + } + ], + "current_revision": "674ac754f91e64a0efb8087e59a176484bd534d1", + "revisions": { + "674ac754f91e64a0efb8087e59a176484bd534d1": { + "_number": 2, + "fetch": { + "http": { + "url": "http://gerrit/myProject", + "ref": "refs/changes/65/3965/2" + } + } + } + } +---- + +[[set-review]] +Set Review +~~~~~~~~~~ +[verse] +'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/review' + +Sets a review on a revision. + +The review must be provided in the request body as a +link:#review-input[ReviewInput] entity. + +.Request +---- + POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/review HTTP/1.0 + Content-Type: application/json;charset=UTF-8 + + { + "message": "Some nits need to be fixed.", + "labels": { + "Code-Review": -1 + }, + "comments": { + "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": [ + { + "line": 23, + "message": "[nit] trailing whitespace" + }, + { + "line": 49, + "message": "[nit] s/conrtol/control" + } + ] + } + } +---- + +As response a link:#review-info[ReviewInfo] entity is returned that +describes the applied labels. + +.Response +---- + HTTP/1.1 200 OK + Content-Disposition: attachment + Content-Type: application/json;charset=UTF-8 + + )]}' + { + "labels": { + "Code-Review": -1 + } + } +---- + +[[submit-revision]] +Submit Revision +~~~~~~~~~~~~~~~ +[verse] +'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/submit' + +Submits a revision. + +The request body only needs to include a link:#submit-input[ +SubmitInput] entity if the request should wait for the merge to +complete. + +.Request +---- + POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/submit HTTP/1.0 + Content-Type: application/json;charset=UTF-8 + + { + "wait_for_merge": true + } +---- + +As response a link:#submit-info[SubmitInfo] entity is returned that +describes the status of the submitted change. + +.Response +---- + HTTP/1.1 200 OK + Content-Disposition: attachment + Content-Type: application/json;charset=UTF-8 + + )]}' + { + "status": "MERGED" + } +---- + +If the revision cannot be submitted, e.g. because the submit rule +doesn't allow submitting the revision or the revision is not the +current revision, the response is "`409 Conflict`" and the error +message is contained in the response body. + +.Response +---- + HTTP/1.1 409 Conflict + Content-Type: text/plain;charset=UTF-8 + + "revision 674ac754f91e64a0efb8087e59a176484bd534d1 is not current revision" +---- + +[[get-submit-type]] +Get Submit Type +~~~~~~~~~~~~~~~ +[verse] +'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 +~~~~~~~~~~~~~~~~ +[verse] +'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 +~~~~~~~~~~~~~~~~ +[verse] +'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_type?filters=SKIP HTTP/1.0 + Content-Type: text/plain;charset-UTF-8 + + submit_rule(submit(R)) :- + R = label('Any-Label-Name', reject(_)). +---- + +The response is a list of link:#submit-record[SubmitRecord] entries +describing the permutations that satisfy the tested submit rule. + +.Response +---- + HTTP/1.1 200 OK + Content-Disposition: attachment + Content-Type: application/json;charset=UTF-8 + + )]}' + [ + { + "status": "NOT_READY", + "reject": { + "Any-Label-Name": {} + } + } + ] +---- + +[[list-drafts]] +List Drafts +~~~~~~~~~~~ +[verse] +'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/drafts/' + +Lists the draft comments of a revision that belong to the calling +user. + +As result a map is returned that maps the file path to a list of +link:#comment-info[CommentInfo] entries. The entries in the map are +sorted by file path. + +.Request +---- + GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/drafts/ HTTP/1.0 +---- + +.Response +---- + HTTP/1.1 200 OK + Content-Disposition: attachment + Content-Type: application/json;charset=UTF-8 + + )]}' + { + "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": [ + { + "kind": "gerritcodereview#comment", + "id": "TvcXrmjM", + "line": 23, + "message": "[nit] trailing whitespace", + "updated": "2013-02-26 15:40:43.986000000" + }, + { + "kind": "gerritcodereview#comment", + "id": "TveXwFiA", + "line": 49, + "in_reply_to": "TfYX-Iuo", + "message": "Done", + "updated": "2013-02-26 15:40:45.328000000" + } + ] + } +---- + +[[create-draft]] +Create Draft +~~~~~~~~~~~~ +[verse] +'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 + + )]}' + { + "kind": "gerritcodereview#comment", + "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 +~~~~~~~~~ +[verse] +'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 + + )]}' + { + "kind": "gerritcodereview#comment", + "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 +~~~~~~~~~~~~ +[verse] +'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 + + )]}' + { + "kind": "gerritcodereview#comment", + "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 +~~~~~~~~~~~~ +[verse] +'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 +---- + +[[set-reviewed]] +Set Reviewed +~~~~~~~~~~~~ +[verse] +'PUT /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/files/link:#patch-id[\{patch-id\}]/reviewed' + +Marks a patch 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 patch was already marked as reviewed by the calling user the +response is "`200 OK`". + +[[delete-reviewed]] +Delete Reviewed +~~~~~~~~~~~~~~~ +[verse] +'DELETE /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/files/link:#patch-id[\{patch-id\}]/reviewed' + +Deletes the reviewed flag of the calling user from a patch 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 +---- + + +[[ids]] +IDs +--- + +[[account-id]] +link:rest-api-accounts.html#account-id[\{account-id\}] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +-- +-- + +[[change-id]] +\{change-id\} +~~~~~~~~~~~~~ +Identifier that uniquely identifies one change. + +This can be: + +* an ID of the change in the format "'$$<project>~<branch>~<Change-Id>$$'", + where for the branch the `refs/heads/` prefix can be omitted + ("$$myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940$$") +* a Change-Id if it uniquely identifies one change + ("I8473b95934b5732ac55d26311a706c9c2bde9940") +* a legacy numeric change ID ("4247") + +[[draft-id]] +\{draft-id\} +~~~~~~~~~~~~ +UUID of a draft comment. + +[[patch-id]] +\{patch-id\} +~~~~~~~~~~~~ +The file path of the patch. + +[[revision-id]] +\{revision-id\} +~~~~~~~~~~~~~~~ +Identifier that uniquely identifies one revision of a change. + +This can be: + +* the literal `current` to name the current patch set/revision +* a commit ID ("674ac754f91e64a0efb8087e59a176484bd534d1") +* an abbreviated commit ID that uniquely identifies one revision of the + change ("674ac754"), at least 4 digits are required +* a legacy numeric patch number ("1" for first patch set of the change) + + +[[json-entities]] +JSON Entities +------------- + +[[abandon-input]] +AbandonInput +~~~~~~~~~~~~ +The `AbandonInput` entity contains information for abandoning a change. + +[options="header",width="50%",cols="1,^1,5"] +|=========================== +|Field Name ||Description +|`message` |optional| +Message to be added as review comment to the change when abandoning the +change. +|=========================== + +[[add-reviewer-result]] +AddReviewerResult +~~~~~~~~~~~~~~~~~ +The `AddReviewerResult` entity describes the result of adding a +reviewer to a change. + +[options="header",width="50%",cols="1,^1,5"] +|=========================== +|Field Name ||Description +|`reviewers` |optional| +The newly added reviewers as a list of link:#reviewer-info[ +ReviewerInfo] entities. +|`error` |optional| +Error message explaining why the reviewer could not be added. + +If a group was specified in the input and an error is returned, it +means that none of the members were added as reviewer. +|`confirm` |`false` if not set| +Whether adding the reviewer requires confirmation. +|=========================== + +[[approval-info]] +ApprovalInfo +~~~~~~~~~~~~ +The `ApprovalInfo` entity contains information about an approval from a +user for a label on a change. + +`ApprovalInfo` has the same fields as +link:rest-api-accounts.html#account-info[AccountInfo]. +In addition `ApprovalInfo` has the following fields: + +[options="header",width="50%",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. +|=========================== + +[[change-info]] +ChangeInfo +~~~~~~~~~~ +The `ChangeInfo` entity contains information about a change. + +[options="header",width="50%",cols="1,^1,5"] +|================================== +|Field Name ||Description +|`kind` ||`gerritcodereview#change` +|`id` || +The ID of the change in the format "'<project>\~<branch>~<Change-Id>'", +where 'project', 'branch' and 'Change-Id' are URL encoded. For 'branch' the +`refs/heads/` prefix is omitted. +|`project` ||The name of the project. +|`branch` || +The name of the target branch. + +The `refs/heads/` prefix is omitted. +|`topic` |optional|The topic to which this change belongs. +|`change_id` ||The Change-Id of the change. +|`subject` || +The subject of the change (header line of the commit message). +|`status` || +The status of the change (`NEW`, `SUBMITTED`, `MERGED`, `ABANDONED`, +`DRAFT`). +|`created` || +The link:rest-api.html#timestamp[timestamp] of when the change was +created. +|`updated` || +The link:rest-api.html#timestamp[timestamp] of when the change was last +updated. +|`starred` |not set if `false`| +Whether the calling user has starred this change. +|`reviewed` |not set if `false`| +Whether the change was reviewed by the calling user. +|`mergeable` |optional| +Whether the change is mergeable. + +Not set for merged changes. +|`_sortkey` ||The sortkey of the change. +|`_number` ||The legacy numeric ID of the change. +|`owner` || +The owner of the change as an link:rest-api-accounts.html#account-info[ +AccountInfo] entity. +|`labels` |optional| +The labels of the change as a map that maps the label names to +link:#label-info[LabelInfo] entries. + +Only set if link:#labels[labels] or link:#detailed-labels[detailed +labels] are requested. +|`permitted_labels` |optional| +A map of the permitted labels that maps a label name to the list of +values that are allowed for that label. + +Only set if link:#detailed-labels[detailed labels] are requested. +|`removable_reviewers`|optional| +The reviewers that can be removed by the calling user as a list of +link:rest-api-accounts.html#account-info[AccountInfo] entities. + +Only set if link:#detailed-labels[detailed labels] are requested. +|`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:#all-revisions[all revisions] are requested. +|`_more_changes` |optional, not set if `false`| +Whether the query would deliver more results if not limited. + +Only set on either the last or the first change that is returned. +|================================== + +[[comment-info]] +CommentInfo +~~~~~~~~~~~ +The `CommentInfo` entity contains information about an inline comment. + +[options="header",width="50%",cols="1,^1,5"] +|=========================== +|Field Name ||Description +|`kind` ||`gerritcodereview#comment` +|`id` ||The URL encoded UUID of the draft comment. +|`path` |optional| +The path of the file for which the inline comment was done. + +Not set if returned in a map where the key is the file path. +|`side` |optional| +The side on which the comment was added. + +Allowed values are `REVISION` and `PARENT`. + +If not set, the default is `REVISION`. +|`line` |optional| +The number of the line for which the comment was done. + +If not set, it's a file comment. +|`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. +|=========================== + +[[comment-input]] +CommentInput +~~~~~~~~~~~~ +The `CommitInput` entity contains information for creating an inline +comment. + +[options="header",width="50%",cols="1,^1,5"] +|=========================== +|Field Name ||Description +|`kind` |optional| +Must be `gerritcodereview#comment` if provided. +|`id` |optional| +The URL encoded UUID of the comment if an existing draft comment should +be updated. +|`path` |optional| +The path of the file for which the inline comment should be added. + +Doesn't need to be set if contained in a map where the key is the file +path. +|`side` |optional| +The side on which the comment should be added. + +Allowed values are `REVISION` and `PARENT`. + +If not set, the default is `REVISION`. +|`line` |optional| +The number of the line for which the comment should be added. + +`0` if it is a file comment. + +If not set, a file comment is added. +|`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. +|=========================== + +[[commit-info]] +CommitInfo +~~~~~~~~~~ +The `CommitInfo` entity contains information about a commit. + +[options="header",width="50%",cols="1,6"] +|========================== +|Field Name |Description +|`commit` |The commit ID. +|`parent` | +The parent commits of this commit as a list of +link:#commit-info[CommitInfo] entities. +|`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. +|========================== + +[[fetch-info]] +FetchInfo +~~~~~~~~~ +The `FetchInfo` entity contains information about how to fetch a patch +set via a certain protocol. + +[options="header",width="50%",cols="1,6"] +|========================== +|Field Name |Description +|`url` |The URL of the project. +|`ref` |The ref of the patch set. +|========================== + +[[file-info]] +FileInfo +~~~~~~~~ +The `FileInfo` entity contains information about a file in a patch set. + +[options="header",width="50%",cols="1,^1,5"] +|============================= +|Field Name ||Description +|`status` |optional| +The status of the file ("`A`"=Added, "`D`"=Deleted, "`R`"=Renamed, +"`C`"=Copied, "`W`"=Rewritten). + +Not set if the file was Modified ("`M`"). +|`binary` |not set if `false`|Whether the file is binary. +|`old_path` |optional| +The old file path. + +Only set if the file was renamed or copied. +|`lines_inserted`|optional| +Number of inserted lines. + +Not set for binary files or if no lines were inserted. +|`lines_deleted` |optional| +Number of deleted lines. + +Not set for binary files or if no lines were deleted. +|============================= + +[[git-person-info]] +GitPersonInfo +~~~~~~~~~~~~~ +The `GitPersonInfo` entity contains information about the +author/committer of a commit. + +[options="header",width="50%",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. +|========================== + +[[label-info]] +LabelInfo +~~~~~~~~~ +The `LabelInfo` entity contains information about a label on a change. + +[options="header",width="50%",cols="1,^1,5"] +|=========================== +|Field Name ||Description +|`approved` |optional|The user who approved this label on the change +as a link:rest-api-accounts.html#account-info[AccountInfo] entity. + +Only set if link:#labels[labels] are requested. +|`rejected` |optional|The user who rejected this label on the change +as a link:rest-api-accounts.html#account-info[AccountInfo] entity. + +Only set if link:#labels[labels] are requested. +|`recommended` |optional|The user who recommended this label on the +change as a link:rest-api-accounts.html#account-info[AccountInfo] entity. + +Only set if link:#labels[labels] are requested. +|`disliked` |optional|The user who disliked this label on the change +as a link:rest-api-accounts.html#account-info[AccountInfo] entity. + +Only set if link:#labels[labels] are requested. +|`value` |optional|The voting value of the user who +recommended/disliked this label on the change if it is not +"`+1`"/"`-1`". + +Only set if link:#labels[labels] are requested. +|`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. +|`all` |optional|List of all approvals for this label as a list +of link:#approval-info[ApprovalInfo] entities. + +Only set if link:#detailed-labels[detailed labels] are 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. + +Only set if link:#detailed-labels[detailed labels] are requested. +|=========================== + +[[restore-input]] +RestoreInput +~~~~~~~~~~~~ +The `RestoreInput` entity contains information for restoring a change. + +[options="header",width="50%",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",width="50%",cols="1,^1,5"] +|=========================== +|Field Name ||Description +|`message` |optional| +Message to be added as review comment to the change when reverting the +change. +|=========================== + +[[review-info]] +ReviewInfo +~~~~~~~~~~ +The `ReviewInfo` entity contains information about a review. + +[options="header",width="50%",cols="1,6"] +|=========================== +|Field Name |Description +|`labels` | +The labels of the review as a map that maps the label names to the +voting values. +|=========================== + +[[review-input]] +ReviewInput +~~~~~~~~~~~ +The `ReviewInput` entity contains information for adding a review to a +revision. + +[options="header",width="50%",cols="1,^1,5"] +|============================ +|Field Name ||Description +|`message` |optional| +The message to be added as review comment. +|`labels` |optional| +The votes that should be added to the revision as a map that maps the +label names to the voting values. +|`comments` |optional| +The comments that should be added as a map that maps a file path to a +list of link:#comment-input[CommentInput] entities. +|`strict_labels`|`true` if not set| +Whether all labels are required to be within the user's permitted ranges +based on access controls. + +If `true`, attempting to use a label not granted to the user will fail +the entire modify operation early. + +If `false`, the operation will execute anyway, but the proposed labels +will be modified to be the "best" value allowed by the access controls. +|`drafts` |optional| +Draft handling that defines how draft comments are handled that are +already in the database but that were not also described in this +input. + +Allowed values are `DELETE`, `PUBLISH` and `KEEP`. + +If not set, the default is `DELETE`. +|`notify` |optional| +Notify handling that defines to whom email notifications should be sent +after the review is stored. + +Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. + +If not set, the default is `ALL`. +|============================ + +[[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",width="50%",cols="1,6"] +|========================== +|Field Name |Description +|`kind` |`gerritcodereview#reviewer` +|`approvals` | +The approvals of the reviewer as a map that maps the label names to the +approval values ("`-2`", "`-1`", " `0`", "`+1`", "`+2`"). +|========================== + +[[reviewer-input]] +ReviewerInput +~~~~~~~~~~~~~ +The `ReviewerInput` entity contains information for adding a reviewer +to a change. + +[options="header",width="50%",cols="1,^1,5"] +|=========================== +|Field Name ||Description +|`reviewer` || +The link:rest-api-accounts.html#account-id[ID] of one account that +should be added as reviewer or the link:rest-api-groups.html#group-id[ +ID] of one group for which all members should be added as reviewers. + +If an ID identifies both an account and a group, only the account is +added as reviewer to the change. +|`confirmed` |optional| +Whether adding the reviewer is confirmed. + +The Gerrit server may be configured to +link:config-gerrit.html#addreviewer.maxWithoutConfirmation[require a +confirmation] when adding a group as reviewer that has many members. +|=========================== + +[[revision-info]] +RevisionInfo +~~~~~~~~~~~~ +The `RevisionInfo` entity contains information about a patch set. + +[options="header",width="50%",cols="1,^1,5"] +|=========================== +|Field Name ||Description +|`draft` |not set if `false`|Whether the patch set is a draft. +|`_number` ||The patch set number. +|`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. +|`commit` ||The commit of the patch set as +link:#commit-info[CommitInfo] entity. +|`files` || +The files of the patch set as a map that maps the file names to +link:#file-info[FileInfo] entities. +|=========================== + +[[rule-input]] +RuleInput +~~~~~~~~~ +The `RuleInput` entity contains information to test a Prolog rule. + +[options="header",width="50%",cols="1,^1,5"] +|=========================== +|Field Name ||Description +|`rule`|| +Prolog code to execute instead of the code in `refs/meta/config`. +|`filters`|`RUN` if not set| +When `RUN` filter rules in the parent projects are called to +post-process the results of the project specific rule. This +behavior matches how the rule will execute if installed. + +If `SKIP` the parent filters are not called, allowing the test +to return results from the input rule. +|=========================== + +[[submit-info]] +SubmitInfo +~~~~~~~~~~ +The `SubmitInfo` entity contains information about the change status +after submitting. + +[options="header",width="50%",cols="1,6"] +|========================== +|Field Name |Description +|`status` | +The status of the change after submitting, can be `MERGED` or +`SUBMITTED`. + +If `wait_for_merge` in the link:#submit-input[SubmitInput] was set to +`false` the returned status is `SUBMITTED` and the caller can't know +whether the change could be merged successfully. +|========================== + +[[submit-input]] +SubmitInput +~~~~~~~~~~~ +The `SubmitInput` entity contains information for submitting a change. + +[options="header",width="50%",cols="1,^1,5"] +|=========================== +|Field Name ||Description +|`wait_for_merge`|`false` if not set| +Whether the request should wait for the merge to complete. + +If `false` the request returns immediately after the change has been +added to the merge queue and the caller can't know whether the change +could be merged successfully. +|=========================== + +[[submit-record]] +SubmitRecord +~~~~~~~~~~~~ +The `SubmitRecord` entity describes results from a submit_rule. + +[options="header",width="50%",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. +|=========================== + +[[topic-input]] +TopicInput +~~~~~~~~~~ +The `TopicInput` entity contains information for setting a topic. + +[options="header",width="50%",cols="1,^1,5"] +|=========================== +|Field Name ||Description +|`topic` |optional|The topic. + +The topic will be deleted if not set. +|`message` |optional| +Message to be added as review comment to the change when setting the +topic. +|=========================== + + +GERRIT +------ +Part of link:index.html[Gerrit Code Review] |