= 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. To create a change the calling user must be allowed to link:access-control.html#category_push_review[upload to code review]. .Request ---- POST /changes/ HTTP/1.0 Content-Type: application/json; charset=UTF-8 { "project" : "myProject", "subject" : "Let's support 100% Gerrit workflow direct in browser", "branch" : "master", "topic" : "create-change-in-browser", "status" : "NEW" } ---- As response a link:#change-info[ChangeInfo] entity is returned that describes the resulting change. .Response ---- HTTP/1.1 201 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9941", "project": "myProject", "branch": "master", "topic": "create-change-in-browser", "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9941", "subject": "Let's support 100% Gerrit workflow direct in browser", "status": "NEW", "created": "2014-05-05 07:15:44.639000000", "updated": "2014-05-05 07:15:44.639000000", "mergeable": true, "insertions": 0, "deletions": 0, "_number": 4711, "owner": { "name": "John Doe" } } ---- [[list-changes]] === Query Changes -- 'GET /changes/' -- Queries changes visible to the caller. The link:user-search.html#_search_operators[query string] must be provided by the `q` parameter. The `n` parameter can be used to limit the returned results. As result a list of link:#change-info[ChangeInfo] entries is returned. The change output is sorted by the last update time, most recently updated to oldest updated. Query for open changes of watched projects: .Request ---- GET /changes/?q=status:open+is:watched&n=2 HTTP/1.0 ---- .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' [ { "id": "demo~master~Idaf5e098d70898b7119f6f4af5a6c13343d64b57", "project": "demo", "branch": "master", "change_id": "Idaf5e098d70898b7119f6f4af5a6c13343d64b57", "subject": "One change", "status": "NEW", "created": "2012-07-17 07:18:30.854000000", "updated": "2012-07-17 07:19:27.766000000", "mergeable": true, "insertions": 26, "deletions": 10, "_number": 1756, "owner": { "name": "John Doe" }, }, { "id": "demo~master~I09c8041b5867d5b33170316e2abc34b79bbb8501", "project": "demo", "branch": "master", "change_id": "I09c8041b5867d5b33170316e2abc34b79bbb8501", "subject": "Another change", "status": "NEW", "created": "2012-07-17 07:18:30.884000000", "updated": "2012-07-17 07:18:30.885000000", "mergeable": true, "insertions": 12, "deletions": 18, "_number": 1757, "owner": { "name": "John Doe" }, "_more_changes": true } ] ---- If the 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. Clients are allowed to specify more than one query by setting the `q` parameter multiple times. In this case the result is an array of arrays, one per query in the same order the queries were given in. .Query for the 25 most recent open changes of the projects that you watch **** get::/changes/?q=status:open+is:watched&n=25 **** Query that retrieves changes for a user's dashboard: .Request ---- GET /changes/?q=is:open+owner:self&q=is:open+reviewer:self+-owner:self&q=is:closed+owner:self+limit:5&o=LABELS HTTP/1.0 ---- .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' [ [ { "id": "demo~master~Idaf5e098d70898b7119f6f4af5a6c13343d64b57", "project": "demo", "branch": "master", "change_id": "Idaf5e098d70898b7119f6f4af5a6c13343d64b57", "subject": "One change", "status": "NEW", "created": "2012-07-17 07:18:30.854000000", "updated": "2012-07-17 07:19:27.766000000", "mergeable": true, "insertions": 4, "deletions": 7, "_number": 1756, "owner": { "name": "John Doe" }, "labels": { "Verified": {}, "Code-Review": {} } } ], [], [] ] ---- .Query the changes for your user dashboard **** get::/changes/?q=is:open+owner:self&q=is:open+reviewer:self+-owner:self&q=is:closed+owner:self+limit:5&o=LABELS **** [[query-options]] Additional fields can be obtained by adding `o` parameters, each option requires more database lookups and slows down the query response time to the client so they are generally disabled by default. Optional fields are: [[labels]] -- * `LABELS`: a summary of each label required for submit, and approvers that have granted (or rejected) with that label. -- [[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, all reviewers by state, and reviewers that may be removed by the current user. -- [[current-revision]] -- * `CURRENT_REVISION`: describe the current revision (patch set) of the change, including the commit SHA-1 and URLs to fetch from. -- [[all-revisions]] -- * `ALL_REVISIONS`: describe all revisions, not just current. -- [[download-commands]] -- * `DOWNLOAD_COMMANDS`: include the `commands` field in the link:#fetch-info[FetchInfo] for revisions. Only valid when the `CURRENT_REVISION` or `ALL_REVISIONS` option is selected. -- [[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_mergeable]] -- * `SKIP_MERGEABLE`: skip the `mergeable` field in link:#change-info[ChangeInfo]. For fast moving projects, this field must be recomputed often, which is slow for projects with big trees. -- [[submittable]] -- * `SUBMITTABLE`: include the `submittable` field in link:#change-info[ChangeInfo], which can be used to tell if the change is reviewed and ready for submit. -- [[web-links]] -- * `WEB_LINKS`: include the `web_links` field in link:#commit-info[CommitInfo], therefore only valid in combination with `CURRENT_COMMIT` or `ALL_COMMITS`. -- [[check]] -- * `CHECK`: include potential problems with the change. -- [[commit-footers]] -- * `COMMIT_FOOTERS`: include the full commit message with Gerrit-specific commit footers in the link:#revision-info[RevisionInfo]. -- [[push-certificates]] -- * `PUSH_CERTIFICATES`: include push certificate information in the link:#revision-info[RevisionInfo]. Ignored if signed push is not link:config-gerrit.html#receive.enableSignedPush[enabled] on the server. -- [[tracking-ids]] -- * `TRACKING_IDS`: include references to external tracking systems as link:#tracking-id-info[TrackingIdInfo]. -- .Request ---- GET /changes/?q=97&o=CURRENT_REVISION&o=CURRENT_COMMIT&o=CURRENT_FILES&o=DOWNLOAD_COMMANDS HTTP/1.0 ---- .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' [ { "id": "gerrit~master~I7ea46d2e2ee5c64c0d807677859cfb7d90b8966a", "project": "gerrit", "branch": "master", "change_id": "I7ea46d2e2ee5c64c0d807677859cfb7d90b8966a", "subject": "Use an EventBus to manage star icons", "status": "NEW", "created": "2012-04-25 00:52:25.580000000", "updated": "2012-04-25 00:52:25.586000000", "mergeable": true, "insertions": 16, "deletions": 7, "_number": 97, "owner": { "name": "Shawn Pearce" }, "current_revision": "184ebe53805e102605d11f6b143486d15c23a09c", "revisions": { "184ebe53805e102605d11f6b143486d15c23a09c": { "kind": "REWORK", "_number": 1, "ref": "refs/changes/97/97/1", "fetch": { "git": { "url": "git://localhost/gerrit", "ref": "refs/changes/97/97/1", "commands": { "Checkout": "git fetch git://localhost/gerrit refs/changes/97/97/1 \u0026\u0026 git checkout FETCH_HEAD", "Cherry-Pick": "git fetch git://localhost/gerrit refs/changes/97/97/1 \u0026\u0026 git cherry-pick FETCH_HEAD", "Format-Patch": "git fetch git://localhost/gerrit refs/changes/97/97/1 \u0026\u0026 git format-patch -1 --stdout FETCH_HEAD", "Pull": "git pull git://localhost/gerrit refs/changes/97/97/1" } }, "http": { "url": "http://myuser@127.0.0.1:8080/gerrit", "ref": "refs/changes/97/97/1", "commands": { "Checkout": "git fetch http://myuser@127.0.0.1:8080/gerrit refs/changes/97/97/1 \u0026\u0026 git checkout FETCH_HEAD", "Cherry-Pick": "git fetch http://myuser@127.0.0.1:8080/gerrit refs/changes/97/97/1 \u0026\u0026 git cherry-pick FETCH_HEAD", "Format-Patch": "git fetch http://myuser@127.0.0.1:8080/gerrit refs/changes/97/97/1 \u0026\u0026 git format-patch -1 --stdout FETCH_HEAD", "Pull": "git pull http://myuser@127.0.0.1:8080/gerrit refs/changes/97/97/1" } }, "ssh": { "url": "ssh://myuser@*:29418/gerrit", "ref": "refs/changes/97/97/1", "commands": { "Checkout": "git fetch ssh://myuser@*:29418/gerrit refs/changes/97/97/1 \u0026\u0026 git checkout FETCH_HEAD", "Cherry-Pick": "git fetch ssh://myuser@*:29418/gerrit refs/changes/97/97/1 \u0026\u0026 git cherry-pick FETCH_HEAD", "Format-Patch": "git fetch ssh://myuser@*:29418/gerrit refs/changes/97/97/1 \u0026\u0026 git format-patch -1 --stdout FETCH_HEAD", "Pull": "git pull ssh://myuser@*:29418/gerrit refs/changes/97/97/1" } } }, "commit": { "parents": [ { "commit": "1eee2c9d8f352483781e772f35dc586a69ff5646", "subject": "Migrate contributor agreements to All-Projects." } ], "author": { "name": "Shawn O. Pearce", "email": "sop@google.com", "date": "2012-04-24 18:08:08.000000000", "tz": -420 }, "committer": { "name": "Shawn O. Pearce", "email": "sop@google.com", "date": "2012-04-24 18:08:08.000000000", "tz": -420 }, "subject": "Use an EventBus to manage star icons", "message": "Use an EventBus to manage star icons\n\nImage widgets that need to ..." }, "files": { "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeCache.java": { "lines_deleted": 8, "size_delta": -412, "size": 7782 }, "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeDetailCache.java": { "lines_inserted": 1, "size_delta": 23, "size": 6762 }, "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeScreen.java": { "lines_inserted": 11, "lines_deleted": 19, "size_delta": -298, "size": 47023 }, "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeTable.java": { "lines_inserted": 23, "lines_deleted": 20, "size_delta": 132, "size": 17727 }, "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarCache.java": { "status": "D", "lines_deleted": 139, "size_delta": -5512, "size": 13098 }, "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarredChanges.java": { "status": "A", "lines_inserted": 204, "size_delta": 8345, "size": 8345 }, "gerrit-gwtui/src/main/java/com/google/gerrit/client/ui/Screen.java": { "lines_deleted": 9, "size_delta": -343, "size": 5385 } } } } } ] ---- [[get-change]] === Get Change -- 'GET /changes/link:#change-id[\{change-id\}]' -- Retrieves a change. Additional fields can be obtained by adding `o` parameters, each option requires more database lookups and slows down the query response time to the client so they are generally disabled by default. Fields are described in link:#list-changes[Query Changes]. .Request ---- GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940 HTTP/1.0 ---- As response a link:#change-info[ChangeInfo] entity is returned that describes the change. .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", "project": "myProject", "branch": "master", "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", "subject": "Implementing Feature X", "status": "NEW", "created": "2013-02-01 09:59:32.126000000", "updated": "2013-02-21 11:16:36.775000000", "mergeable": true, "insertions": 34, "deletions": 101, "_number": 3965, "owner": { "name": "John Doe" } } ---- [[get-change-detail]] === Get Change Detail -- 'GET /changes/link:#change-id[\{change-id\}]/detail' -- Retrieves a change with link:#labels[labels], link:#detailed-labels[ detailed labels], link:#detailed-accounts[detailed accounts], 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", "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", "subject": "Implementing Feature X", "status": "NEW", "created": "2013-02-01 09:59:32.126000000", "updated": "2013-02-21 11:16:36.775000000", "mergeable": true, "insertions": 126, "deletions": 11, "_number": 3965, "owner": { "_account_id": 1000096, "name": "John Doe", "email": "john.doe@example.com", "username": "jdoe" }, "labels": { "Verified": { "all": [ { "value": 0, "_account_id": 1000096, "name": "John Doe", "email": "john.doe@example.com", "username": "jdoe" }, { "value": 0, "_account_id": 1000097, "name": "Jane Roe", "email": "jane.roe@example.com", "username": "jroe" } ], "values": { "-1": "Fails", " 0": "No score", "+1": "Verified" } }, "Code-Review": { "disliked": { "_account_id": 1000096, "name": "John Doe", "email": "john.doe@example.com", "username": "jdoe" }, "all": [ { "value": -1, "_account_id": 1000096, "name": "John Doe", "email": "john.doe@example.com", "username": "jdoe" }, { "value": 1, "_account_id": 1000097, "name": "Jane Roe", "email": "jane.roe@example.com", "username": "jroe" } ] "values": { "-2": "This shall not be merged", "-1": "I would prefer this is not merged as is", " 0": "No score", "+1": "Looks good to me, but someone else must approve", "+2": "Looks good to me, approved" } } }, "permitted_labels": { "Verified": [ "-1", " 0", "+1" ], "Code-Review": [ "-2", "-1", " 0", "+1", "+2" ] }, "removable_reviewers": [ { "_account_id": 1000096, "name": "John Doe", "email": "john.doe@example.com", "username": "jdoe" }, { "_account_id": 1000097, "name": "Jane Roe", "email": "jane.roe@example.com", "username": "jroe" } ], "reviewers": { "REVIEWER": [ { "_account_id": 1000096, "name": "John Doe", "email": "john.doe@example.com", "username": "jdoe" }, { "_account_id": 1000097, "name": "Jane Roe", "email": "jane.roe@example.com", "username": "jroe" } ] }, "reviewer_updates": [ { "state": "REVIEWER", "reviewer": { "_account_id": 1000096, "name": "John Doe", "email": "john.doe@example.com", "username": "jdoe" }, "updated_by": { "_account_id": 1000096, "name": "John Doe", "email": "john.doe@example.com", "username": "jdoe" }, "updated": "2016-07-21 20:12:39.000000000" }, { "state": "REMOVED", "reviewer": { "_account_id": 1000096, "name": "John Doe", "email": "john.doe@example.com", "username": "jdoe" }, "updated_by": { "_account_id": 1000096, "name": "John Doe", "email": "john.doe@example.com", "username": "jdoe" }, "updated": "2016-07-21 20:12:33.000000000" }, { "state": "CC", "reviewer": { "_account_id": 1000096, "name": "John Doe", "email": "john.doe@example.com", "username": "jdoe" }, "updated_by": { "_account_id": 1000096, "name": "John Doe", "email": "john.doe@example.com", "username": "jdoe" }, "updated": "2016-03-23 21:34:02.419000000", }, ], "messages": [ { "id": "YH-egE", "author": { "_account_id": 1000096, "name": "John Doe", "email": "john.doe@example.com", "username": "jdoe" }, "date": "2013-03-23 21:34:02.419000000", "message": "Patch Set 1:\n\nThis is the first message.", "_revision_number": 1 }, { "id": "WEEdhU", "author": { "_account_id": 1000097, "name": "Jane Roe", "email": "jane.roe@example.com", "username": "jroe" }, "date": "2013-03-23 21:36:52.332000000", "message": "Patch Set 1:\n\nThis is the second message.\n\nWith a line break.", "_revision_number": 1 } ] } ---- [[create-merge-patch-set-for-change]] === Create Merge Patch Set For Change -- 'POST /changes/link:#change-id[\{change-id\}]/merge' -- Update an existing change by using a link:#merge-patch-set-input[MergePatchSetInput] entity. Gerrit will create a merge commit based on the information of MergePatchSetInput and add a new patch set to the change corresponding to the new merge commit. .Request ---- POST /changes/test~master~Ic5466d107c5294414710935a8ef3b0180fb848dc/merge HTTP/1.0 Content-Type: application/json; charset=UTF-8 { "subject": "Merge dev_branch into master", "merge": { "source": "refs/changes/34/1234/1" } } ---- As response a link:#change-info[ChangeInfo] entity with current revision is returned that describes the resulting change. .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "id": "test~master~Ic5466d107c5294414710935a8ef3b0180fb848dc", "project": "test", "branch": "master", "hashtags": [], "change_id": "Ic5466d107c5294414710935a8ef3b0180fb848dc", "subject": "Merge dev_branch into master", "status": "NEW", "created": "2016-09-23 18:08:53.238000000", "updated": "2016-09-23 18:09:25.934000000", "submit_type": "MERGE_IF_NECESSARY", "mergeable": true, "insertions": 5, "deletions": 0, "_number": 72, "owner": { "_account_id": 1000000 }, "current_revision": "27cc4558b5a3d3387dd11ee2df7a117e7e581822" } ---- [[set-message]] === Set Commit Message -- 'PUT /changes/link:#change-id[\{change-id\}]/message' -- Creates a new patch set with a new commit message. The new commit message must be provided in the request body inside a link:#commit-message-input[CommitMessageInput] entity and contain the change ID footer if link:project-configuration.html#require-change-id[Require Change-Id] was specified. .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. .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. 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 ---- [[get-assignee]] === Get Assignee -- 'GET /changes/link:#change-id[\{change-id\}]/assignee' -- Retrieves the account of the user assigned to a change. .Request ---- GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/assignee HTTP/1.0 ---- As a response an link:rest-api-accounts.html#account-info[AccountInfo] entity describing the assigned account is returned. .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "_account_id": 1000096, "name": "John Doe", "email": "john.doe@example.com", "username": "jdoe" } ---- If the change has no assignee the response is "`204 No Content`". [[get-past-assignees]] === Get Past Assignees -- 'GET /changes/link:#change-id[\{change-id\}]/past_assignees' -- Returns a list of every user ever assigned to a change, in the order in which they were first assigned. [NOTE] Past assignees are only available when NoteDb is enabled. .Request ---- GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/past_assignees HTTP/1.0 ---- As a response a list of link:rest-api-accounts.html#account-info[AccountInfo] entities is returned. .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' [ { "_account_id": 1000051, "name": "Jane Doe", "email": "jane.doe@example.com", "username": "janed" }, { "_account_id": 1000096, "name": "John Doe", "email": "john.doe@example.com", "username": "jdoe" } ] ---- [[set-assignee]] === Set Assignee -- 'PUT /changes/link:#change-id[\{change-id\}]/assignee' -- Sets the assignee of a change. The new assignee must be provided in the request body inside a link:#assignee-input[AssigneeInput] entity. .Request ---- PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/assignee HTTP/1.0 Content-Type: application/json; charset=UTF-8 { "assignee": "jdoe" } ---- As a response an link:rest-api-accounts.html#account-info[AccountInfo] entity describing the assigned account is returned. .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "_account_id": 1000096, "name": "John Doe", "email": "john.doe@example.com", "username": "jdoe" } ---- [[delete-assignee]] === Delete Assignee -- 'DELETE /changes/link:#change-id[\{change-id\}]/assignee' -- Deletes the assignee of a change. .Request ---- DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/assignee HTTP/1.0 ---- As a response an link:rest-api-accounts.html#account-info[AccountInfo] entity describing the account of the deleted assignee is returned. .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "_account_id": 1000096, "name": "John Doe", "email": "john.doe@example.com", "username": "jdoe" } ---- If the change had no assignee the response is "`204 No Content`". [[get-pure-revert]] === Get Pure Revert -- 'GET /changes/link:#change-id[\{change-id\}]/pure_revert' -- Check if the given change is a pure revert of the change it references in `revertOf`. Optionally, the query parameter `o` can be passed in to specify a commit (SHA1 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. .Request ---- POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/abandon HTTP/1.0 ---- As response a link:#change-info[ChangeInfo] entity is returned that describes the abandoned change. .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", "project": "myProject", "branch": "master", "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", "subject": "Implementing Feature X", "status": "ABANDONED", "created": "2013-02-01 09:59:32.126000000", "updated": "2013-02-21 11:16:36.775000000", "mergeable": true, "insertions": 3, "deletions": 310, "_number": 3965, "owner": { "name": "John Doe" } } ---- If the change cannot be abandoned because the change state doesn't allow abandoning of the change, the response is "`409 Conflict`" and the error message is contained in the response body. .Response ---- HTTP/1.1 409 Conflict Content-Disposition: attachment Content-Type: text/plain; charset=UTF-8 change is merged ---- .Notifications An email will be sent using the "abandon" template. The notify handling is ALL. Notifications are suppressed on WIP changes that have never started review. [options="header",cols="1,2"] |============================= |WIP State |notify=ALL |Ready for review|owner, reviewers, CCs, stars, ABANDONED_CHANGES watchers |Work in progress|not sent |Reviewable WIP |owner, reviewers, CCs, stars, ABANDONED_CHANGES watchers |============================= [[restore-change]] === Restore Change -- 'POST /changes/link:#change-id[\{change-id\}]/restore' -- Restores a change. The request body does not need to include a link:#restore-input[ RestoreInput] entity if no review comment is added. .Request ---- POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/restore HTTP/1.0 ---- As response a link:#change-info[ChangeInfo] entity is returned that describes the restored change. .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", "project": "myProject", "branch": "master", "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", "subject": "Implementing Feature X", "status": "NEW", "created": "2013-02-01 09:59:32.126000000", "updated": "2013-02-21 11:16:36.775000000", "mergeable": true, "insertions": 2, "deletions": 13, "_number": 3965, "owner": { "name": "John Doe" } } ---- If the change cannot be restored because the change state doesn't allow restoring the change, the response is "`409 Conflict`" and the error message is contained in the response body. .Response ---- HTTP/1.1 409 Conflict Content-Disposition: attachment Content-Type: text/plain; charset=UTF-8 change is new ---- [[rebase-change]] === Rebase Change -- 'POST /changes/link:#change-id[\{change-id\}]/rebase' -- Rebases a change. Optionally, the parent revision can be changed to another patch set through the link:#rebase-input[RebaseInput] entity. .Request ---- POST /changes/myProject~master~I3ea943139cb62e86071996f2480e58bf3eeb9dd2/rebase HTTP/1.0 Content-Type: application/json;charset=UTF-8 { "base" : "1234", } ---- As response a link:#change-info[ChangeInfo] entity is returned that describes the rebased change. Information about the current patch set is included. .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "id": "myProject~master~I3ea943139cb62e86071996f2480e58bf3eeb9dd2", "project": "myProject", "branch": "master", "change_id": "I3ea943139cb62e86071996f2480e58bf3eeb9dd2", "subject": "Implement Feature X", "status": "NEW", "created": "2013-02-01 09:59:32.126000000", "updated": "2013-02-21 11:16:36.775000000", "mergeable": false, "insertions": 33, "deletions": 9, "_number": 4799, "owner": { "name": "John Doe" }, "current_revision": "27cc4558b5a3d3387dd11ee2df7a117e7e581822", "revisions": { "27cc4558b5a3d3387dd11ee2df7a117e7e581822": { "kind": "REWORK", "_number": 2, "ref": "refs/changes/99/4799/2", "fetch": { "http": { "url": "http://gerrit:8080/myProject", "ref": "refs/changes/99/4799/2" } }, "commit": { "parents": [ { "commit": "b4003890dadd406d80222bf1ad8aca09a4876b70", "subject": "Implement Feature A" } ], "author": { "name": "John Doe", "email": "john.doe@example.com", "date": "2013-05-07 15:21:27.000000000", "tz": 120 }, "committer": { "name": "Gerrit Code Review", "email": "gerrit-server@example.com", "date": "2013-05-07 15:35:43.000000000", "tz": 120 }, "subject": "Implement Feature X", "message": "Implement Feature X\n\nAdded feature X." } } } ---- If the change cannot be rebased, e.g. due to conflicts, the response is "`409 Conflict`" and the error message is contained in the response body. .Response ---- HTTP/1.1 409 Conflict Content-Disposition: attachment Content-Type: text/plain; charset=UTF-8 The change could not be rebased due to a path conflict during merge. ---- [[move-change]] === Move Change -- 'POST /changes/link:#change-id[\{change-id\}]/move' -- Move a change. The destination branch must be provided in the request body inside a link:#move-input[MoveInput] entity. .Request ---- POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/move HTTP/1.0 Content-Type: application/json; charset=UTF-8 { "destination_branch" : "release-branch" } ---- As response a link:#change-info[ChangeInfo] entity is returned that describes the moved change. .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "id": "myProject~release-branch~I8473b95934b5732ac55d26311a706c9c2bde9940", "project": "myProject", "branch": "release-branch", "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", "subject": "Implementing Feature X", "status": "NEW", "created": "2013-02-01 09:59:32.126000000", "updated": "2013-02-21 11:16:36.775000000", "mergeable": true, "insertions": 2, "deletions": 13, "_number": 3965, "owner": { "name": "John Doe" } } ---- Note that this endpoint will not update the change's parents, which is different from the link:#cherry-pick[cherry-pick] endpoint. If the change cannot be moved because the change state doesn't allow moving the change, the response is "`409 Conflict`" and the error message is contained in the response body. .Response ---- HTTP/1.1 409 Conflict Content-Disposition: attachment Content-Type: text/plain; charset=UTF-8 change is merged ---- If the change cannot be moved because the user doesn't have abandon permission on the change or upload permission on the destination, the response is "`409 Conflict`" and the error message is contained in the response body. .Response ---- HTTP/1.1 409 Conflict Content-Disposition: attachment Content-Type: text/plain; charset=UTF-8 move not permitted ---- [[revert-change]] === Revert Change -- 'POST /changes/link:#change-id[\{change-id\}]/revert' -- Reverts a change. The request body does not need to include a link:#revert-input[ RevertInput] entity if no review comment is added. .Request ---- POST /changes/myProject~master~I1ffe09a505e25f15ce1521bcfb222e51e62c2a14/revert HTTP/1.0 ---- As response a link:#change-info[ChangeInfo] entity is returned that describes the reverting change. .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", "project": "myProject", "branch": "master", "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", "subject": "Revert \"Implementing Feature X\"", "status": "NEW", "created": "2013-02-01 09:59:32.126000000", "updated": "2013-02-21 11:16:36.775000000", "mergeable": true, "insertions": 6, "deletions": 4, "_number": 3965, "owner": { "name": "John Doe" } } ---- If the change cannot be reverted because the change state doesn't allow reverting the change, the response is "`409 Conflict`" and the error message is contained in the response body. .Response ---- HTTP/1.1 409 Conflict Content-Disposition: attachment Content-Type: text/plain; charset=UTF-8 change is new ---- [[submit-change]] === Submit Change -- 'POST /changes/link:#change-id[\{change-id\}]/submit' -- Submits a change. The request body only needs to include a link:#submit-input[ SubmitInput] entity if submitting on behalf of another user. .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. .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", "project": "myProject", "branch": "master", "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", "subject": "Implementing Feature X", "status": "MERGED", "created": "2013-02-01 09:59:32.126000000", "updated": "2013-02-21 11:16:36.775000000", "submitted": "2013-02-21 11:16:36.615000000", "_number": 3965, "owner": { "name": "John Doe" } } ---- If the change cannot be submitted because the submit rule doesn't allow submitting the change, the response is "`409 Conflict`" and the error message is contained in the response body. .Response ---- HTTP/1.1 409 Conflict Content-Disposition: attachment Content-Type: text/plain; charset=UTF-8 blocked by Verified ---- [[submitted-together]] === Changes Submitted Together -- 'GET /changes/link:#change-id[\{change-id\}]/submitted_together?o=NON_VISIBLE_CHANGES' -- Computes list of all changes which are submitted when link:#submit-change[Submit] is called for this change, including the current change itself. The list consists of: * The given change. * If link:config-gerrit.html#change.submitWholeTopic[`change.submitWholeTopic`] is enabled, include all open changes with the same topic. * For each change whose submit type is not CHERRY_PICK, include unmerged ancestors targeting the same branch. As a special case, the list is empty if this change would be submitted by itself (without other changes). .Request ---- GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/submitted_together?o=NON_VISIBLE_CHANGES HTTP/1.0 Content-Type: application/json; charset=UTF-8 ---- As a response a link:#submitted-together-info[SubmittedTogetherInfo] entity is returned that describes what would happen if the change were submitted. This response contains a list of changes and a count of changes that are not visible to the caller that are part of the set of changes to be merged. The listed changes use the same format as in link:#list-changes[Query Changes] with the link:#labels[`LABELS`], link:#detailed-labels[`DETAILED_LABELS`], link:#current-revision[`CURRENT_REVISION`],and link:#submittable[`SUBMITTABLE`] options set. Standard link:#query-options[formatting options] can be specified with the `o` parameter, as well as the `submitted_together` specific option `NON_VISIBLE_CHANGES`. .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "changes": [ { "id": "gerrit~master~I1ffe09a505e25f15ce1521bcfb222e51e62c2a14", "project": "gerrit", "branch": "master", "hashtags": [], "change_id": "I1ffe09a505e25f15ce1521bcfb222e51e62c2a14", "subject": "ChangeMergeQueue: Rewrite such that it works on set of changes", "status": "NEW", "created": "2015-05-01 15:39:57.979000000", "updated": "2015-05-20 19:25:21.592000000", "mergeable": true, "insertions": 303, "deletions": 210, "_number": 1779, "owner": { "_account_id": 1000000 }, "labels": { "Code-Review": { "approved": { "_account_id": 1000000 }, "all": [ { "value": 2, "date": "2015-05-20 19:25:21.592000000", "_account_id": 1000000 } ], "values": { "-2": "This shall not be merged", "-1": "I would prefer this is not merged as is", " 0": "No score", "+1": "Looks good to me, but someone else must approve", "+2": "Looks good to me, approved" }, "default_value": 0 }, "Verified": { "approved": { "_account_id": 1000000 }, "all": [ { "value": 1, "date": "2015-05-20 19:25:21.592000000", "_account_id": 1000000 } ], "values": { "-1": "Fails", " 0": "No score", "+1": "Verified" }, "default_value": 0 } }, "permitted_labels": { "Code-Review": [ "-2", "-1", " 0", "+1", "+2" ], "Verified": [ "-1", " 0", "+1" ] }, "removable_reviewers": [ { "_account_id": 1000000 } ], "reviewers": { "REVIEWER": [ { "_account_id": 1000000 } ] }, "current_revision": "9adb9f4c7b40eeee0646e235de818d09164d7379", "revisions": { "9adb9f4c7b40eeee0646e235de818d09164d7379": { "kind": "REWORK", "_number": 1, "created": "2015-05-01 15:39:57.979000000", "uploader": { "_account_id": 1000000 }, "ref": "refs/changes/79/1779/1", "fetch": {}, } } }, { "id": "gerrit~master~I7fe807e63792b3d26776fd1422e5e790a5697e22", "project": "gerrit", "branch": "master", "hashtags": [], "change_id": "I7fe807e63792b3d26776fd1422e5e790a5697e22", "subject": "AbstractSubmoduleSubscription: Split up createSubscription", "status": "NEW", "created": "2015-05-01 15:39:57.979000000", "updated": "2015-05-20 19:25:21.546000000", "mergeable": true, "insertions": 15, "deletions": 6, "_number": 1780, "owner": { "_account_id": 1000000 }, "labels": { "Code-Review": { "approved": { "_account_id": 1000000 }, "all": [ { "value": 2, "date": "2015-05-20 19:25:21.546000000", "_account_id": 1000000 } ], "values": { "-2": "This shall not be merged", "-1": "I would prefer this is not merged as is", " 0": "No score", "+1": "Looks good to me, but someone else must approve", "+2": "Looks good to me, approved" }, "default_value": 0 }, "Verified": { "approved": { "_account_id": 1000000 }, "all": [ { "value": 1, "date": "2015-05-20 19:25:21.546000000", "_account_id": 1000000 } ], "values": { "-1": "Fails", " 0": "No score", "+1": "Verified" }, "default_value": 0 } }, "permitted_labels": { "Code-Review": [ "-2", "-1", " 0", "+1", "+2" ], "Verified": [ "-1", " 0", "+1" ] }, "removable_reviewers": [ { "_account_id": 1000000 } ], "reviewers": { "REVIEWER": [ { "_account_id": 1000000 } ] }, "current_revision": "1bd7c12a38854a2c6de426feec28800623f492c4", "revisions": { "1bd7c12a38854a2c6de426feec28800623f492c4": { "kind": "REWORK", "_number": 1, "created": "2015-05-01 15:39:57.979000000", "uploader": { "_account_id": 1000000 }, "ref": "refs/changes/80/1780/1", "fetch": {}, } } } ], "non_visible_changes": 0 } ---- If the `o=NON_VISIBLE_CHANGES` query parameter is not passed, then instead of a link:#submitted-together-info[SubmittedTogetherInfo] entity, the response is a list of changes, or a 403 response with a message if the set of changes to be submitted with this change includes changes the caller cannot read. [[delete-change]] === Delete Change -- 'DELETE /changes/link:#change-id[\{change-id\}]' -- Deletes a change. New or abandoned changes can be deleted by their owner if the user is granted the link:access-control.html#category_delete_own_changes[Delete Own Changes] permission, otherwise only by administrators. .Request ---- DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940 HTTP/1.0 Content-Type: application/json; charset=UTF-8 ---- .Response ---- HTTP/1.1 204 No Content ---- [[get-included-in]] === Get Included In -- 'GET /changes/link:#change-id[\{change-id\}]/in' -- Retrieves the branches and tags in which a change is included. As result an link:#included-in-info[IncludedInInfo] entity is returned. .Request ---- GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/in HTTP/1.0 ---- .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "branches": [ "master" ], "tags": [] } ---- [[index-change]] === Index Change -- 'POST /changes/link:#change-id[\{change-id\}]/index' -- Adds or updates the change in the secondary index. .Request ---- POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/index HTTP/1.0 ---- .Response ---- HTTP/1.1 204 No Content ---- [[list-change-comments]] === List Change Comments -- 'GET /changes/link:#change-id[\{change-id\}]/comments' -- Lists the published comments of all revisions of the change. Returns a map of file paths to lists of link:#comment-info[CommentInfo] entries. The entries in the map are sorted by file path, and the comments for each path are sorted by patch set number. Each comment has the `patch_set` and `author` fields set. .Request ---- GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/comments HTTP/1.0 ---- .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": [ { "patch_set": 1, "id": "TvcXrmjM", "line": 23, "message": "[nit] trailing whitespace", "updated": "2013-02-26 15:40:43.986000000" "author": { "_account_id": 1000096, "name": "John Doe", "email": "john.doe@example.com" } }, { "patch_set": 2, "id": "TveXwFiA", "line": 49, "in_reply_to": "TfYX-Iuo", "message": "Done", "updated": "2013-02-26 15:40:45.328000000" "author": { "_account_id": 1000097, "name": "Jane Roe", "email": "jane.roe@example.com" } } ] } ---- [[list-change-robot-comments]] === List Change Robot Comments -- 'GET /changes/link:#change-id[\{change-id\}]/robotcomments' -- Lists the robot comments of all revisions of the change. Return a map that maps the file path to a list of link:#robot-comment-info[RobotCommentInfo] entries. The entries in the map are sorted by file path. .Request ---- GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/robotcomments/ HTTP/1.0 ---- .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": [ { "id": "TvcXrmjM", "line": 23, "message": "unused import", "updated": "2016-02-26 15:40:43.986000000", "author": { "_account_id": 1000110, "name": "Code Analyzer", "email": "code.analyzer@example.com" }, "robotId": "importChecker", "robotRunId": "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" }, "robotId": "styleChecker", "robotRunId": "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`. .Request ---- GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/drafts HTTP/1.0 ---- .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": [ { "patch_set": 1, "id": "TvcXrmjM", "line": 23, "message": "[nit] trailing whitespace", "updated": "2013-02-26 15:40:43.986000000" }, { "patch_set": 2, "id": "TveXwFiA", "line": 49, "in_reply_to": "TfYX-Iuo", "message": "Done", "updated": "2013-02-26 15:40:45.328000000" } ] } ---- [[check-change]] === Check Change -- 'GET /changes/link:#change-id[\{change-id\}]/check' -- Performs consistency checks on the change, and returns a link:#change-info[ChangeInfo] entity with the `problems` field set to a list of link:#problem-info[ProblemInfo] entities. Depending on the type of problem, some fields not marked optional may be missing from the result. At least `id`, `project`, `branch`, and `_number` will be present. .Request ---- GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/check HTTP/1.0 ---- .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", "project": "myProject", "branch": "master", "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", "subject": "Implementing Feature X", "status": "NEW", "created": "2013-02-01 09:59:32.126000000", "updated": "2013-02-21 11:16:36.775000000", "mergeable": true, "insertions": 34, "deletions": 101, "_number": 3965, "owner": { "name": "John Doe" }, "problems": [ { "message": "Current patch set 1 not found" } ] } ---- [[fix-change]] === Fix Change -- 'POST /changes/link:#change-id[\{change-id\}]/check' -- Performs consistency checks on the change as with link:#check-change[GET /check], and additionally fixes any problems that can be fixed automatically. The returned field values reflect any fixes. Some fixes have options controlling their behavior, which can be set in the link:#fix-input[FixInput] entity body. Only the change owner, a project owner, or an administrator may fix changes. .Request ---- POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/check HTTP/1.0 ---- .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", "project": "myProject", "branch": "master", "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", "subject": "Implementing Feature X", "status": "MERGED", "created": "2013-02-01 09:59:32.126000000", "updated": "2013-02-21 11:16:36.775000000", "submitted": "2013-02-21 11:16:36.615000000", "mergeable": true, "insertions": 34, "deletions": 101, "_number": 3965, "owner": { "name": "John Doe" }, "problems": [ { "message": "Current patch set 2 not found" }, { "message": "Patch set 1 (1eee2c9d8f352483781e772f35dc586a69ff5646) is merged into destination ref master (1eee2c9d8f352483781e772f35dc586a69ff5646), but change status is NEW", "status": FIXED, "outcome": "Marked change as merged" } ] } ---- [[set-work-in-pogress]] === Set Work-In-Progress -- 'POST /changes/link:#change-id[\{change-id\}]/wip' -- Marks the change as not ready for review yet. Changes may only be marked not ready by the owner, project owners or site administrators. The request body does not need to include a link:#work-in-progress-input[WorkInProgressInput] entity if no review comment is added. Actions that create a new patch set in a WIP change default to notifying *OWNER* instead of *ALL*. .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. .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. 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. A message can be specified in the request body inside a link:#private-input[PrivateInput] entity. .Request ---- DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/private HTTP/1.0 Content-Type: application/json; charset=UTF-8 { "message": "This is a security fix that must not be public." } ---- .Response ---- HTTP/1.1 204 No Content ---- If the change was already not private, the response is "`409 Conflict`". Please note that some proxies prohibit request bodies for DELETE requests. In this case, if you want to set a message options, use a POST request: .Request ---- POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/private.delete HTTP/1.0 Content-Type: application/json; charset=UTF-8 { "message": "This is a security fix that must not be public." } ---- [[ignore]] === Ignore -- 'PUT /changes/link:#change-id[\{change-id\}]/ignore' -- Marks a change as ignored. The change will not be shown in the incoming reviews dashboard, and email notifications will be suppressed. .Request ---- PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/ignore HTTP/1.0 ---- [[unignore]] === Unignore -- 'PUT /changes/link:#change-id[\{change-id\}]/unignore' -- Un-marks a change as ignored. .Request ---- PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/unignore HTTP/1.0 ---- [[mark-as-reviewed]] === Mark as Reviewed -- 'PUT /changes/link:#change-id[\{change-id\}]/reviewed' -- Marks a change as reviewed. This allows users to "de-highlight" changes in their dashboard until a new patch set is uploaded. This differs from the link:#ignore[ignore] endpoint, which will mute emails and hide the change from dashboard completely until it is link:#unignore[unignored] again. .Request ---- PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewed HTTP/1.0 ---- [[mark-as-unreviewed]] === Mark as Unreviewed -- 'PUT /changes/link:#change-id[\{change-id\}]/unreviewed' -- Marks a change as unreviewed. This allows users to "highlight" changes in their dashboard .Request ---- PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/unreviewed HTTP/1.0 ---- [[get-hashtags]] === Get Hashtags -- 'GET /changes/link:#change-id[\{change-id\}]/hashtags' -- Gets the hashtags associated with a change. [NOTE] Hashtags are only available when NoteDb is enabled. .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. [NOTE] Hashtags are only available when NoteDb is enabled. The hashtags to add or remove must be provided in the request body inside a link:#hashtags-input[HashtagsInput] entity. .Request ---- POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/hashtags HTTP/1.0 Content-Type: application/json; charset=UTF-8 { "add" : [ "hashtag3" ], "remove" : [ "hashtag2" ] } ---- As response the change's hashtags are returned as a list of strings. .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' [ "hashtag1", "hashtag3" ] ---- [[list-change-messages]] === List Change Messages -- 'GET /changes/link:#change-id[\{change-id\}]/messages' -- Lists all the messages of a change including link:#detailed-accounts[detailed account information]. .Request ---- GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/messages ---- As response a list of link:#change-message-info[ChangeMessageInfo] entities is returned. .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' [ { "id": "YH-egE", "author": { "_account_id": 1000096, "name": "John Doe", "email": "john.doe@example.com", "username": "jdoe" }, "date": "2013-03-23 21:34:02.419000000", "message": "Patch Set 1:\n\nThis is the first message.", "_revision_number": 1 }, { "id": "WEEdhU", "author": { "_account_id": 1000097, "name": "Jane Roe", "email": "jane.roe@example.com", "username": "jroe" }, "date": "2013-03-23 21:36:52.332000000", "message": "Patch Set 1:\n\nThis is the second message.\n\nWith a line break.", "_revision_number": 1 } ] ---- [[get-change-message]] === Get Change Message Retrieves a change message including link:#detailed-accounts[detailed account information]. -- 'GET /changes/link:#change-id[\{change-id\}]/message/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": "Change message removed by: Administrator; Reason: spam", "_revision_number": 1 } ---- [[edit-endpoints]] == Change Edit Endpoints [[get-edit-detail]] === Get Change Edit Details -- 'GET /changes/link:#change-id[\{change-id\}]/edit -- Retrieves a change edit details. .Request ---- GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit HTTP/1.0 ---- As response an link:#edit-info[EditInfo] entity is returned that describes the change edit, or "`204 No Content`" when change edit doesn't exist for this change. Change edits are stored on special branches and there can be max one edit per user per change. Edits aren't tracked in the database. When request parameter `list` is provided the response also includes the file list. When `base` request parameter is provided the file list is computed against this base revision. When request parameter `download-commands` is provided fetch info map is also included. .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "commit":{ "parents":[ { "commit":"1eee2c9d8f352483781e772f35dc586a69ff5646", } ], "author":{ "name":"Shawn O. Pearce", "email":"sop@google.com", "date":"2012-04-24 18:08:08.000000000", "tz":-420 }, "committer":{ "name":"Shawn O. Pearce", "email":"sop@google.com", "date":"2012-04-24 18:08:08.000000000", "tz":-420 }, "subject":"Use an EventBus to manage star icons", "message":"Use an EventBus to manage star icons\n\nImage widgets that need to ..." }, "base_revision":"c35558e0925e6985c91f3a16921537d5e572b7a3" } ---- [[put-edit-file]] === Change file content in Change Edit -- 'PUT /changes/link:#change-id[\{change-id\}]/edit/path%2fto%2ffile -- Put content of a file to a change edit. .Request ---- PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit/foo HTTP/1.0 ---- When change edit doesn't exist for this change yet it is created. When file content isn't provided, it is wiped out for that file. As response "`204 No Content`" is returned. .Response ---- HTTP/1.1 204 No Content ---- [[post-edit]] === Restore file content or rename files in Change Edit -- 'POST /changes/link:#change-id[\{change-id\}]/edit -- Creates empty change edit, restores file content or renames files in change edit. The request body needs to include a link:#change-edit-input[ChangeEditInput] entity when a file within change edit should be restored or old and new file names to rename a file. .Request ---- POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit HTTP/1.0 Content-Type: application/json; charset=UTF-8 { "restore_path": "foo" } ---- or for rename: .Request ---- POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit HTTP/1.0 Content-Type: application/json; charset=UTF-8 { "old_path": "foo", "new_path": "bar" } ---- When change edit doesn't exist for this change yet it is created. When path and restore flag are provided in request body, this file is restored. When old and new file names are provided, the file is renamed. As response "`204 No Content`" is returned. .Response ---- HTTP/1.1 204 No Content ---- [[put-change-edit-message]] === Change commit message in Change Edit -- 'PUT /changes/link:#change-id[\{change-id\}]/edit:message -- Modify commit message. The request body needs to include a link:#change-edit-message-input[ChangeEditMessageInput] entity. .Request ---- PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit:message HTTP/1.0 Content-Type: application/json; charset=UTF-8 { "message": "New commit message\n\nChange-Id: I10394472cbd17dd12454f229e4f6de00b143a444" } ---- If a change edit doesn't exist for this change yet, it is created. As response "`204 No Content`" is returned. .Response ---- HTTP/1.1 204 No Content ---- [[delete-edit-file]] === Delete file in Change Edit -- 'DELETE /changes/link:#change-id[\{change-id\}]/edit/path%2fto%2ffile' -- Deletes a file from a change edit. This deletes the file from the repository completely. This is not the same as reverting or restoring a file to its previous contents. .Request ---- DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit/foo HTTP/1.0 ---- When change edit doesn't exist for this change yet it is created. .Response ---- HTTP/1.1 204 No Content ---- [[get-edit-file]] === Retrieve file content from Change Edit -- 'GET /changes/link:#change-id[\{change-id\}]/edit/path%2fto%2ffile -- Retrieves content of a file from a change edit. .Request ---- GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit/foo HTTP/1.0 ---- The content of the file is returned as text encoded inside base64. The Content-Type header will always be `text/plain` reflecting the outer base64 encoding. A Gerrit-specific `X-FYI-Content-Type` header can be examined to find the server detected content type of the file. When the specified file was deleted in the change edit "`204 No Content`" is returned. If only the content type is required, callers should use HEAD to avoid downloading the encoded file contents. If the `base` parameter is set to true, the returned content is from the revision that the edit is based on. .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: text/plain; charset=ISO-8859-1 X-FYI-Content-Encoding: base64 X-FYI-Content-Type: text/xml RnJvbSA3ZGFkY2MxNTNmZGVhMTdhYTg0ZmYzMmE2ZTI0NWRiYjY... ---- Alternatively, if the only value of the Accept request header is `application/json` the content is returned as JSON string and `X-FYI-Content-Encoding` is set to `json`. [[get-edit-meta-data]] === Retrieve meta data of a file from Change Edit -- 'GET /changes/link:#change-id[\{change-id\}]/edit/path%2fto%2ffile/meta -- Retrieves meta data of a file from a change edit. Currently only web links are returned. .Request ---- GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit/foo/meta HTTP/1.0 ---- This REST endpoint retrieves additional information for a file in a change edit. As result an link:#edit-file-info[EditFileInfo] entity is returned. .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "web_links":[ { "show_on_side_by_side_diff_view": true, "name": "side-by-side preview diff", "image_url": "plugins/xdocs/static/sideBySideDiffPreview.png", "url": "#/x/xdocs/c/42/1..0/README.md", "target": "_self" }, { "show_on_unified_diff_view": true, "name": "unified preview diff", "image_url": "plugins/xdocs/static/unifiedDiffPreview.png", "url": "#/x/xdocs/c/42/1..0/README.md,unified", "target": "_self" } ]} ---- [[get-edit-message]] === Retrieve commit message from Change Edit or current patch set of the change -- 'GET /changes/link:#change-id[\{change-id\}]/edit:message -- Retrieves commit message from change edit. If the `base` parameter is set to true, the returned message is from the revision that the edit is based on. .Request ---- GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit:message HTTP/1.0 ---- The commit message is returned as base64 encoded string. .Response ---- HTTP/1.1 200 OK VGhpcyBpcyBhIGNvbW1pdCBtZXNzYWdlCgpDaGFuZ2UtSWQ6IElhYzhmZGM1MGRlZjFiYWUzYjAz M2JhNjcxZTk0OTBmNzUxNDU5ZGUzCg== ---- Alternatively, if the only value of the Accept request header is `application/json` the commit message is returned as JSON string: .Response ---- HTTP/1.1 200 OK )]}' "Subject of the commit message\n\nThis is the body of the commit message.\n\nChange-Id: Iaf1ba916bf843c175673d675bf7f52862f452db9\n" ---- [[publish-edit]] === Publish Change Edit -- 'POST /changes/link:#change-id[\{change-id\}]/edit:publish -- Promotes change edit to a regular patch set. Options can be provided in the request body as a link:#publish-change-edit-input[PublishChangeEditInput] entity. .Request ---- POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit:publish HTTP/1.0 Content-Type: application/json; charset=UTF-8 { "notify": "NONE" } ---- As response "`204 No Content`" is returned. .Response ---- HTTP/1.1 204 No Content ---- [[rebase-edit]] === Rebase Change Edit -- 'POST /changes/link:#change-id[\{change-id\}]/edit:rebase -- Rebases change edit on top of latest patch set. .Request ---- POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit:rebase HTTP/1.0 ---- When change was rebased on top of latest patch set, response "`204 No Content`" is returned. When change edit is already based on top of the latest patch set, the response "`409 Conflict`" is returned. .Response ---- HTTP/1.1 204 No Content ---- [[delete-edit]] === Delete Change Edit -- 'DELETE /changes/link:#change-id[\{change-id\}]/edit' -- Deletes change edit. .Request ---- DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit HTTP/1.0 ---- As response "`204 No Content`" is returned. .Response ---- HTTP/1.1 204 No Content ---- [[reviewer-endpoints]] == Reviewer Endpoints [[list-reviewers]] === List Reviewers -- 'GET /changes/link:#change-id[\{change-id\}]/reviewers/' -- Lists the reviewers of a change. As result a list of link:#reviewer-info[ReviewerInfo] entries is returned. .Request ---- GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/ HTTP/1.0 ---- .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' [ { "approvals": { "Verified": "+1", "Code-Review": "+2" }, "_account_id": 1000096, "name": "John Doe", "email": "john.doe@example.com" }, { "approvals": { "Verified": " 0", "Code-Review": "-1" }, "_account_id": 1000097, "name": "Jane Roe", "email": "jane.roe@example.com" } ] ---- [[suggest-reviewers]] === Suggest Reviewers -- 'GET /changes/link:#change-id[\{change-id\}]/suggest_reviewers?q=J&n=5' -- Suggest the reviewers for a given query `q` and result limit `n`. If result limit is not passed, then the default 10 is used. Groups can be excluded from the results by specifying 'e=f'. 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 } ] ---- [[get-reviewer]] === Get Reviewer -- 'GET /changes/link:#change-id[\{change-id\}]/reviewers/link:rest-api-accounts.html#account-id[\{account-id\}]' -- Retrieves a reviewer of a change. As response a link:#reviewer-info[ReviewerInfo] entity is returned that describes the reviewer. .Request ---- GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/john.doe@example.com HTTP/1.0 ---- .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "approvals": { "Verified": "+1", "Code-Review": "+2" }, "_account_id": 1000096, "name": "John Doe", "email": "john.doe@example.com" } ---- [[add-reviewer]] === Add Reviewer -- 'POST /changes/link:#change-id[\{change-id\}]/reviewers' -- Adds one user or all members of one group as reviewer to the change. The reviewer to be added to the change must be provided in the request body as a link:#reviewer-input[ReviewerInput] entity. .Request ---- POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers HTTP/1.0 Content-Type: application/json; charset=UTF-8 { "reviewer": "john.doe@example.com" } ---- As response an link:#add-reviewer-result[AddReviewerResult] entity is returned that describes the newly added reviewers. .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "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. .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 " 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 " } ---- .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "input": "John Doe " } ---- .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. Options can be provided in the request body as a link:#delete-reviewer-input[DeleteReviewerInput] entity. .Request ---- DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe HTTP/1.0 POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe/delete HTTP/1.0 ---- Please note that some proxies prohibit request bodies for DELETE requests. In this case, if you want to specify options, use a POST request: .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. Options can be provided in the request body as a link:#delete-vote-input[DeleteVoteInput] entity. .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 ---- Please note that some proxies prohibit request bodies for DELETE requests. In this case, if you want to specify options, use a POST request: .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 actions mapped to their link:#action-info[ActionInfo]. [[get-review]] === Get Review -- 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/review' -- Retrieves a review of a revision. .Request ---- GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/review HTTP/1.0 ---- As response a link:#change-info[ChangeInfo] entity with link:#detailed-labels[detailed labels] and link:#detailed-accounts[ detailed accounts] is returned that describes the review of the revision. The revision for which the review is retrieved is contained in the `revisions` field. In addition the `current_revision` field is set if the revision for which the review is retrieved is the current revision of the change. Please note that the returned labels are always for the current patch set. .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", "project": "myProject", "branch": "master", "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", "subject": "Implementing Feature X", "status": "NEW", "created": "2013-02-01 09:59:32.126000000", "updated": "2013-02-21 11:16:36.775000000", "mergeable": true, "insertions": 34, "deletions": 45, "_number": 3965, "owner": { "_account_id": 1000096, "name": "John Doe", "email": "john.doe@example.com" }, "labels": { "Verified": { "all": [ { "value": 0, "_account_id": 1000096, "name": "John Doe", "email": "john.doe@example.com" }, { "value": 0, "_account_id": 1000097, "name": "Jane Roe", "email": "jane.roe@example.com" } ], "values": { "-1": "Fails", " 0": "No score", "+1": "Verified" } }, "Code-Review": { "all": [ { "value": -1, "_account_id": 1000096, "name": "John Doe", "email": "john.doe@example.com" }, { "value": 1, "_account_id": 1000097, "name": "Jane Roe", "email": "jane.roe@example.com" } ] "values": { "-2": "This shall not be merged", "-1": "I would prefer this is not merged as is", " 0": "No score", "+1": "Looks good to me, but someone else must approve", "+2": "Looks good to me, approved" } } }, "permitted_labels": { "Verified": [ "-1", " 0", "+1" ], "Code-Review": [ "-2", "-1", " 0", "+1", "+2" ] }, "removable_reviewers": [ { "_account_id": 1000096, "name": "John Doe", "email": "john.doe@example.com" }, { "_account_id": 1000097, "name": "Jane Roe", "email": "jane.roe@example.com" } ], "reviewers": { "REVIEWER": [ { "_account_id": 1000096, "name": "John Doe", "email": "john.doe@example.com" }, { "_account_id": 1000097, "name": "Jane Roe", "email": "jane.roe@example.com" } ] }, "current_revision": "674ac754f91e64a0efb8087e59a176484bd534d1", "revisions": { "674ac754f91e64a0efb8087e59a176484bd534d1": { "kind": "REWORK", "_number": 2, "ref": "refs/changes/65/3965/2", "fetch": { "http": { "url": "http://gerrit/myProject", "ref": "refs/changes/65/3965/2" } } } } } ---- [[get-related-changes]] === Get Related Changes -- 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/related' -- Retrieves related changes of a revision. Related changes are changes that either depend on, or are dependencies of the revision. .Request ---- GET /changes/gerrit~master~I5e4fc08ce34d33c090c9e0bf320de1b17309f774/revisions/b1cb4caa6be46d12b94c25aa68aebabcbb3f53fe/related HTTP/1.0 ---- As result a link:#related-changes-info[RelatedChangesInfo] entity is returned describing the related changes. .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "changes": [ { "project": "gerrit", "change_id": "Ic62ae3103fca2214904dbf2faf4c861b5f0ae9b5", "commit": { "commit": "78847477532e386f5a2185a4e8c90b2509e354e3", "parents": [ { "commit": "bb499510bbcdbc9164d96b0dbabb4aa45f59a87e" } ], "author": { "name": "David Ostrovsky", "email": "david@ostrovsky.org", "date": "2014-07-12 15:04:24.000000000", "tz": 120 }, "subject": "Remove Solr" }, "_change_number": 58478, "_revision_number": 2, "_current_revision_number": 2 "status": "NEW" }, { "project": "gerrit", "change_id": "I5e4fc08ce34d33c090c9e0bf320de1b17309f774", "commit": { "commit": "b1cb4caa6be46d12b94c25aa68aebabcbb3f53fe", "parents": [ { "commit": "d898f12a9b7a92eb37e7a80636195a1b06417aad" } ], "author": { "name": "David Pursehouse", "email": "david.pursehouse@sonymobile.com", "date": "2014-06-24 02:01:28.000000000", "tz": 540 }, "subject": "Add support for secondary index with Elasticsearch" }, "_change_number": 58081, "_revision_number": 10, "_current_revision_number": 10 "status": "NEW" } ] } ---- [[set-review]] === Set Review -- 'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/review' -- Sets a review on a revision, optionally also publishing draft comments, setting labels, adding reviewers or CCs, and modifying the work in progress property. The review must be provided in the request body as a link:#review-input[ReviewInput] entity. 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:#add-reviewer-result[AddReviewerResult]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": "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. .Request ---- POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/submit HTTP/1.0 Content-Type: application/json; charset=UTF-8 ---- 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-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. [[submit-preview]] === Submit Preview -- 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/preview_submit' -- Gets a file containing thin bundles of all modified projects if this change was submitted. The bundles are named `${ProjectName}.git`. Each thin bundle contains enough to construct the state in which a project would be in if this change were submitted. The base of the thin bundles are the current target branches, so to make use of this call in a non-racy way, first get the bundles and then fetch all projects contained in the bundle. (This assumes no non-fastforward pushes). You need to give a parameter '?format=zip' or '?format=tar' to specify the format for the outer container. It is always possible to use tgz, even if tgz is not in the list of allowed archive formats. To make good use of this call, you would roughly need code as found at: ---- $ curl -Lo preview_submit_test.sh http://review.example.com:8080/tools/scripts/preview_submit_test.sh ---- .Request ---- GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/preview_submit?zip HTTP/1.0 ---- .Response ---- HTTP/1.1 200 OK Date: Tue, 13 Sep 2016 19:13:46 GMT Content-Disposition: attachment; filename="submit-preview-147.zip" X-Content-Type-Options: nosniff Cache-Control: no-cache, no-store, max-age=0, must-revalidate Pragma: no-cache Expires: Mon, 01 Jan 1990 00:00:00 GMT Content-Type: application/x-zip Transfer-Encoding: chunked [binary stuff] ---- In case of an error, the response is not a zip file but a regular json response, containing only the error message: .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' "Anonymous users cannot submit" ---- [[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 list of link:#submit-record[SubmitRecord] entries describing the permutations that satisfy the tested submit rule. .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' [ { "status": "NOT_READY", "reject": { "Any-Label-Name": {} } } ] ---- When testing with the `curl` command line client the `--data-binary @rules.pl` flag should be used to ensure all LFs are included in the Prolog code: ---- curl -X POST \ -H 'Content-Type: text/plain; charset=UTF-8' \ --data-binary @rules.pl \ http://.../test.submit_rule ---- [[list-drafts]] === List 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. The reason can be provided in the request body as a link:#delete-comment-input[DeleteCommentInput] entity. Note that only users with the link:access-control.html#capability_administrateServer[Administrate Server] global capability are permitted to delete a comment. Please note that some proxies prohibit request bodies for DELETE requests. In this case, if you want to specify options, use a POST request: .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 -- '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" }, "robotId": "importChecker", "robotRunId": "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" }, "robotId": "styleChecker", "robotRunId": "5c606c425dd45184484f9d0a2ffd725a7607839b" } ] } ---- [[get-robot-comment]] === Get Robot Comment -- '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" }, "robotId": "importChecker", "robotRunId": "76b1375aa8626ea7149792831fe2ed85e80d9e04" } ---- [[apply-fix]] === Apply Fix -- 'POST /changes/<>/revisions/<>/fixes/<>/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. .Request ---- POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/fixes/8f605a55_f6aa4ecc/apply HTTP/1.0 ---- If the fix was successfully applied, an <> 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_revision":"674ac754f91e64a0efb8087e59a176484bd534d1" } ---- 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 The existing change edit could not be merged with another tree. ---- [[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 list of link:#file-info[FileInfo] entries. The entries in the map are sorted by file path. .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "/COMMIT_MSG": { "status": "A", "lines_inserted": 7, "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. The integer-valued request parameter `parent` changes the response to return a list of the files which are different in this commit compared to the given parent commit. 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/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. [[weblinks-only]] If the `weblinks-only` parameter is specified, only the diff web links are returned. .Request ---- GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/b6b9c10649b9041884046119ab794374470a1b45/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/diff?base=2 HTTP/1.0 ---- .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )] { "meta_a": { "name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", "content_type": "text/x-java-source", "lines": 578 }, "meta_b": { "name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", "content_type": "text/x-java-source", "lines": 578 }, "change_type": "MODIFIED", "content": [ { "skip": 578 } ] } ---- The `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`. The `context` parameter can be specified to control the number of lines of surrounding context in the diff. Valid values are `ALL` or number of lines. [[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. 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. .Request ---- POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/cherrypick HTTP/1.0 Content-Type: application/json; charset=UTF-8 { "message" : "Implementing Feature X", "destination" : "release-branch" } ---- As response a link:#change-info[ChangeInfo] entity is returned that describes the resulting cherry picked change. .Response ---- HTTP/1.1 200 OK Content-Disposition: attachment Content-Type: application/json; charset=UTF-8 )]}' { "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9941", "project": "myProject", "branch": "release-branch", "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9941", "subject": "Implementing Feature X", "status": "NEW", "created": "2013-02-01 09:59:32.126000000", "updated": "2013-02-21 11:16:36.775000000", "mergeable": true, "insertions": 12, "deletions": 11, "_number": 3965, "owner": { "name": "John Doe" } } ---- [[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. Options can be provided in the request body as a link:#delete-vote-input[DeleteVoteInput] entity. .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 ---- Please note that some proxies prohibit request bodies for DELETE requests. In this case, if you want to specify options, use a POST request: .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 ---- [[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: "'$$~$$'" Depending on the server's configuration, Gerrit can still support the following deprecated identifiers. These will be removed in a future release: * an ID of the change in the format "'$$~~$$'", 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 numeric change ID ("4247") If you need more time to migrate off of old change IDs, please see link:config-gerrit.html#change.api.allowedIdentifier[change.api.allowedIdentifier] for more information on how to enable the use of deprecated identifiers. [[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. [[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 legacy 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 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. |==================================== [[add-reviewer-result]] === AddReviewerResult The `AddReviewerResult` entity describes the result of adding a reviewer to a change. [options="header",cols="1,^1,5"] |=========================== |Field Name ||Description |`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:#reviewer-info[ ReviewerInfo] entities. This field will only appear if the requested `state` for the reviewer was `CC` *and* NoteDb is enabled on the server. |`error` |optional| Error message explaining why the reviewer could not be added. + If a group was specified in the input and an error is returned, it means that none of the members were added as reviewer. |`confirm` |`false` if not set| Whether adding the reviewer requires confirmation. |=========================== [[approval-info]] === ApprovalInfo The `ApprovalInfo` entity contains information about an approval from a user for a label on a change. `ApprovalInfo` has the same fields as link:rest-api-accounts.html#account-info[AccountInfo]. In addition `ApprovalInfo` has the following fields: [options="header",cols="1,^1,5"] |=========================== |Field Name ||Description |`value` |optional| The vote that the user has given for the label. If present and zero, the user is permitted to vote on the label. If absent, the user is not permitted to vote on that label. |`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. NOTE: To apply different tags on 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. |=========================== [[assignee-input]] === AssigneeInput The `AssigneeInput` entity contains the identity of the user to be set as assignee. [options="header",cols="1,^1,5"] |=========================== |Field Name ||Description |`assignee` || The link:rest-api-accounts.html#account-id[ID] of one account that should be added as assignee. |=========================== [[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-info]] === ChangeInfo The `ChangeInfo` entity contains information about a change. [options="header",cols="1,^1,5"] |================================== |Field Name ||Description |`id` || The ID of the change in the format "'\~~'", 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. |`assignee` |optional| The assignee of the change as an link:rest-api-accounts.html#account-info[ AccountInfo] entity. |`hashtags` |optional| List of hashtags that are set on the change (only populated when NoteDb is enabled). |`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 with the default label. |`stars` |optional| A list of star labels that are applied by the calling user to this change. The labels are lexicographically sorted. |`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:project-configuration.html#submit_type[submit type] of the change. + Not set for merged changes. |`mergeable` |optional| Whether the change is mergeable. + Not set for merged changes, if the change has not yet been tested, or if the link:#skip_mergeable[skip_mergeable] option is set. |`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. |`unresolved_comment_count` |optional| Number of unresolved comments. Not set if the current change index doesn't have the data. |`_number` ||The legacy numeric ID of the change. |`owner` || The owner of the change as an link:rest-api-accounts.html#account-info[ AccountInfo] entity. |`actions` |optional| Actions the caller might be able to perform on this revision. The information is a map of view name to link:#action-info[ActionInfo] entities. |`requirements` |optional| List of the link:rest-api-changes.html#requirement[requirements] to be met before this change can be submitted. |`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. |`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` 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. + Only set if 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:#detailed-labels[detailed labels] are requested. |`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 and if NoteDb is enabled. |`messages`|optional| Messages associated with the change as a list of link:#change-message-info[ChangeMessageInfo] entities. + Only set if link:#messages[messages] are requested. |`current_revision` |optional| The commit ID of the current patch set of this change. + Only set if link:#current-revision[the current revision] is requested or if link:#all-revisions[all revisions] are requested. |`revisions` |optional| All patch sets of this change as a map that maps the commit ID of the patch set to a link:#revision-info[RevisionInfo] entity. + Only set if link:#current-revision[the current revision] is requested (in which case it will only contain a key for the current revision) or if link:#all-revisions[all revisions] are requested. |`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 numeric Change-Id of the change that this change reverts. |================================== [[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. |`topic` |optional|The topic to which this change belongs. |`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`. |`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`. |`new_branch` |optional, default to `false`| Allow creating a new branch when set to `true`. |`merge` |optional| The detail of a merge commit as a link:#merge-input[MergeInput] entity. |`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 recipient type to link:#notify-info[NotifyInfo] entity. |================================== [[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. + 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. |`tag` |optional| Value of the `tag` field from link:#review-input[ReviewInput] set while posting the review. NOTE: To apply different tags on 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` ||Commit message for the cherry-picked change |`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 `NONE`. |`notify_details` |optional| Additional information about whom to notify about the update as a map of 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. |=========================== [[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| 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`. |`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 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. |=========================== [[comment-input]] === CommentInput The `CommentInput` entity contains information for creating an inline comment. [options="header",cols="1,^1,5"] |=========================== |Field Name ||Description |`id` |optional| The URL encoded UUID of the comment if an existing draft comment should be updated. |`path` |optional| The path of the file for which the inline comment should be added. + Doesn't need to be set if contained in a map where the key is the file path. |`side` |optional| The side on which the comment should be added. + Allowed values are `REVISION` and `PARENT`. + If not set, the default is `REVISION`. |`line` |optional| The number of the line for which the comment should be added. + `0` if it is a file comment. + If neither line nor range is set, a file comment is added. + If range is set, this value is ignored in favor of the `end_line` of the range. |`range` |optional| The range of the comment as a link:#comment-range[CommentRange] entity. |`in_reply_to` |optional| The URL encoded UUID of the comment to which this comment is a reply. |`updated` |optional| The link:rest-api.html#timestamp[timestamp] of this comment. + Accepted but ignored. |`message` |optional| The comment message. + If not set and an existing draft comment is updated, the existing draft comment is deleted. |`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] |`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. |=========================== [[comment-range]] === CommentRange The `CommentRange` entity describes the range of an inline comment. [options="header",cols="1,^1,5"] |=========================== |Field Name ||Description |`start_line` ||The start line number of the range. (1-based, inclusive) |`start_character` ||The character position in the start line. (0-based, inclusive) |`end_line` ||The end line number of the range. (1-based, exclusive) |`end_character` ||The character position in the end line. (0-based, exclusive) |=========================== [[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 commit in external sites as a list of link:#web-link-info[WebLinkInfo] entities. |=========================== [[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. |`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 recipient type to link:#notify-info[NotifyInfo] entity. |============================= [[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 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 recipient type to link:#notify-info[NotifyInfo] entity. |============================= [[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 during a replace, i.e. both `a` and `b` are present| Text sections deleted from side A as a link:#diff-intraline-info[DiffIntralineInfo] entity. |`edit_b` |only present during a replace, i.e. both `a` and `b` are present| Text sections inserted in side B as a link:#diff-intraline-info[DiffIntralineInfo] entity. |`due_to_rebase`|not set if `false`|Indicates whether this entry was introduced by a rebase. |`skip` |optional|count of lines skipped on both sides when the file is too large to include all common lines. |`common` |optional|Set to `true` if the region is common according to the requested ignore-whitespace parameter, but a and b contain differing amounts of whitespace. When present and true a and b are used instead of ab. |========================== [[diff-file-meta-info]] === DiffFileMetaInfo The `DiffFileMetaInfo` entity contains meta information about a file diff. [options="header",cols="1,^1,5"] |========================== |Field Name ||Description |`name` ||The name of the file. |`content_type`||The content type of the file. |`lines` ||The total number of lines in the file. |`web_links` |optional| Links to the file in external sites as a list of link:rest-api-changes.html#web-link-info[WebLinkInfo] entries. |========================== [[diff-info]] === DiffInfo The `DiffInfo` entity contains information about the diff of a file in a revision. If the link:#weblinks-only[weblinks-only] parameter is specified, only the `web_links` field is set. [options="header",cols="1,^1,5"] |========================== |Field Name ||Description |`meta_a` |not present when the file is added| Meta information about the file on side A as a link:#diff-file-meta-info[DiffFileMetaInfo] entity. |`meta_b` |not present when the file is deleted| Meta information about the file on side B as a link:#diff-file-meta-info[DiffFileMetaInfo] entity. |`change_type` ||The type of change (`ADDED`, `MODIFIED`, `DELETED`, `RENAMED` `COPIED`, `REWRITE`). |`intraline_status`|only set when the `intraline` parameter was specified in the request| Intraline status (`OK`, `ERROR`, `TIMEOUT`). |`diff_header` ||A list of strings representing the patch set diff header. |`content` ||The content differences in the file as a list of link:#diff-content[DiffContent] entities. |`web_links` |optional| Links to the file diff in external sites as a list of link:rest-api-changes.html#diff-web-link-info[DiffWebLinkInfo] entries. |`binary` |not set if `false`|Whether the file is binary. |========================== [[diff-intraline-info]] === DiffIntralineInfo The `DiffIntralineInfo` entity contains information about intraline edits in a file. The information consists of a list of `` pairs, where the skip length is the number of characters between the end of the previous edit and the start of this edit, and the mark length is the number of edited characters following the skip. The start of the edits is from the beginning of the related diff content lines. Note that the implied newline character at the end of each line is included in the length calculation, and thus it is possible for the edits to span newlines. [[diff-web-link-info]] === DiffWebLinkInfo The `DiffWebLinkInfo` entity describes a link on a diff screen to an external site. [options="header",cols="1,6"] |======================= |Field Name|Description |`name` |The link name. |`url` |The link URL. |`image_url`|URL to the icon of the link. |show_on_side_by_side_diff_view| Whether the web link should be shown on the side-by-side diff screen. |show_on_unified_diff_view| Whether the web link should be shown on the unified diff screen. |======================= [[edit-file-info]] === EditFileInfo The `EditFileInfo` entity contains additional information of a file within a change edit. [options="header",cols="1,^1,5"] |=========================== |Field Name ||Description |`web_links` |optional| Links to the diff info in external sites as a list of link:#web-link-info[WebLinkInfo] entities. |=========================== [[edit-info]] === EditInfo The `EditInfo` entity contains information about a change edit. [options="header",cols="1,^1,5"] |=========================== |Field Name ||Description |`commit` ||The commit of change edit as link:#commit-info[CommitInfo] entity. |`base_revision`||The revision of the patch set the change edit is based on. |`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. |`lines_deleted` |optional| Number of deleted lines. + Not set for binary files or if no lines were deleted. |`size_delta` || Number of bytes by which the file size increased/decreased. |`size` || File size in bytes. |============================= [[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 <> 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 <> 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. |`range` |A <> indicating which content of the file should be replaced. Lines in the file are assumed to be separated by the line feed character, the carriage return character, the carriage return followed by the line feed character, or one of the other Unicode linebreak sequences supported by Java. |`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. [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`]. * For a quick summary of the state of labels, use `LABELS`. * For detailed information about labels, including exact numeric votes for all users and the allowed range of votes for the current user, use `DETAILED_LABELS`. ==== Common fields [options="header",cols="1,^1,5"] |=========================== |Field Name ||Description |`optional` |not set if `false`| Whether the label is optional. Optional means the label may be set, but it's neither necessary for submission nor does it block submission if set. |=========================== ==== Fields set by `LABELS` [options="header",cols="1,^1,5"] |=========================== |Field Name ||Description |`approved` |optional|One user who approved this label on the change (voted the maximum value) as an link:rest-api-accounts.html#account-info[AccountInfo] entity. |`rejected` |optional|One user who rejected this label on the change (voted the minimum value) as an link:rest-api-accounts.html#account-info[AccountInfo] entity. |`recommended` |optional|One user who recommended this label on the change (voted positively, but not the maximum value) as an link:rest-api-accounts.html#account-info[AccountInfo] entity. |`disliked` |optional|One user who disliked this label on the change (voted negatively, but not the minimum value) as an link:rest-api-accounts.html#account-info[AccountInfo] entity. |`blocking` |optional|If `true`, the label blocks submit operation. If not set, the default is false. |`value` |optional|The voting value of the user who recommended/disliked this label on the change if it is not "`+1`"/"`-1`". |`default_value`|optional|The default voting value for the label. This value may be outside the range specified in permitted_labels. |=========================== ==== Fields set by `DETAILED_LABELS` [options="header",cols="1,^1,5"] |=========================== |Field Name ||Description |`all` |optional|List of all approvals for this label as a list of link:#approval-info[ApprovalInfo] entities. 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. |`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. |`strategy` |optional| The strategy of the merge, can be `recursive`, `resolve`, `simple-two-way-in-core`, `ours` or `theirs`, default will use project settings. |============================ [[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 |`inheritParent` |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 `inheritParent` 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. |================================== [[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 |=========================== [[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 recipient type. The recipient type can be `TO`, `CC` and `BCC`. [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. |======================= [[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 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/`. 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",width="50%",cols="1,^1,5"] |=========================== |Field Name ||Description |`base` |optional| The new parent revision. This can be a ref or a SHA1 to a concrete patchset. + Alternatively, a change number can be specified, in which case the current patch set is inferred. + Empty string is used for rebasing directly on top of the target branch, which effectively breaks dependency towards a parent change. |=========================== [[related-change-and-commit-info]] === RelatedChangeAndCommitInfo The `RelatedChangeAndCommitInfo` entity contains information about a related change and commit. [options="header",cols="1,^1,5"] |=========================== |Field Name ||Description |`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`). |=========================== [[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. 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. data:: (Optional) Additional key-value data linked to this requirement. This is used in templates to render rich status messages. [options="header",cols="1,^1,5"] |=========================== |Field Name | |Description |`status` | | Status of the requirement. Can be either `OK`, `NOT_READY` or `RULE_ERROR`. |`fallbackText` | | 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. |`data` |optional| Holds custom key-value strings, used in templates to render richer status messages |=========================== [[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 recipient type to link:#notify-info[NotifyInfo] entity. |============================= [[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 account added or removed from the change as an link:rest-api-accounts.html#account-info[AccountInfo] entity. |`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 may be used by CI or other automated systems to distinguish them from human reviews. Comments with specific tag values can be filtered out in the web UI. |`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| 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. |`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 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 to 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. |============================ [[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#add-reviewer-result[AddReviewerResult] representing the outcome of adding as 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. |============================ [[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 a reviewer to a change. [options="header",cols="1,^1,5"] |============================= |Field Name ||Description |`reviewer` || The link:rest-api-accounts.html#account-id[ID] of one account that should be added as reviewer or the link:rest-api-groups.html#group-id[ ID] of one group for which all members should be added as reviewers. + If an ID identifies both an account and a group, only the account is added as reviewer to the change. |`state` |optional| Add reviewer in this state. Possible reviewer states are `REVIEWER` and `CC`. 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 recipient type to link:#notify-info[NotifyInfo] entity. |============================= [[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`, `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. |`ref` ||The Git reference for the patch set. |`fetch` || Information about how to fetch this patch set. The fetch information is provided as a map that maps the protocol name ("`git`", "`http`", "`ssh`") to link:#fetch-info[FetchInfo] entities. This information is only included if a plugin implementing the link:intro-project-owner.html#download-commands[download commands] interface is installed. |`commit` |optional|The commit of the patch set as link:#commit-info[CommitInfo] entity. |`files` |optional| The files of the patch set as a map that maps the file names to link:#file-info[FileInfo] entities. Only set if link:#current-files[CURRENT_FILES] or link:#all-files[ALL_FILES] option is requested. |`actions` |optional| Actions the caller might be able to perform on this revision. The information is a map of view name to link:#action-info[ActionInfo] entities. |`reviewed` |optional| Indicates whether the caller is authenticated and has commented on the current revision. Only set if link:#reviewed[REVIEWED] option is requested. |`messageWithFooter` |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 The `RobotCommentInfo` entity contains information about a robot inline comment. `RobotCommentInfo` has the same fields as <>. 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. |`fix_suggestions`|optional|Suggested fixes for this robot comment as a list of <> entities. |=========================== [[robot-comment-input]] === RobotCommentInput The `RobotCommentInput` entity contains information for creating an inline robot comment. `RobotCommentInput` has the same fields as <>. [[rule-input]] === RuleInput The `RuleInput` entity contains information to test a Prolog rule. [options="header",cols="1,^1,5"] |=========================== |Field Name ||Description |`rule`|| Prolog code to execute instead of the code in `refs/meta/config`. |`filters`|`RUN` if not set| When `RUN` filter rules in the parent projects are called to post-process the results of the project specific rule. This behavior matches how the rule will execute if installed. + If `SKIP` the parent filters are not called, allowing the test to return results from the input rule. |=========================== [[submit-info]] === SubmitInfo The `SubmitInfo` entity contains information about the change status after submitting. [options="header",cols="1,^1,5"] |========================== |Field Name ||Description |`status` || The status of the change after submitting is `MERGED`. |`on_behalf_of`|optional| The link:rest-api-accounts.html#account-id[\{account-id\}] of the user on whose behalf the action should be done. To use this option the caller must have been granted both `Submit` and `Submit (On Behalf Of)` permissions. The user named by `on_behalf_of` does not need to be granted the `Submit` permission. This feature is aimed for CI solutions: the CI account can be granted both permissions, so individual users don't need `Submit` permission themselves. Still the changes can be submitted on behalf of real users and not with the identity of the CI account. |========================== [[submit-input]] === SubmitInput The `SubmitInput` entity contains information for submitting a change. [options="header",cols="1,^1,5"] |============================= |Field Name ||Description |`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`. |`notify_details`|optional| Additional information about whom to notify about the update as a map of 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. |=========================== [[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. |=========================== [[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. [options="header",cols="1,6"] |====================== |Field Name|Description |`name` |The link name. |`url` |The link URL. |`image_url`|URL to the icon of the link. |====================== [[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 ---------