| :linkattrs: | |
| = Gerrit Code Review - /changes/ REST API | |
| This page describes the change related REST endpoints. | |
| Please also take note of the general information on the | |
| link:rest-api.html[REST API]. | |
| [[change-endpoints]] | |
| == Change Endpoints | |
| [[create-change]] | |
| === Create Change | |
| -- | |
| 'POST /changes/' | |
| -- | |
| The change input link:#change-input[ChangeInput] entity must be | |
| provided in the request body. It is not allowed to create changes | |
| under `refs/tags/` or Gerrit internal ref namespaces such as | |
| `refs/changes/`, `refs/meta/external-ids/`, and `refs/users/`. The | |
| request would fail with `400 Bad Request` in this case. | |
| To create a change the calling user must be allowed to | |
| link:access-control.html#category_push_review[upload to code review]. | |
| .Request | |
| ---- | |
| POST /changes/ HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "project" : "myProject", | |
| "subject" : "Let's support 100% Gerrit workflow direct in browser", | |
| "branch" : "master", | |
| "topic" : "create-change-in-browser", | |
| "status" : "NEW" | |
| } | |
| ---- | |
| As response a link:#change-info[ChangeInfo] entity is returned that describes | |
| the resulting change. | |
| .Response | |
| ---- | |
| HTTP/1.1 201 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9941", | |
| "project": "myProject", | |
| "branch": "master", | |
| "topic": "create-change-in-browser", | |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9941", | |
| "subject": "Let's support 100% Gerrit workflow direct in browser", | |
| "status": "NEW", | |
| "created": "2014-05-05 07:15:44.639000000", | |
| "updated": "2014-05-05 07:15:44.639000000", | |
| "mergeable": true, | |
| "insertions": 0, | |
| "deletions": 0, | |
| "_number": 4711, | |
| "owner": { | |
| "name": "John Doe" | |
| }, | |
| "current_revision_number": 2 | |
| } | |
| ---- | |
| [[list-changes]] | |
| === Query Changes | |
| -- | |
| 'GET /changes/' | |
| -- | |
| Queries changes visible to the caller. The | |
| link:user-search.html#_search_operators[query string] must be provided | |
| by the `q` parameter. The `n` parameter can be used to limit the | |
| returned results. The `no-limit` parameter can be used remove the default | |
| limit on queries and return all results (does not apply to anonymous requests). | |
| This might not be supported by all index backends. | |
| As result a list of link:#change-info[ChangeInfo] entries is returned. | |
| The change output is sorted by the last update time, most recently | |
| updated to oldest updated. | |
| Query for open changes of watched projects: | |
| .Request | |
| ---- | |
| GET /changes/?q=status:open+is:watched&n=2 HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| [ | |
| { | |
| "id": "demo~master~Idaf5e098d70898b7119f6f4af5a6c13343d64b57", | |
| "project": "demo", | |
| "branch": "master", | |
| "attention_set": { | |
| "1000096": { | |
| "account": { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com" | |
| }, | |
| "last_update": "2012-07-17 07:19:27.766000000", | |
| "reason": "reviewer or cc replied" | |
| } | |
| }, | |
| "change_id": "Idaf5e098d70898b7119f6f4af5a6c13343d64b57", | |
| "subject": "One change", | |
| "status": "NEW", | |
| "created": "2012-07-17 07:18:30.854000000", | |
| "updated": "2012-07-17 07:19:27.766000000", | |
| "mergeable": true, | |
| "insertions": 26, | |
| "deletions": 10, | |
| "_number": 1756, | |
| "owner": { | |
| "name": "John Doe" | |
| }, | |
| "current_revision_number": 2 | |
| }, | |
| { | |
| "id": "demo~master~I09c8041b5867d5b33170316e2abc34b79bbb8501", | |
| "project": "demo", | |
| "branch": "master", | |
| "change_id": "I09c8041b5867d5b33170316e2abc34b79bbb8501", | |
| "subject": "Another change", | |
| "status": "NEW", | |
| "created": "2012-07-17 07:18:30.884000000", | |
| "updated": "2012-07-17 07:18:30.885000000", | |
| "mergeable": true, | |
| "insertions": 12, | |
| "deletions": 18, | |
| "_number": 1757, | |
| "owner": { | |
| "name": "John Doe" | |
| }, | |
| "current_revision_number": 2, | |
| "_more_changes": true | |
| } | |
| ] | |
| ---- | |
| If the number of changes matching the query exceeds either the internal | |
| limit or a supplied `n` query parameter, the last change object has a | |
| `_more_changes: true` JSON field set. | |
| The `S` or `start` query parameter can be supplied to skip a number | |
| of changes from the list. | |
| The `allow-incomplete-results` query parameter can be used. This is a boolean | |
| parameter that can optionally be set to true. If set, the server can tolerate | |
| handling faulty records when parsed from the change index, for example if a | |
| field contained a value of a wrong format. For faulty records, the server | |
| will return a canonical empty record where only the fields {project, branch, | |
| change_id, _number, owner} are set and the subject will be set to | |
| "\*\**ERROR***". All other fields will be empty. | |
| Note that the handling of this parameter is up to the index implementation. | |
| Clients are allowed to specify more than one query by setting the `q` | |
| parameter multiple times. In this case the result is an array of | |
| arrays, one per query in the same order the queries were given in. | |
| .Query for the 25 most recent open changes of the projects that you watch | |
| **** | |
| get::/changes/?q=status:open+is:watched&n=25 | |
| **** | |
| Query that retrieves changes for a user's dashboard: | |
| .Request | |
| ---- | |
| GET /changes/?q=is:open+owner:self&q=is:open+reviewer:self+-owner:self&q=is:closed+owner:self+limit:5&o=LABELS HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| [ | |
| [ | |
| { | |
| "id": "demo~master~Idaf5e098d70898b7119f6f4af5a6c13343d64b57", | |
| "project": "demo", | |
| "branch": "master", | |
| "change_id": "Idaf5e098d70898b7119f6f4af5a6c13343d64b57", | |
| "subject": "One change", | |
| "status": "NEW", | |
| "created": "2012-07-17 07:18:30.854000000", | |
| "updated": "2012-07-17 07:19:27.766000000", | |
| "mergeable": true, | |
| "insertions": 4, | |
| "deletions": 7, | |
| "_number": 1756, | |
| "owner": { | |
| "name": "John Doe" | |
| }, | |
| "labels": { | |
| "Verified": {}, | |
| "Code-Review": {} | |
| }, | |
| "current_revision_number": 2 | |
| } | |
| ], | |
| [], | |
| [] | |
| ] | |
| ---- | |
| .Query the changes for your user dashboard | |
| **** | |
| get::/changes/?q=is:open+owner:self&q=is:open+reviewer:self+-owner:self&q=is:closed+owner:self+limit:5&o=LABELS | |
| **** | |
| [[query-options]] | |
| Additional fields can be obtained by adding `o` parameters, each | |
| option requires more database lookups and slows down the query | |
| response time to the client so they are generally disabled by | |
| default. Optional fields are: | |
| [[labels]] | |
| -- | |
| * `LABELS`: Includes the `labels` field which contains all information about | |
| labels and approvers that have granted (or rejected) that label. Does not | |
| include the `permitted_voting_range` attribute with the list of | |
| link:#approval-info[ApprovalInfo] of the `all` attribute. | |
| -- | |
| [[detailed-labels]] | |
| -- | |
| * `DETAILED_LABELS`: Includes the `labels` field which contains all information | |
| about labels and approvers that have granted (or rejected) that label, including | |
| the `permitted_voting_range` attribute with the list of | |
| link:#approval-info[ApprovalInfo] of the `all` attribute. | |
| -- | |
| [[submit-requirements]] | |
| -- | |
| * `SUBMIT_REQUIREMENTS`: detailed result of the evaluated submit requirements | |
| for this change. | |
| -- | |
| [[current-revision]] | |
| -- | |
| * `CURRENT_REVISION`: describe the current revision (patch set) | |
| of the change, including the commit SHA-1 and URLs to fetch from. | |
| -- | |
| [[all-revisions]] | |
| -- | |
| * `ALL_REVISIONS`: describe all revisions, not just current. | |
| -- | |
| [[download-commands]] | |
| -- | |
| * `DOWNLOAD_COMMANDS`: include the `commands` field in the | |
| link:#fetch-info[FetchInfo] for revisions. Only valid when the | |
| `CURRENT_REVISION` or `ALL_REVISIONS` option is selected. | |
| -- | |
| [[current-commit]] | |
| -- | |
| * `CURRENT_COMMIT`: parse and output all header fields from the | |
| commit object, including message. Only valid when the | |
| `CURRENT_REVISION` or `ALL_REVISIONS` option is selected. | |
| -- | |
| [[all-commits]] | |
| -- | |
| * `ALL_COMMITS`: parse and output all header fields from the | |
| output revisions. If only `CURRENT_REVISION` was requested | |
| then only the current revision's commit data will be output. | |
| -- | |
| [[current-files]] | |
| -- | |
| * `CURRENT_FILES`: list files modified by the commit and magic files, | |
| including basic line counts inserted/deleted per file. Only valid | |
| when the `CURRENT_REVISION` or `ALL_REVISIONS` option is selected. | |
| -- | |
| [[all-files]] | |
| -- | |
| * `ALL_FILES`: list files modified by the commit and magic files, | |
| including basic line counts inserted/deleted per file. If only the | |
| `CURRENT_REVISION` was requested then only that commit's modified | |
| files will be output. | |
| -- | |
| [[detailed-accounts]] | |
| -- | |
| * `DETAILED_ACCOUNTS`: include `_account_id`, `email` and `username` | |
| fields when referencing accounts. | |
| -- | |
| [[reviewer-updates]] | |
| -- | |
| * `REVIEWER_UPDATES`: include updates to reviewers set as | |
| link:#review-update-info[ReviewerUpdateInfo] entities. | |
| -- | |
| [[messages]] | |
| -- | |
| * `MESSAGES`: include messages associated with the change. | |
| -- | |
| [[actions]] | |
| -- | |
| * `CURRENT_ACTIONS`: include information on available actions | |
| for the change and its current revision. Ignored if the caller | |
| is not authenticated. | |
| -- | |
| [[change-actions]] | |
| -- | |
| * `CHANGE_ACTIONS`: include information on available | |
| change actions for the change. Ignored if the caller | |
| is not authenticated. | |
| -- | |
| [[reviewed]] | |
| -- | |
| * `REVIEWED`: include the `reviewed` field if all of the following are | |
| true: | |
| - the change is open | |
| - the caller is authenticated | |
| - the caller has commented on the change more recently than the last update | |
| from the change owner, i.e. this change would show up in the results of | |
| link:user-search.html#reviewedby[reviewedby:self]. | |
| -- | |
| [[skip_diffstat]] | |
| -- | |
| * `SKIP_DIFFSTAT`: skip the 'insertions' and 'deletions' field in link:#change-info[ChangeInfo]. | |
| For large trees, their computation may be expensive. | |
| -- | |
| [[submittable]] | |
| -- | |
| * `SUBMITTABLE`: include the `submittable` field in link:#change-info[ChangeInfo], | |
| which can be used to tell if the change is reviewed and ready for submit. Only | |
| changes with `status` is `NEW` can be submittable, for `MERGED` and | |
| `ABANDONED` changes this alway evaluates to `false`. | |
| -- | |
| [[web-links]] | |
| -- | |
| * `WEB_LINKS`: include the `web_links` field in link:#commit-info[CommitInfo], | |
| therefore only valid in combination with `CURRENT_COMMIT` or | |
| `ALL_COMMITS`. | |
| -- | |
| [[check]] | |
| -- | |
| * `CHECK`: include potential problems with the change. | |
| -- | |
| [[commit-footers]] | |
| -- | |
| * `COMMIT_FOOTERS`: include the full commit message with | |
| Gerrit-specific commit footers in the | |
| link:#revision-info[RevisionInfo]. | |
| -- | |
| [[push-certificates]] | |
| -- | |
| * `PUSH_CERTIFICATES`: include push certificate information in the | |
| link:#revision-info[RevisionInfo]. Ignored if signed push is not | |
| link:config-gerrit.html#receive.enableSignedPush[enabled] on the | |
| server. | |
| -- | |
| [[tracking-ids]] | |
| -- | |
| * `TRACKING_IDS`: include references to external tracking systems | |
| as link:#tracking-id-info[TrackingIdInfo]. | |
| -- | |
| [[custom-keyed-values]] | |
| -- | |
| * `CUSTOM_KEYED_VALUES`: include the custom key-value map | |
| -- | |
| [[star]] | |
| -- | |
| * `STAR`: include the `starred` field in | |
| link:#change-info[ChangeInfo], which indicates if the change is starred | |
| by the current user or not. | |
| -- | |
| [[parents-data]] | |
| -- | |
| * `PARENTS`: include the `parents_data` field in | |
| link:#revision-info[RevisionInfo], which provides information of whether the | |
| parent commit of this revision, e.g. if it's merged in the target branch | |
| and whether it points to a patch-set of another change. | |
| -- | |
| .Request | |
| ---- | |
| GET /changes/?q=97&o=CURRENT_REVISION&o=CURRENT_COMMIT&o=CURRENT_FILES&o=DOWNLOAD_COMMANDS HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| [ | |
| { | |
| "id": "gerrit~master~I7ea46d2e2ee5c64c0d807677859cfb7d90b8966a", | |
| "project": "gerrit", | |
| "branch": "master", | |
| "change_id": "I7ea46d2e2ee5c64c0d807677859cfb7d90b8966a", | |
| "subject": "Use an EventBus to manage star icons", | |
| "status": "NEW", | |
| "created": "2012-04-25 00:52:25.580000000", | |
| "updated": "2012-04-25 00:52:25.586000000", | |
| "mergeable": true, | |
| "insertions": 16, | |
| "deletions": 7, | |
| "_number": 97, | |
| "owner": { | |
| "name": "Shawn Pearce" | |
| }, | |
| "current_revision_number": 1, | |
| "current_revision": "184ebe53805e102605d11f6b143486d15c23a09c", | |
| "revisions": { | |
| "184ebe53805e102605d11f6b143486d15c23a09c": { | |
| "kind": "REWORK", | |
| "_number": 1, | |
| "ref": "refs/changes/97/97/1", | |
| "fetch": { | |
| "git": { | |
| "url": "git://localhost/gerrit", | |
| "ref": "refs/changes/97/97/1", | |
| "commands": { | |
| "Checkout": "git fetch git://localhost/gerrit refs/changes/97/97/1 \u0026\u0026 git checkout FETCH_HEAD", | |
| "Cherry-Pick": "git fetch git://localhost/gerrit refs/changes/97/97/1 \u0026\u0026 git cherry-pick FETCH_HEAD", | |
| "Format-Patch": "git fetch git://localhost/gerrit refs/changes/97/97/1 \u0026\u0026 git format-patch -1 --stdout FETCH_HEAD", | |
| "Pull": "git pull git://localhost/gerrit refs/changes/97/97/1" | |
| } | |
| }, | |
| "http": { | |
| "url": "http://myuser@127.0.0.1:8080/gerrit", | |
| "ref": "refs/changes/97/97/1", | |
| "commands": { | |
| "Checkout": "git fetch http://myuser@127.0.0.1:8080/gerrit refs/changes/97/97/1 \u0026\u0026 git checkout FETCH_HEAD", | |
| "Cherry-Pick": "git fetch http://myuser@127.0.0.1:8080/gerrit refs/changes/97/97/1 \u0026\u0026 git cherry-pick FETCH_HEAD", | |
| "Format-Patch": "git fetch http://myuser@127.0.0.1:8080/gerrit refs/changes/97/97/1 \u0026\u0026 git format-patch -1 --stdout FETCH_HEAD", | |
| "Pull": "git pull http://myuser@127.0.0.1:8080/gerrit refs/changes/97/97/1" | |
| } | |
| }, | |
| "ssh": { | |
| "url": "ssh://myuser@*:29418/gerrit", | |
| "ref": "refs/changes/97/97/1", | |
| "commands": { | |
| "Checkout": "git fetch ssh://myuser@*:29418/gerrit refs/changes/97/97/1 \u0026\u0026 git checkout FETCH_HEAD", | |
| "Cherry-Pick": "git fetch ssh://myuser@*:29418/gerrit refs/changes/97/97/1 \u0026\u0026 git cherry-pick FETCH_HEAD", | |
| "Format-Patch": "git fetch ssh://myuser@*:29418/gerrit refs/changes/97/97/1 \u0026\u0026 git format-patch -1 --stdout FETCH_HEAD", | |
| "Pull": "git pull ssh://myuser@*:29418/gerrit refs/changes/97/97/1" | |
| } | |
| } | |
| }, | |
| "commit": { | |
| "parents": [ | |
| { | |
| "commit": "1eee2c9d8f352483781e772f35dc586a69ff5646", | |
| "subject": "Migrate contributor agreements to All-Projects." | |
| } | |
| ], | |
| "author": { | |
| "name": "Shawn O. Pearce", | |
| "email": "sop@google.com", | |
| "date": "2012-04-24 18:08:08.000000000", | |
| "tz": -420 | |
| }, | |
| "committer": { | |
| "name": "Shawn O. Pearce", | |
| "email": "sop@google.com", | |
| "date": "2012-04-24 18:08:08.000000000", | |
| "tz": -420 | |
| }, | |
| "subject": "Use an EventBus to manage star icons", | |
| "message": "Use an EventBus to manage star icons\n\nImage widgets that need to ..." | |
| }, | |
| "files": { | |
| "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeCache.java": { | |
| "lines_deleted": 8, | |
| "size_delta": -412, | |
| "size": 7782 | |
| }, | |
| "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeDetailCache.java": { | |
| "lines_inserted": 1, | |
| "size_delta": 23, | |
| "size": 6762 | |
| }, | |
| "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeScreen.java": { | |
| "lines_inserted": 11, | |
| "lines_deleted": 19, | |
| "size_delta": -298, | |
| "size": 47023 | |
| }, | |
| "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeTable.java": { | |
| "lines_inserted": 23, | |
| "lines_deleted": 20, | |
| "size_delta": 132, | |
| "size": 17727 | |
| }, | |
| "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarCache.java": { | |
| "status": "D", | |
| "lines_deleted": 139, | |
| "size_delta": -5512, | |
| "size": 13098 | |
| }, | |
| "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarredChanges.java": { | |
| "status": "A", | |
| "lines_inserted": 204, | |
| "size_delta": 8345, | |
| "size": 8345 | |
| }, | |
| "gerrit-gwtui/src/main/java/com/google/gerrit/client/ui/Screen.java": { | |
| "lines_deleted": 9, | |
| "size_delta": -343, | |
| "size": 5385 | |
| } | |
| } | |
| } | |
| } | |
| } | |
| ] | |
| ---- | |
| [[get-change]] | |
| === Get Change | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]' | |
| -- | |
| Retrieves a change. | |
| Additional fields can be obtained by adding `o` parameters, each | |
| option requires more database lookups and slows down the query | |
| response time to the client so they are generally disabled by | |
| default. Fields are described in link:#list-changes[Query Changes]. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940 HTTP/1.0 | |
| ---- | |
| As response a link:#change-info[ChangeInfo] entity is returned that | |
| describes the change. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", | |
| "project": "myProject", | |
| "branch": "master", | |
| "attention_set": { | |
| "1000096": { | |
| "account": { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com" | |
| }, | |
| "last_update": "2013-02-21 11:16:36.775000000", | |
| "reason": "reviewer or cc replied" | |
| } | |
| }, | |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", | |
| "subject": "Implementing Feature X", | |
| "status": "NEW", | |
| "created": "2013-02-01 09:59:32.126000000", | |
| "updated": "2013-02-21 11:16:36.775000000", | |
| "mergeable": true, | |
| "insertions": 34, | |
| "deletions": 101, | |
| "_number": 3965, | |
| "owner": { | |
| "name": "John Doe" | |
| }, | |
| "current_revision_number": 2 | |
| } | |
| ---- | |
| Historical state of the change can be retrieved by specifying the | |
| `meta=SHA-1` parameter. This will use a historical NoteDb snapshot to | |
| populate ChangeInfo. If the SHA-1 is not reachable as a NoteDb state, | |
| status code 412 is returned. | |
| [[get-meta-diff]] | |
| === Get Meta Diff | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/meta_diff?old=SHA-1&meta=SHA-1' | |
| -- | |
| Retrieves the difference between two historical states of a change | |
| by specifying the `old=SHA-1` and the `meta=SHA-1` parameters. | |
| If the `old` parameter is not provided, the parent of the `meta` | |
| SHA-1 is used. If the `meta` parameter is not provided, the current | |
| state of the change is used. If neither are provided, the | |
| difference between the current state of the change and its previous | |
| state is returned. | |
| Additional fields can be obtained by adding `o` parameters, analogous | |
| to link:#get-change[Get Change], and the same concerns for Get Change hold for | |
| this endpoint too. Fields are described in link:#list-changes[Query Changes]. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/meta_diff?old=b083abc34eb6dbdb9e154ba092fc198000e997b4&meta=63b81f2bde703ae07787a940e8fdf9a1828605b1 HTTP/1.0 | |
| ---- | |
| As a response, two link:#change-info[ChangeInfo] entities are returned | |
| that describe information added and removed from the `old` change state, and | |
| the two link:#change-info[ChangeInfo] entities that generated the diff are | |
| returned. Only fields that differ between the change's two states are returned. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "added": { | |
| "attention_set": { | |
| "1000096": { | |
| "account": { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com" | |
| }, | |
| "last_update": "2013-02-21 11:16:36.775000000", | |
| "reason": "reviewer or cc replied" | |
| } | |
| }, | |
| "updated": "2013-02-21 11:16:36.775000000", | |
| "topic": "new-topic" | |
| }, | |
| "removed": { | |
| "updated": "2013-02-01 09:59:32.126000000", | |
| "topic": "old-topic" | |
| }, | |
| "old_change_info": { | |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", | |
| "project": "myProject", | |
| "branch": "master", | |
| "attention_set": [], | |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", | |
| "subject": "Implementing Feature X", | |
| "status": "NEW", | |
| "topic": "old-topic", | |
| "created": "2013-02-01 09:59:32.126000000", | |
| "updated": "2013-02-01 09:59:32.126000000", | |
| "mergeable": true, | |
| "insertions": 34, | |
| "deletions": 101, | |
| "_number": 3965, | |
| "owner": { | |
| "name": "John Doe" | |
| }, | |
| "current_revision_number": 2 | |
| }, | |
| "new_change_info": { | |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", | |
| "project": "myProject", | |
| "branch": "master", | |
| "attention_set": { | |
| "1000096": { | |
| "account": { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com" | |
| }, | |
| "last_update": "2013-02-21 11:16:36.775000000", | |
| "reason": "reviewer or cc replied" | |
| } | |
| }, | |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", | |
| "subject": "Implementing Feature X", | |
| "status": "NEW", | |
| "topic": "new-topic", | |
| "created": "2013-02-01 09:59:32.126000000", | |
| "updated": "2013-02-21 11:16:36.775000000", | |
| "mergeable": true, | |
| "insertions": 34, | |
| "deletions": 101, | |
| "_number": 3965, | |
| "owner": { | |
| "name": "John Doe" | |
| }, | |
| "current_revision_number": 2 | |
| }, | |
| } | |
| ---- | |
| If the provided SHA-1 for `meta` is not reachable as a NoteDb | |
| state, the status code 412 is returned. If the SHA-1 for `old` | |
| is not reachable, the difference between the change at state | |
| `meta` and an empty change is returned. | |
| [[get-change-detail]] | |
| === Get Change Detail | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/detail' | |
| -- | |
| Retrieves a change with link:#labels[labels], link:#detailed-labels[ | |
| detailed labels], link:#detailed-accounts[detailed accounts], | |
| link:#reviewer-updates[reviewer updates], and link:#messages[messages]. | |
| Additional fields can be obtained by adding `o` parameters, each | |
| option requires more database lookups and slows down the query | |
| response time to the client so they are generally disabled by | |
| default. Fields are described in link:#list-changes[Query Changes]. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/detail HTTP/1.0 | |
| ---- | |
| As response a link:#change-info[ChangeInfo] entity is returned that | |
| describes the change. This response will contain all votes for each | |
| label and include one combined vote. The combined label vote is | |
| calculated in the following order (from highest to lowest): | |
| REJECTED > APPROVED > DISLIKED > RECOMMENDED. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", | |
| "project": "myProject", | |
| "branch": "master", | |
| "attention_set": { | |
| "1000096": { | |
| "account": { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com", | |
| "username": "jdoe" | |
| }, | |
| "last_update": "2013-02-21 11:16:36.775000000", | |
| "reason": "reviewer or cc replied" | |
| } | |
| }, | |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", | |
| "subject": "Implementing Feature X", | |
| "status": "NEW", | |
| "created": "2013-02-01 09:59:32.126000000", | |
| "updated": "2013-02-21 11:16:36.775000000", | |
| "mergeable": true, | |
| "insertions": 126, | |
| "deletions": 11, | |
| "_number": 3965, | |
| "owner": { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com", | |
| "username": "jdoe" | |
| }, | |
| "labels": { | |
| "Verified": { | |
| "all": [ | |
| { | |
| "value": 0, | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com", | |
| "username": "jdoe" | |
| }, | |
| { | |
| "value": 0, | |
| "_account_id": 1000097, | |
| "name": "Jane Roe", | |
| "email": "jane.roe@example.com", | |
| "username": "jroe" | |
| } | |
| ], | |
| "values": { | |
| "-1": "Fails", | |
| " 0": "No score", | |
| "+1": "Verified" | |
| } | |
| }, | |
| "Code-Review": { | |
| "disliked": { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com", | |
| "username": "jdoe" | |
| }, | |
| "all": [ | |
| { | |
| "value": -1, | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com", | |
| "username": "jdoe" | |
| }, | |
| { | |
| "value": 1, | |
| "_account_id": 1000097, | |
| "name": "Jane Roe", | |
| "email": "jane.roe@example.com", | |
| "username": "jroe" | |
| } | |
| ] | |
| "values": { | |
| "-2": "This shall not be submitted", | |
| "-1": "I would prefer this is not submitted as is", | |
| " 0": "No score", | |
| "+1": "Looks good to me, but someone else must approve", | |
| "+2": "Looks good to me, approved" | |
| } | |
| } | |
| }, | |
| "permitted_labels": { | |
| "Verified": [ | |
| "-1", | |
| " 0", | |
| "+1" | |
| ], | |
| "Code-Review": [ | |
| "-2", | |
| "-1", | |
| " 0", | |
| "+1", | |
| "+2" | |
| ] | |
| }, | |
| "removable_labels": { | |
| "Code-Review": { | |
| "-1": [ | |
| { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com", | |
| "username": "jdoe" | |
| } | |
| ], | |
| "+1": [ | |
| { | |
| "_account_id": 1000097, | |
| "name": "Jane Roe", | |
| "email": "jane.roe@example.com", | |
| "username": "jroe" | |
| } | |
| ] | |
| } | |
| }, | |
| "removable_reviewers": [ | |
| { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com", | |
| "username": "jdoe" | |
| }, | |
| { | |
| "_account_id": 1000097, | |
| "name": "Jane Roe", | |
| "email": "jane.roe@example.com", | |
| "username": "jroe" | |
| } | |
| ], | |
| "reviewers": { | |
| "REVIEWER": [ | |
| { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com", | |
| "username": "jdoe" | |
| }, | |
| { | |
| "_account_id": 1000097, | |
| "name": "Jane Roe", | |
| "email": "jane.roe@example.com", | |
| "username": "jroe" | |
| } | |
| ] | |
| }, | |
| "reviewer_updates": [ | |
| { | |
| "state": "REVIEWER", | |
| "reviewer": { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com", | |
| "username": "jdoe" | |
| }, | |
| "updated_by": { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com", | |
| "username": "jdoe" | |
| }, | |
| "updated": "2016-07-21 20:12:39.000000000" | |
| }, | |
| { | |
| "state": "REMOVED", | |
| "reviewer": { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com", | |
| "username": "jdoe" | |
| }, | |
| "updated_by": { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com", | |
| "username": "jdoe" | |
| }, | |
| "updated": "2016-07-21 20:12:33.000000000" | |
| }, | |
| { | |
| "state": "CC", | |
| "reviewer": { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com", | |
| "username": "jdoe" | |
| }, | |
| "updated_by": { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com", | |
| "username": "jdoe" | |
| }, | |
| "updated": "2016-03-23 21:34:02.419000000", | |
| }, | |
| ], | |
| "messages": [ | |
| { | |
| "id": "YH-egE", | |
| "author": { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com", | |
| "username": "jdoe" | |
| }, | |
| "date": "2013-03-23 21:34:02.419000000", | |
| "message": "Patch Set 1:\n\nThis is the first message.", | |
| "_revision_number": 1 | |
| }, | |
| { | |
| "id": "WEEdhU", | |
| "author": { | |
| "_account_id": 1000097, | |
| "name": "Jane Roe", | |
| "email": "jane.roe@example.com", | |
| "username": "jroe" | |
| }, | |
| "date": "2013-03-23 21:36:52.332000000", | |
| "message": "Patch Set 1:\n\nThis is the second message.\n\nWith a line break.", | |
| "_revision_number": 1 | |
| } | |
| ], | |
| "current_revision_number": 2 | |
| } | |
| ---- | |
| [[create-merge-patch-set-for-change]] | |
| === Create Merge Patch Set For Change | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/merge' | |
| -- | |
| Update an existing change by using a | |
| link:#merge-patch-set-input[MergePatchSetInput] entity. | |
| Gerrit will create a merge commit based on the information of | |
| MergePatchSetInput and add a new patch set to the change corresponding | |
| to the new merge commit. | |
| If one of the secondary emails associated with the user performing the operation was used as the | |
| committer email in the current patch set, the same email will be used as the committer email in the | |
| new patch set; otherwise, the user's preferred email will be used. | |
| .Request | |
| ---- | |
| POST /changes/test~master~Ic5466d107c5294414710935a8ef3b0180fb848dc/merge HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "subject": "Merge dev_branch into master", | |
| "merge": { | |
| "source": "refs/changes/34/1234/1" | |
| } | |
| } | |
| ---- | |
| As response a link:#change-info[ChangeInfo] entity with current revision is | |
| returned that describes the resulting change. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "id": "test~master~Ic5466d107c5294414710935a8ef3b0180fb848dc", | |
| "project": "test", | |
| "branch": "master", | |
| "hashtags": [], | |
| "change_id": "Ic5466d107c5294414710935a8ef3b0180fb848dc", | |
| "subject": "Merge dev_branch into master", | |
| "status": "NEW", | |
| "created": "2016-09-23 18:08:53.238000000", | |
| "updated": "2016-09-23 18:09:25.934000000", | |
| "submit_type": "MERGE_IF_NECESSARY", | |
| "mergeable": true, | |
| "insertions": 5, | |
| "deletions": 0, | |
| "_number": 72, | |
| "owner": { | |
| "_account_id": 1000000 | |
| }, | |
| "current_revision_number": 1, | |
| "current_revision": "27cc4558b5a3d3387dd11ee2df7a117e7e581822" | |
| } | |
| ---- | |
| [[get-message]] | |
| === Get Commit Message | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/message' | |
| -- | |
| Returns the commit message of the change (from the current patch set). | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/message HTTP/1.0 | |
| ---- | |
| The commit message is returned as a link:#commit-message-info[ | |
| CommitMessageInfo] entity. | |
| Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "subject": "Add feature X", | |
| "full_message": "Add Feature X\n\nFeature X helps with foo.\n\nBug: 123\nChange-Id: I10394472cbd17dd12454f229e4f6de00b143a444\n", | |
| "footers": { | |
| "Bug": "123", | |
| "Change-Id": "I10394472cbd17dd12454f229e4f6de00b143a444" | |
| } | |
| } | |
| ---- | |
| [[set-message]] | |
| === Set Commit Message | |
| -- | |
| 'PUT /changes/link:#change-id[\{change-id\}]/message' | |
| -- | |
| Creates a new patch set with a new commit message. | |
| If one of the secondary emails associated with the user performing the operation was used as the | |
| committer email in the current patch set, the same email will be used as the committer email in the | |
| new patch set; otherwise, the user's preferred email will be used. | |
| The new commit message must be provided in the request body inside a | |
| link:#commit-message-input[CommitMessageInput] entity. If a Change-Id | |
| footer is specified, it must match the current Change-Id footer. If | |
| the Change-Id footer is absent, the current Change-Id is added to the | |
| message. | |
| .Request | |
| ---- | |
| PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/message HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "message": "New Commit message \n\nChange-Id: I10394472cbd17dd12454f229e4f6de00b143a444\n" | |
| } | |
| ---- | |
| .Notifications | |
| An email will be sent using the "newpatchset" template. | |
| [options="header",cols="1,1"] | |
| |============================= | |
| |WIP State |Default | |
| |Ready for review|owner, reviewers, CCs, stars, NEW_PATCHSETS watchers | |
| |Work in progress|owner | |
| |============================= | |
| [[get-topic]] | |
| === Get Topic | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/topic' | |
| -- | |
| Retrieves the topic of a change. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| "Documentation" | |
| ---- | |
| If the change does not have a topic an empty string is returned. | |
| [[set-topic]] | |
| === Set Topic | |
| -- | |
| 'PUT /changes/link:#change-id[\{change-id\}]/topic' | |
| -- | |
| Sets the topic of a change. | |
| The new topic must be provided in the request body inside a | |
| link:#topic-input[TopicInput] entity. Any leading or trailing whitespace | |
| in the topic name will be removed. | |
| .Request | |
| ---- | |
| PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "topic": "Documentation" | |
| } | |
| ---- | |
| As response the new topic is returned. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| "Documentation" | |
| ---- | |
| If the topic was deleted the response is "`204 No Content`". | |
| [[delete-topic]] | |
| === Delete Topic | |
| -- | |
| 'DELETE /changes/link:#change-id[\{change-id\}]/topic' | |
| -- | |
| Deletes the topic of a change. | |
| .Request | |
| ---- | |
| DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 204 No Content | |
| ---- | |
| [[get-pure-revert]] | |
| === Get Pure Revert | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/pure_revert' | |
| -- | |
| Check if the given change is a pure revert of the change it references in `revertOf`. | |
| Optionally, the query parameter `o` can be passed in to specify a commit (SHA-1 in | |
| 40 digit hex representation) to check against. It takes precedence over `revertOf`. | |
| If the change has no reference in `revertOf`, the parameter is mandatory. | |
| As response a link:#pure-revert-info[PureRevertInfo] entity is returned. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/pure_revert?o=247bccf56ae47634650bcc08b8aa784c3580ccas HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "is_pure_revert" : false | |
| } | |
| ---- | |
| [[abandon-change]] | |
| === Abandon Change | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/abandon' | |
| -- | |
| Abandons a change. | |
| The request body does not need to include a link:#abandon-input[ | |
| AbandonInput] entity if no review comment is added. | |
| Abandoning a change also removes all users from the link:user-attention-set.html[attention set]. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/abandon HTTP/1.0 | |
| ---- | |
| As response a link:#change-info[ChangeInfo] entity is returned that | |
| describes the abandoned change. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", | |
| "project": "myProject", | |
| "branch": "master", | |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", | |
| "subject": "Implementing Feature X", | |
| "status": "ABANDONED", | |
| "created": "2013-02-01 09:59:32.126000000", | |
| "updated": "2013-02-21 11:16:36.775000000", | |
| "mergeable": true, | |
| "insertions": 3, | |
| "deletions": 310, | |
| "_number": 3965, | |
| "owner": { | |
| "name": "John Doe" | |
| }, | |
| "current_revision_number": 2 | |
| } | |
| ---- | |
| If the change cannot be abandoned because the change state doesn't | |
| allow abandoning of the change, the response is "`409 Conflict`" and | |
| the error message is contained in the response body. | |
| .Response | |
| ---- | |
| HTTP/1.1 409 Conflict | |
| Content-Disposition: attachment | |
| Content-Type: text/plain; charset=UTF-8 | |
| change is merged | |
| ---- | |
| .Notifications | |
| An email will be sent using the "abandon" template. The notify handling is ALL. | |
| Notifications are suppressed on WIP changes that have never started review. | |
| [options="header",cols="1,2"] | |
| |============================= | |
| |WIP State |notify=ALL | |
| |Ready for review|owner, reviewers, CCs, stars, ABANDONED_CHANGES watchers | |
| |Work in progress|not sent | |
| |Reviewable WIP |owner, reviewers, CCs, stars, ABANDONED_CHANGES watchers | |
| |============================= | |
| [[restore-change]] | |
| === Restore Change | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/restore' | |
| -- | |
| Restores a change. | |
| The request body does not need to include a link:#restore-input[ | |
| RestoreInput] entity if no review comment is added. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/restore HTTP/1.0 | |
| ---- | |
| As response a link:#change-info[ChangeInfo] entity is returned that | |
| describes the restored change. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", | |
| "project": "myProject", | |
| "branch": "master", | |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", | |
| "subject": "Implementing Feature X", | |
| "status": "NEW", | |
| "created": "2013-02-01 09:59:32.126000000", | |
| "updated": "2013-02-21 11:16:36.775000000", | |
| "mergeable": true, | |
| "insertions": 2, | |
| "deletions": 13, | |
| "_number": 3965, | |
| "owner": { | |
| "name": "John Doe" | |
| }, | |
| "current_revision_number": 2 | |
| } | |
| ---- | |
| If the change cannot be restored because the change state doesn't | |
| allow restoring the change, the response is "`409 Conflict`" and | |
| the error message is contained in the response body. | |
| .Response | |
| ---- | |
| HTTP/1.1 409 Conflict | |
| Content-Disposition: attachment | |
| Content-Type: text/plain; charset=UTF-8 | |
| change is new | |
| ---- | |
| [[rebase-change]] | |
| === Rebase Change | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/rebase' | |
| -- | |
| Rebases a change. | |
| For merge commits always the first parent is rebased. This means the new base becomes the first | |
| parent of the rebased merge commit while the second parent stays intact. | |
| If one of the secondary emails associated with the user performing the operation was used as the | |
| committer email in the current patch set, the same email will be used as the committer email in the | |
| new patch set; otherwise, the user's preferred email will be used. | |
| Optionally, the parent revision can be changed to another patch set through the | |
| link:#rebase-input[RebaseInput] entity. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I3ea943139cb62e86071996f2480e58bf3eeb9dd2/rebase HTTP/1.0 | |
| Content-Type: application/json;charset=UTF-8 | |
| { | |
| "base" : "1234", | |
| } | |
| ---- | |
| As response a link:#change-info[ChangeInfo] entity is returned that | |
| describes the rebased change. Information about the current patch set | |
| is included. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "id": "myProject~master~I3ea943139cb62e86071996f2480e58bf3eeb9dd2", | |
| "project": "myProject", | |
| "branch": "master", | |
| "change_id": "I3ea943139cb62e86071996f2480e58bf3eeb9dd2", | |
| "subject": "Implement Feature X", | |
| "status": "NEW", | |
| "created": "2013-02-01 09:59:32.126000000", | |
| "updated": "2013-02-21 11:16:36.775000000", | |
| "mergeable": false, | |
| "insertions": 33, | |
| "deletions": 9, | |
| "_number": 4799, | |
| "owner": { | |
| "name": "John Doe" | |
| }, | |
| "current_revision_number": 2, | |
| "current_revision": "27cc4558b5a3d3387dd11ee2df7a117e7e581822", | |
| "revisions": { | |
| "27cc4558b5a3d3387dd11ee2df7a117e7e581822": { | |
| "kind": "REWORK", | |
| "_number": 2, | |
| "ref": "refs/changes/99/4799/2", | |
| "fetch": { | |
| "http": { | |
| "url": "http://gerrit:8080/myProject", | |
| "ref": "refs/changes/99/4799/2" | |
| } | |
| }, | |
| "commit": { | |
| "parents": [ | |
| { | |
| "commit": "b4003890dadd406d80222bf1ad8aca09a4876b70", | |
| "subject": "Implement Feature A" | |
| } | |
| ], | |
| "author": { | |
| "name": "John Doe", | |
| "email": "john.doe@example.com", | |
| "date": "2013-05-07 15:21:27.000000000", | |
| "tz": 120 | |
| }, | |
| "committer": { | |
| "name": "Gerrit Code Review", | |
| "email": "gerrit-server@example.com", | |
| "date": "2013-05-07 15:35:43.000000000", | |
| "tz": 120 | |
| }, | |
| "subject": "Implement Feature X", | |
| "message": "Implement Feature X\n\nAdded feature X." | |
| } | |
| } | |
| } | |
| ---- | |
| If the change cannot be rebased, e.g. due to conflicts, the response is | |
| "`409 Conflict`" and the error message is contained in the response | |
| body. | |
| .Response | |
| ---- | |
| HTTP/1.1 409 Conflict | |
| Content-Disposition: attachment | |
| Content-Type: text/plain; charset=UTF-8 | |
| The change could not be rebased due to a path conflict during merge. | |
| ---- | |
| Rebasing a change is allowed for the change owner, users with the | |
| link:access-control.html#category_rebase[Rebase] permission and users | |
| with the link:access-control.html#category_submit[Submit] permission. | |
| In addition, the rebaser or the original uploader, if rebasing is done | |
| on behalf of the uploader (see `rebase_on_behalf_of_uploader` option in | |
| link:#rebase-input[RebaseInput]), needs to have all permissions that | |
| are required to create the new patch set: | |
| * the link:access-control.html#category_push[Push] permission | |
| * the link:access-control.html#category_add_patch_set[Add Patch Set] | |
| permission (only if the user is not the change owner) | |
| * the link:access-control.html#category_forge_author[Forge Author] | |
| permission (only if the commit author is forged) | |
| * the link:access-control.html#category_forge_server[Forge Server] | |
| permission (only if the commit author is the server identity) | |
| The same permissions were required for the upload of the original patch | |
| set. This means if the rebase is done on behalf of the uploader these | |
| permission checks should just pass, unless the uploader lost | |
| permissions after the upload of the original patch set. In this case | |
| rebasing on behalf of the uploader is not possible and a normal rebase | |
| (on behalf of the rebaser) must be done, which means that the rebaser | |
| becomes the uploader and takes over the change. If self approvals are | |
| disallowed, this means that the rebaser can no longer approve the | |
| change (as approvals of the uploader are ignored). | |
| [[rebase-chain]] | |
| === Rebase Chain | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/rebase:chain' | |
| -- | |
| Rebases an ancestry chain of changes. | |
| If one of the secondary emails associated with the user performing the operation was used as the | |
| committer email in the current patch set, the same email will be used as the committer email in the | |
| new patch set; otherwise, the user's preferred email will be used. | |
| The operated change is treated as the chain tip. All unsubmitted ancestors are rebased. | |
| Requires a linear ancestry relation (single parenting throughout the chain). | |
| Optionally, the parent revision (of the oldest ancestor to be rebased) can be changed to another | |
| change, revision or branch through the link:#rebase-input[RebaseInput] entity. | |
| Providing a `committer_email` through the link:#rebase-input[RebaseInput] entity is not supported | |
| when rebasing a chain. | |
| If the chain is outdated, i.e., there's a change that depends on an old revision of its parent, the | |
| result is the same as individually rebasing all outdated changes on top of their parent's latest | |
| revision before running the rebase chain action. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I08a021fb07b83fe845140a2c11508b3bdd93b48f/rebase:chain HTTP/1.0 | |
| Content-Type: application/json;charset=UTF-8 | |
| { | |
| "base" : "1234", | |
| } | |
| ---- | |
| As response a link:#rebase-chain-info[RebaseChainInfo] entity is returned that | |
| describes the rebased changes. Information about the current patch sets | |
| are included. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "rebased_changes": [ | |
| { | |
| "id": "myProject~master~I0e534de9d7f0d6f35b71f7d726acf835b2110c66", | |
| "project": "myProject", | |
| "branch": "master", | |
| "hashtags": [ | |
| ], | |
| "change_id": "I0e534de9d7f0d6f35b71f7d726acf835b2110c66", | |
| "subject": "456", | |
| "status": "NEW", | |
| "created": "2022-11-21 20: 51: 31.000000000", | |
| "updated": "2022-11-21 20: 56: 49.000000000", | |
| "submit_type": "MERGE_IF_NECESSARY", | |
| "insertions": 0, | |
| "deletions": 0, | |
| "total_comment_count": 0, | |
| "unresolved_comment_count": 0, | |
| "has_review_started": true, | |
| "meta_rev_id": "a2a6692213f546e1045ecf4647439fac8d6d8faa", | |
| "_number": 21, | |
| "owner": { | |
| "_account_id": 1000000 | |
| }, | |
| "current_revision_number": 2, | |
| "current_revision": "c3b2ba222d42a56e05c90f88d4509a124620517d", | |
| "revisions": { | |
| "c3b2ba222d42a56e05c90f88d4509a124620517d": { | |
| "kind": "NO_CHANGE", | |
| "_number": 2, | |
| "created": "2022-11-21 20: 56: 49.000000000", | |
| "uploader": { | |
| "_account_id": 1000000 | |
| }, | |
| "ref": "refs/changes/21/21/2", | |
| "fetch": { | |
| }, | |
| "commit": { | |
| "parents": [ | |
| { | |
| "commit": "7803f427dd7c4a2441466e4d740a1850dcee1af4", | |
| "subject": "123" | |
| } | |
| ], | |
| "author": { | |
| "name": "Nitzan Gur-Furman", | |
| "email": "nitzan@google.com", | |
| "date": "2022-11-21 20: 49: 39.000000000", | |
| "tz": 60 | |
| }, | |
| "committer": { | |
| "name": "Administrator", | |
| "email": "admin@example.com", | |
| "date": "2022-11-21 20: 56: 49.000000000", | |
| "tz": 60 | |
| }, | |
| "subject": "456", | |
| "message": "456\n" | |
| }, | |
| "description": "Rebase" | |
| } | |
| }, | |
| "requirements": [ | |
| ], | |
| "submit_records": [ | |
| { | |
| "rule_name": "gerrit~DefaultSubmitRule", | |
| "status": "NOT_READY", | |
| "labels": [ | |
| { | |
| "label": "Code-Review", | |
| "status": "NEED" | |
| } | |
| ] | |
| } | |
| ] | |
| }, | |
| { | |
| "id": "myProject~master~I08a021fb07b83fe845140a2c11508b3bdd93b48f", | |
| "project": "myProject", | |
| "branch": "master", | |
| "hashtags": [ | |
| ], | |
| "change_id": "I08a021fb07b83fe845140a2c11508b3bdd93b48f", | |
| "subject": "789", | |
| "status": "NEW", | |
| "created": "2022-11-21 20: 51: 31.000000000", | |
| "updated": "2022-11-21 20: 56: 49.000000000", | |
| "submit_type": "MERGE_IF_NECESSARY", | |
| "insertions": 0, | |
| "deletions": 0, | |
| "total_comment_count": 0, | |
| "unresolved_comment_count": 0, | |
| "has_review_started": true, | |
| "meta_rev_id": "3bfb843fea471f96e16b9199c3a30fff0285bc45", | |
| "_number": 22, | |
| "owner": { | |
| "_account_id": 1000000 | |
| }, | |
| "current_revision_number": 2, | |
| "current_revision": "77eb17a9501a5c21963bc6af56085e60f281acbb", | |
| "revisions": { | |
| "77eb17a9501a5c21963bc6af56085e60f281acbb": { | |
| "kind": "NO_CHANGE", | |
| "_number": 2, | |
| "created": "2022-11-21 20: 56: 49.000000000", | |
| "uploader": { | |
| "_account_id": 1000000 | |
| }, | |
| "ref": "refs/changes/22/22/2", | |
| "fetch": { | |
| }, | |
| "commit": { | |
| "parents": [ | |
| { | |
| "commit": "c3b2ba222d42a56e05c90f88d4509a124620517d", | |
| "subject": "456" | |
| } | |
| ], | |
| "author": { | |
| "name": "Nitzan Gur-Furman", | |
| "email": "nitzan@google.com", | |
| "date": "2022-11-21 20: 51: 07.000000000", | |
| "tz": 60 | |
| }, | |
| "committer": { | |
| "name": "Administrator", | |
| "email": "admin@example.com", | |
| "date": "2022-11-21 20: 56: 49.000000000", | |
| "tz": 60 | |
| }, | |
| "subject": "789", | |
| "message": "789\n" | |
| }, | |
| "description": "Rebase" | |
| } | |
| }, | |
| "requirements": [ | |
| ], | |
| "submit_records": [ | |
| { | |
| "rule_name": "gerrit~DefaultSubmitRule", | |
| "status": "NOT_READY", | |
| "labels": [ | |
| { | |
| "label": "Code-Review", | |
| "status": "NEED" | |
| } | |
| ] | |
| } | |
| ] | |
| } | |
| ], | |
| } | |
| ---- | |
| If the change cannot be rebased, e.g. due to conflicts, the response is | |
| "`409 Conflict`" and the error message is contained in the response | |
| body. | |
| .Response | |
| ---- | |
| HTTP/1.1 409 Conflict | |
| Content-Disposition: attachment | |
| Content-Type: text/plain; charset=UTF-8 | |
| Change I0e534de9d7f0d6f35b71f7d726acf835b2110c66 could not be rebased due to a conflict during | |
| merge. | |
| merge conflict(s): | |
| a.txt | |
| ---- | |
| [[move-change]] | |
| === Move Change | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/move' | |
| -- | |
| Move a change. | |
| The destination branch must be provided in the request body inside a | |
| link:#move-input[MoveInput] entity. | |
| Only veto votes that are blocking the change from submission are moved to | |
| the destination branch by default. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/move HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "destination_branch" : "release-branch" | |
| } | |
| ---- | |
| As response a link:#change-info[ChangeInfo] entity is returned that | |
| describes the moved change. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "id": "myProject~release-branch~I8473b95934b5732ac55d26311a706c9c2bde9940", | |
| "project": "myProject", | |
| "branch": "release-branch", | |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", | |
| "subject": "Implementing Feature X", | |
| "status": "NEW", | |
| "created": "2013-02-01 09:59:32.126000000", | |
| "updated": "2013-02-21 11:16:36.775000000", | |
| "mergeable": true, | |
| "insertions": 2, | |
| "deletions": 13, | |
| "_number": 3965, | |
| "owner": { | |
| "name": "John Doe" | |
| }, | |
| "current_revision_number": 2 | |
| } | |
| ---- | |
| Note that this endpoint will not update the change's parents, which is | |
| different from the link:#cherry-pick[cherry-pick] endpoint. | |
| If the change cannot be moved because the change state doesn't | |
| allow moving the change, the response is "`409 Conflict`" and | |
| the error message is contained in the response body. | |
| .Response | |
| ---- | |
| HTTP/1.1 409 Conflict | |
| Content-Disposition: attachment | |
| Content-Type: text/plain; charset=UTF-8 | |
| change is merged | |
| ---- | |
| If the change cannot be moved because the user doesn't have | |
| abandon permission on the change or upload permission on the destination, | |
| the response is "`409 Conflict`" and the error message is contained in the | |
| response body. | |
| .Response | |
| ---- | |
| HTTP/1.1 409 Conflict | |
| Content-Disposition: attachment | |
| Content-Type: text/plain; charset=UTF-8 | |
| move not permitted | |
| ---- | |
| [[revert-change]] | |
| === Revert Change | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/revert' | |
| -- | |
| Reverts a change. | |
| The subject of the newly created change will be | |
| 'Revert "<subject-of-reverted-change>"'. If the subject of the change reverted is | |
| above 63 characters, it will be cut down to 59 characters with "..." in the end. | |
| The request body does not need to include a link:#revert-input[ | |
| RevertInput] entity if no review comment is added. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I1ffe09a505e25f15ce1521bcfb222e51e62c2a14/revert HTTP/1.0 | |
| ---- | |
| As response a link:#change-info[ChangeInfo] entity is returned that | |
| describes the reverting change. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", | |
| "project": "myProject", | |
| "branch": "master", | |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", | |
| "subject": "Revert \"Implementing Feature X\"", | |
| "status": "NEW", | |
| "created": "2013-02-01 09:59:32.126000000", | |
| "updated": "2013-02-21 11:16:36.775000000", | |
| "mergeable": true, | |
| "insertions": 6, | |
| "deletions": 4, | |
| "_number": 3965, | |
| "owner": { | |
| "name": "John Doe" | |
| }, | |
| "current_revision_number": 2 | |
| } | |
| ---- | |
| If the user doesn't have revert permission on the change or upload permission on | |
| the destination branch, the response is "`403 Forbidden`", and the error message is | |
| contained in the response body. | |
| If the change cannot be reverted because the change state doesn't | |
| allow reverting the change the response is "`409 Conflict`", and the error | |
| message is contained in the response body. | |
| .Response | |
| ---- | |
| HTTP/1.1 409 Conflict | |
| Content-Disposition: attachment | |
| Content-Type: text/plain; charset=UTF-8 | |
| change is new | |
| ---- | |
| [[revert-submission]] | |
| === Revert Submission | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/revert_submission' | |
| -- | |
| Creates open revert changes for all of the changes of a certain submission. | |
| The subject of each revert change will be 'Revert "<subject-of-reverted-change"'. | |
| If the subject is above 60 characters, the subject will be cut to 56 characters | |
| with "..." in the end. However, whenever reverting the submission of a revert | |
| submission, the subject will be shortened from | |
| 'Revert "Revert "<subject-of-reverted-change""' to | |
| 'Revert^2 "<subject-of-reverted-change"'. Also, for every future revert submission, | |
| the only difference in the subject will be the number of the revert (instead of | |
| Revert^2 the subject will change to Revert^3 and so on). | |
| There are no guarantees about the subjects if the users change the default subjects. | |
| Details for the revert can be specified in the request body inside a link:#revert-input[ | |
| RevertInput] The topic of all created revert changes will be | |
| `revert-{submission_id}-{random_string_of_size_10}`. | |
| The changes will not be rebased on onto the destination branch so the users may still | |
| have to manually rebase them to resolve conflicts and make them submittable. | |
| However, the changes that have the same project and branch will be rebased on top | |
| of each other. E.g, the first revert change will have the original change as a | |
| parent, and the second revert change will have the first revert change as a | |
| parent. | |
| There is one special case that involves merge commits; if a user has multiple | |
| changes in the same project and branch, but not in the same change series, those | |
| changes can still get submitted together if they have the same topic and | |
| link:config-gerrit.html#change.submitWholeTopic[`change.submitWholeTopic`] in | |
| gerrit.config is set to true. In the case, Gerrit may create merge commits on | |
| submit (depending on the link:config-project-config.html#submit-type[submit types] | |
| of the project). | |
| The first parent for the reverts will be the most recent merge commit that was | |
| created by Gerrit to merge the different change series into the target branch. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I1ffe09a505e25f15ce1521bcfb222e51e62c2a14/revert_submission HTTP/1.0 | |
| ---- | |
| As response link:#revert-submission-info[RevertSubmissionInfo] entity | |
| is returned. That entity describes the revert changes. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| "revert_changes": | |
| [ | |
| { | |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", | |
| "project": "myProject", | |
| "branch": "master", | |
| "topic": "revert--1571043962462-3640749-ABCEEZGHIJ", | |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", | |
| "subject": "Revert \"Implementing Feature X\"", | |
| "status": "NEW", | |
| "created": "2013-02-01 09:59:32.126000000", | |
| "updated": "2013-02-21 11:16:36.775000000", | |
| "mergeable": true, | |
| "insertions": 6, | |
| "deletions": 4, | |
| "_number": 3965, | |
| "owner": { | |
| "name": "John Doe" | |
| }, | |
| "current_revision_number": 2 | |
| }, | |
| { | |
| "id": "anyProject~master~1eee2c9d8f352483781e772f35dc586a69ff5646", | |
| "project": "anyProject", | |
| "branch": "master", | |
| "topic": "revert--1571043962462-3640749-ABCEEZGHIJ", | |
| "change_id": "I1eee2c9d8f352483781e772f35dc586a69ff5646", | |
| "subject": "Revert \"Implementing Feature Y\"", | |
| "status": "NEW", | |
| "created": "2013-02-04 09:59:33.126000000", | |
| "updated": "2013-02-21 11:16:37.775000000", | |
| "mergeable": true, | |
| "insertions": 62, | |
| "deletions": 11, | |
| "_number": 3966, | |
| "owner": { | |
| "name": "Jane Doe" | |
| }, | |
| "current_revision_number": 2 | |
| } | |
| ] | |
| ---- | |
| If the user doesn't have revert permission on the change or upload permission on | |
| the destination, the response is "`403 Forbidden`", and the error message is | |
| contained in the response body. | |
| If the change cannot be reverted because the change state doesn't | |
| allow reverting the change the response is "`409 Conflict`", and the error | |
| message is contained in the response body. | |
| .Response | |
| ---- | |
| HTTP/1.1 409 Conflict | |
| Content-Disposition: attachment | |
| Content-Type: text/plain; charset=UTF-8 | |
| change is new | |
| ---- | |
| [[submit-change]] | |
| === Submit Change | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/submit' | |
| -- | |
| Submits a change. | |
| If the submission results in a new patch set (due to a rebase or cherry-pick merge method), the | |
| committer email will remain the same as the one used in the previous commit, provided that one of | |
| the secondary emails associated with the user performing the operation was used as the committer | |
| email in the previous commit. Otherwise, the user's preferred email will be used. | |
| The request body only needs to include a link:#submit-input[ | |
| SubmitInput] entity if submitting on behalf of another user. | |
| Submitting a change also removes all users from the link:user-attention-set.html[attention set]. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/submit HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "on_behalf_of": 1001439 | |
| } | |
| ---- | |
| As response a link:#change-info[ChangeInfo] entity is returned that | |
| describes the submitted/merged change. | |
| Submission may submit multiple changes, but we still only return one ChangeInfo | |
| object. To query for all submitted changes, please use the submission_id that is | |
| part of the response. | |
| Changes that will also be submitted: | |
| 1. All changes of the same topic if | |
| link:config-gerrit.html#change.submitWholeTopic[`change.submitWholeTopic`] | |
| configuration is set to true. | |
| 2. All dependent changes. | |
| 3. The closure of the above (e.g if a dependent change has a topic, all changes | |
| of *that* topic will also be submitted). | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", | |
| "project": "myProject", | |
| "branch": "master", | |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", | |
| "subject": "Implementing Feature X", | |
| "status": "MERGED", | |
| "created": "2013-02-01 09:59:32.126000000", | |
| "updated": "2013-02-21 11:16:36.775000000", | |
| "submitted": "2013-02-21 11:16:36.615000000", | |
| "_number": 3965, | |
| "owner": { | |
| "name": "John Doe" | |
| }, | |
| "current_revision_number": 2 | |
| } | |
| ---- | |
| If the change cannot be submitted because the submit rule doesn't allow | |
| submitting the change, the response is "`409 Conflict`" and the error | |
| message is contained in the response body. | |
| .Response | |
| ---- | |
| HTTP/1.1 409 Conflict | |
| Content-Disposition: attachment | |
| Content-Type: text/plain; charset=UTF-8 | |
| blocked by Verified | |
| ---- | |
| [[submitted-together]] | |
| === Changes Submitted Together | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/submitted_together?o=NON_VISIBLE_CHANGES' | |
| -- | |
| Computes list of all changes which are submitted when | |
| link:#submit-change[Submit] is called for this change, | |
| including the current change itself. | |
| The list consists of: | |
| * The given change. | |
| * If link:config-gerrit.html#change.submitWholeTopic[`change.submitWholeTopic`] | |
| is enabled OR if the `o=TOPIC_CLOSURE` query parameter is passed, include all | |
| open changes with the same topic. | |
| * For each change whose submit type is not CHERRY_PICK, include unmerged | |
| ancestors targeting the same branch. | |
| As a special case, the list is empty if this change would be | |
| submitted by itself (without other changes). | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/submitted_together?o=NON_VISIBLE_CHANGES HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| ---- | |
| As a response a link:#submitted-together-info[SubmittedTogetherInfo] | |
| entity is returned that describes what would happen if the change were | |
| submitted. This response contains a list of changes and a count of | |
| changes that are not visible to the caller that are part of the set of | |
| changes to be merged. | |
| The listed changes use the same format as in | |
| link:#list-changes[Query Changes] with the | |
| link:#labels[`LABELS`], link:#detailed-labels[`DETAILED_LABELS`], | |
| link:#current-revision[`CURRENT_REVISION`],and | |
| link:#submittable[`SUBMITTABLE`] options set. | |
| Standard link:#query-options[formatting options] can be specified | |
| with the `o` parameter, as well as the `submitted_together` specific | |
| options `NON_VISIBLE_CHANGES` and `TOPIC_CLOSURE`. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "changes": [ | |
| { | |
| "id": "gerrit~master~I1ffe09a505e25f15ce1521bcfb222e51e62c2a14", | |
| "project": "gerrit", | |
| "branch": "master", | |
| "hashtags": [], | |
| "change_id": "I1ffe09a505e25f15ce1521bcfb222e51e62c2a14", | |
| "subject": "ChangeMergeQueue: Rewrite such that it works on set of changes", | |
| "status": "NEW", | |
| "created": "2015-05-01 15:39:57.979000000", | |
| "updated": "2015-05-20 19:25:21.592000000", | |
| "mergeable": true, | |
| "insertions": 303, | |
| "deletions": 210, | |
| "_number": 1779, | |
| "owner": { | |
| "_account_id": 1000000 | |
| }, | |
| "labels": { | |
| "Code-Review": { | |
| "approved": { | |
| "_account_id": 1000000 | |
| }, | |
| "all": [ | |
| { | |
| "value": 2, | |
| "date": "2015-05-20 19:25:21.592000000", | |
| "_account_id": 1000000 | |
| } | |
| ], | |
| "values": { | |
| "-2": "This shall not be submitted", | |
| "-1": "I would prefer this is not submitted as is", | |
| " 0": "No score", | |
| "+1": "Looks good to me, but someone else must approve", | |
| "+2": "Looks good to me, approved" | |
| }, | |
| "default_value": 0 | |
| }, | |
| "Verified": { | |
| "approved": { | |
| "_account_id": 1000000 | |
| }, | |
| "all": [ | |
| { | |
| "value": 1, | |
| "date": "2015-05-20 19:25:21.592000000", | |
| "_account_id": 1000000 | |
| } | |
| ], | |
| "values": { | |
| "-1": "Fails", | |
| " 0": "No score", | |
| "+1": "Verified" | |
| }, | |
| "default_value": 0 | |
| } | |
| }, | |
| "permitted_labels": { | |
| "Code-Review": [ | |
| "-2", | |
| "-1", | |
| " 0", | |
| "+1", | |
| "+2" | |
| ], | |
| "Verified": [ | |
| "-1", | |
| " 0", | |
| "+1" | |
| ] | |
| }, | |
| "removable_reviewers": [ | |
| { | |
| "_account_id": 1000000 | |
| } | |
| ], | |
| "reviewers": { | |
| "REVIEWER": [ | |
| { | |
| "_account_id": 1000000 | |
| } | |
| ] | |
| }, | |
| "current_revision_number": 1, | |
| "current_revision": "9adb9f4c7b40eeee0646e235de818d09164d7379", | |
| "revisions": { | |
| "9adb9f4c7b40eeee0646e235de818d09164d7379": { | |
| "kind": "REWORK", | |
| "_number": 1, | |
| "created": "2015-05-01 15:39:57.979000000", | |
| "uploader": { | |
| "_account_id": 1000000 | |
| }, | |
| "ref": "refs/changes/79/1779/1", | |
| "fetch": {}, | |
| } | |
| } | |
| }, | |
| { | |
| "id": "gerrit~master~I7fe807e63792b3d26776fd1422e5e790a5697e22", | |
| "project": "gerrit", | |
| "branch": "master", | |
| "hashtags": [], | |
| "change_id": "I7fe807e63792b3d26776fd1422e5e790a5697e22", | |
| "subject": "AbstractSubmoduleSubscription: Split up createSubscription", | |
| "status": "NEW", | |
| "created": "2015-05-01 15:39:57.979000000", | |
| "updated": "2015-05-20 19:25:21.546000000", | |
| "mergeable": true, | |
| "insertions": 15, | |
| "deletions": 6, | |
| "_number": 1780, | |
| "owner": { | |
| "_account_id": 1000000 | |
| }, | |
| "labels": { | |
| "Code-Review": { | |
| "approved": { | |
| "_account_id": 1000000 | |
| }, | |
| "all": [ | |
| { | |
| "value": 2, | |
| "date": "2015-05-20 19:25:21.546000000", | |
| "_account_id": 1000000 | |
| } | |
| ], | |
| "values": { | |
| "-2": "This shall not be submitted", | |
| "-1": "I would prefer this is not submitted as is", | |
| " 0": "No score", | |
| "+1": "Looks good to me, but someone else must approve", | |
| "+2": "Looks good to me, approved" | |
| }, | |
| "default_value": 0 | |
| }, | |
| "Verified": { | |
| "approved": { | |
| "_account_id": 1000000 | |
| }, | |
| "all": [ | |
| { | |
| "value": 1, | |
| "date": "2015-05-20 19:25:21.546000000", | |
| "_account_id": 1000000 | |
| } | |
| ], | |
| "values": { | |
| "-1": "Fails", | |
| " 0": "No score", | |
| "+1": "Verified" | |
| }, | |
| "default_value": 0 | |
| } | |
| }, | |
| "permitted_labels": { | |
| "Code-Review": [ | |
| "-2", | |
| "-1", | |
| " 0", | |
| "+1", | |
| "+2" | |
| ], | |
| "Verified": [ | |
| "-1", | |
| " 0", | |
| "+1" | |
| ] | |
| }, | |
| "removable_reviewers": [ | |
| { | |
| "_account_id": 1000000 | |
| } | |
| ], | |
| "reviewers": { | |
| "REVIEWER": [ | |
| { | |
| "_account_id": 1000000 | |
| } | |
| ] | |
| }, | |
| "current_revision_number": 1, | |
| "current_revision": "1bd7c12a38854a2c6de426feec28800623f492c4", | |
| "revisions": { | |
| "1bd7c12a38854a2c6de426feec28800623f492c4": { | |
| "kind": "REWORK", | |
| "_number": 1, | |
| "created": "2015-05-01 15:39:57.979000000", | |
| "uploader": { | |
| "_account_id": 1000000 | |
| }, | |
| "ref": "refs/changes/80/1780/1", | |
| "fetch": {}, | |
| } | |
| } | |
| } | |
| ], | |
| "non_visible_changes": 0 | |
| } | |
| ---- | |
| If the `o=NON_VISIBLE_CHANGES` query parameter is not passed, then | |
| instead of a link:#submitted-together-info[SubmittedTogetherInfo] | |
| entity, the response is a list of changes, or a 403 response with a | |
| message if the set of changes to be submitted with this change | |
| includes changes the caller cannot read. | |
| [[delete-change]] | |
| === Delete Change | |
| -- | |
| 'DELETE /changes/link:#change-id[\{change-id\}]' | |
| -- | |
| Deletes a change. | |
| New or abandoned changes can be deleted by their owner if the user is granted | |
| the link:access-control.html#category_delete_own_changes[Delete Own Changes] permission, | |
| otherwise only by administrators. | |
| .Request | |
| ---- | |
| DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940 HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 204 No Content | |
| ---- | |
| [[apply-patch]] | |
| === Create patch-set from patch | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/patch:apply' | |
| -- | |
| Creates a new patch set on a destination change from the provided patch. | |
| If one of the secondary emails associated with the user performing the operation was used as the | |
| committer email in the current patch set, the same email will be used as the committer email in the | |
| new patch set; otherwise, the user's preferred email will be used. | |
| The patch must be provided in the request body, inside a | |
| link:#applypatchpatchset-input[ApplyPatchPatchSetInput] entity. | |
| If a base commit is given, the patch is applied on top of it. Otherwise, the | |
| patch is applied on top of the target change's original parent. | |
| Applying the patch will fail if the destination change is closed, or in case of any conflicts. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/patch:apply HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "patch": { | |
| "patch": "new file mode 100644\n--- /dev/null\n+++ b/a_new_file.txt\n@@ -0,0 +1,2 @@ \ | |
| +Patch compatible `git diff` output \ | |
| +For example: `link:#get-patch[<gerrit patch>] | base64 -d | sed -z 's/\n/\\n/g'`" | |
| } | |
| } | |
| ---- | |
| As response a link:#change-info[ChangeInfo] entity is returned that | |
| describes the destination change after applying the patch. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9941", | |
| "project": "myProject", | |
| "branch": "release-branch", | |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9941", | |
| "subject": "Original change subject", | |
| "status": "NEW", | |
| "created": "2013-02-01 09:59:32.126000000", | |
| "updated": "2013-02-21 11:16:36.775000000", | |
| "mergeable": true, | |
| "insertions": 12, | |
| "deletions": 11, | |
| "_number": 3965, | |
| "owner": { | |
| "name": "John Doe" | |
| }, | |
| "current_revision_number": 1, | |
| "current_revision": "184ebe53805e102605d11f6b143486d15c23a09c" | |
| } | |
| ---- | |
| [[get-included-in]] | |
| === Get Included In | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/in' | |
| -- | |
| Retrieves the branches and tags in which a change is included. As result | |
| an link:#included-in-info[IncludedInInfo] entity is returned. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/in HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "branches": [ | |
| "master" | |
| ], | |
| "tags": [] | |
| } | |
| ---- | |
| [[index-change]] | |
| === Index Change | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/index' | |
| -- | |
| Adds or updates the change in the secondary index. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/index HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 204 No Content | |
| ---- | |
| [[list-change-comments]] | |
| === List Change Comments | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/comments' | |
| -- | |
| Lists the published comments of all revisions of the change. | |
| Returns a map of file paths to lists of link:#comment-info[CommentInfo] | |
| entries. The entries in the map are sorted by file path, and the | |
| comments for each path are sorted by patch set number. Each comment has | |
| the `patch_set` and `author` fields set. | |
| If the `enable-context` request parameter is set to true, the comment entries | |
| will contain a list of link:#context-line[ContextLine] containing the lines of | |
| the source file where the comment was written. | |
| The `context-padding` request parameter can be used to specify an extra number | |
| of context lines to be added before and after the comment range. This parameter | |
| only works if `enable-context` is set to true. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/comments HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": [ | |
| { | |
| "patch_set": 1, | |
| "id": "TvcXrmjM", | |
| "line": 23, | |
| "message": "[nit] trailing whitespace", | |
| "updated": "2013-02-26 15:40:43.986000000" | |
| "author": { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com" | |
| } | |
| }, | |
| { | |
| "patch_set": 2, | |
| "id": "TveXwFiA", | |
| "line": 49, | |
| "in_reply_to": "TfYX-Iuo", | |
| "message": "Done", | |
| "updated": "2013-02-26 15:40:45.328000000" | |
| "author": { | |
| "_account_id": 1000097, | |
| "name": "Jane Roe", | |
| "email": "jane.roe@example.com" | |
| } | |
| } | |
| ] | |
| } | |
| ---- | |
| [[list-change-drafts]] | |
| === List Change Drafts | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/drafts' | |
| -- | |
| Lists the draft comments of all revisions of the change that belong to | |
| the calling user. | |
| Returns a map of file paths to lists of link:#comment-info[CommentInfo] | |
| entries. The entries in the map are sorted by file path, and the | |
| comments for each path are sorted by patch set number. Each comment has | |
| the `patch_set` field set, and no `author`. | |
| The `enable-context` and `context-padding` request parameters can be used to | |
| request comment context. See link:#list-change-comments[List Change Comments] | |
| for more details. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/drafts HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": [ | |
| { | |
| "patch_set": 1, | |
| "id": "TvcXrmjM", | |
| "line": 23, | |
| "message": "[nit] trailing whitespace", | |
| "updated": "2013-02-26 15:40:43.986000000" | |
| }, | |
| { | |
| "patch_set": 2, | |
| "id": "TveXwFiA", | |
| "line": 49, | |
| "in_reply_to": "TfYX-Iuo", | |
| "message": "Done", | |
| "updated": "2013-02-26 15:40:45.328000000" | |
| } | |
| ] | |
| } | |
| ---- | |
| [[check-change]] | |
| === Check Change | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/check' | |
| -- | |
| Performs consistency checks on the change, and returns a | |
| link:#change-info[ChangeInfo] entity with the `problems` field set to a | |
| list of link:#problem-info[ProblemInfo] entities. | |
| Depending on the type of problem, some fields not marked optional may be | |
| missing from the result. At least `id`, `project`, `branch`, and | |
| `_number` will be present. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/check HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", | |
| "project": "myProject", | |
| "branch": "master", | |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", | |
| "subject": "Implementing Feature X", | |
| "status": "NEW", | |
| "created": "2013-02-01 09:59:32.126000000", | |
| "updated": "2013-02-21 11:16:36.775000000", | |
| "mergeable": true, | |
| "insertions": 34, | |
| "deletions": 101, | |
| "_number": 3965, | |
| "owner": { | |
| "name": "John Doe" | |
| }, | |
| "current_revision_number": 2, | |
| "problems": [ | |
| { | |
| "message": "Current patch set 1 not found" | |
| } | |
| ] | |
| } | |
| ---- | |
| [[fix-change]] | |
| === Fix Change | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/check' | |
| -- | |
| Performs consistency checks on the change as with link:#check-change[GET | |
| /check], and additionally fixes any problems that can be fixed | |
| automatically. The returned field values reflect any fixes. | |
| Some fixes have options controlling their behavior, which can be set in the | |
| link:#fix-input[FixInput] entity body. | |
| Only the change owner, a project owner, or an administrator may fix changes. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/check HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", | |
| "project": "myProject", | |
| "branch": "master", | |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", | |
| "subject": "Implementing Feature X", | |
| "status": "MERGED", | |
| "created": "2013-02-01 09:59:32.126000000", | |
| "updated": "2013-02-21 11:16:36.775000000", | |
| "submitted": "2013-02-21 11:16:36.615000000", | |
| "mergeable": true, | |
| "insertions": 34, | |
| "deletions": 101, | |
| "_number": 3965, | |
| "owner": { | |
| "name": "John Doe" | |
| }, | |
| "current_revision_number": 2, | |
| "problems": [ | |
| { | |
| "message": "Current patch set 2 not found" | |
| }, | |
| { | |
| "message": "Patch set 1 (1eee2c9d8f352483781e772f35dc586a69ff5646) is merged into destination ref master (1eee2c9d8f352483781e772f35dc586a69ff5646), but change status is NEW", | |
| "status": FIXED, | |
| "outcome": "Marked change as merged" | |
| } | |
| ] | |
| } | |
| ---- | |
| [[set-work-in-progress]] | |
| === Set Work-In-Progress | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/wip' | |
| -- | |
| Marks the change as not ready for review yet. Changes may only be marked not | |
| ready by the owner, project owners or site administrators. | |
| The request body does not need to include a | |
| link:#work-in-progress-input[WorkInProgressInput] entity if no review comment | |
| is added. Actions that create a new patch set in a WIP change default to | |
| notifying *OWNER* instead of *ALL*. | |
| Marking a change work in progress also removes all users from the | |
| link:user-attention-set.html[attention set]. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/wip HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "message": "Refactoring needs to be done before we can proceed here." | |
| } | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| ---- | |
| [[set-ready-for-review]] | |
| === Set Ready-For-Review | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/ready' | |
| -- | |
| Marks the change as ready for review (set WIP property to false). Changes may | |
| only be marked ready by the owner, project owners or site administrators. | |
| Activates notifications of reviewer. The request body does not need | |
| to include a link:#work-in-progress-input[WorkInProgressInput] entity | |
| if no review comment is added. | |
| Marking a change ready for review also adds all of the reviewers of the change | |
| to the link:user-attention-set.html[attention set]. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/ready HTTP/1.0 | |
| Content-Type: application/json;charset=UTF-8 | |
| { | |
| "message": "Refactoring is done." | |
| } | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| ---- | |
| [[mark-private]] | |
| === Mark Private | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/private' | |
| -- | |
| Marks the change to be private. Only open changes can be marked private. | |
| Changes may only be marked private by the owner or site administrators. | |
| A message can be specified in the request body inside a | |
| link:#private-input[PrivateInput] entity. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/private HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "message": "After this security fix has been released we can make it public now." | |
| } | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 201 Created | |
| ---- | |
| If the change was already private the response is "`200 OK`". | |
| [[unmark-private]] | |
| === Unmark Private | |
| -- | |
| 'DELETE /changes/link:#change-id[\{change-id\}]/private' | |
| -- | |
| Marks the change to be non-private. Note users can only unmark own private | |
| changes. | |
| .Request | |
| ---- | |
| DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/private HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 204 No Content | |
| ---- | |
| If the change was already not private, the response is "`409 Conflict`". | |
| A message can be specified in the request body inside a | |
| link:#private-input[PrivateInput] entity. Historically, this method allowed | |
| a body in the DELETE, but that behavior is | |
| link:https://www.gerritcodereview.com/releases/2.16.md[deprecated,role=external,window=_blank]. | |
| In this case, use a POST request instead: | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/private.delete HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "message": "This is a security fix that must not be public." | |
| } | |
| ---- | |
| [[get-hashtags]] | |
| === Get Hashtags | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/hashtags' | |
| -- | |
| Gets the hashtags associated with a change. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/hashtags HTTP/1.0 | |
| ---- | |
| As response the change's hashtags are returned as a list of strings. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| [ | |
| "hashtag1", | |
| "hashtag2" | |
| ] | |
| ---- | |
| [[set-hashtags]] | |
| === Set Hashtags | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/hashtags' | |
| -- | |
| Adds and/or removes hashtags from a change. | |
| The hashtags to add or remove must be provided in the request body inside a | |
| link:#hashtags-input[HashtagsInput] entity. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/hashtags HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "add" : [ | |
| "hashtag3" | |
| ], | |
| "remove" : [ | |
| "hashtag2" | |
| ] | |
| } | |
| ---- | |
| As response the change's hashtags are returned as a list of strings. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| [ | |
| "hashtag1", | |
| "hashtag3" | |
| ] | |
| ---- | |
| [[get-custom-keyed-values]] | |
| === Get Custom Keyed Values | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/custom_keyed_values' | |
| -- | |
| Gets the custom keyed values associated with a change. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/custom_keyed_values HTTP/1.0 | |
| ---- | |
| As response the change's custom keyed values are returned as a map of strings. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "key1": "value1", | |
| "key2": "value2" | |
| } | |
| ---- | |
| [[set-custom-keyed-values]] | |
| === Set Custom Keyed Values | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/custom_keyed_values' | |
| -- | |
| Adds and/or removes custom keyed values from a change. | |
| The custom keyed values to add or remove must be provided in the request body | |
| inside a link:#custom-keyed-values-input[CustomKeyedValuesInput] entity. | |
| Note that custom keyed values are expected to be small in both key and value. | |
| A typical use-case would be storing the ID to some external system, in which | |
| case the key would be something unique to that system and the value would be | |
| the ID. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/custom_keyed_values HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "add" : { | |
| "key1": "value1" | |
| }, | |
| "remove" : [ | |
| "key2" | |
| ] | |
| } | |
| ---- | |
| As response the change's custom keyed values are returned as a map of strings to strings. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "key1": "value1", | |
| "key3": "value3" | |
| } | |
| ---- | |
| [[validation-options]] | |
| === Get Validation Options | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/validation-options' | |
| -- | |
| Retrieves the validation options that apply to the change. | |
| .Request | |
| ---- | |
| GET /changes/link:#change-id[\{change-id\}]/validation-options HTTP/1.0 | |
| ---- | |
| As response a link:#validation-options-infos[ValidationOptionInfos] entity is | |
| returned that contains all the validation options. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| validation_options: [ | |
| { | |
| name: "optionName", | |
| description: "description of the validation option" | |
| } | |
| ] | |
| } | |
| ---- | |
| [[list-change-messages]] | |
| === List Change Messages | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/messages' | |
| -- | |
| Lists all the messages of a change including link:#detailed-accounts[detailed account information]. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/messages | |
| ---- | |
| As response a list of link:#change-message-info[ChangeMessageInfo] entities is returned. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| [ | |
| { | |
| "id": "YH-egE", | |
| "author": { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com", | |
| "username": "jdoe" | |
| }, | |
| "date": "2013-03-23 21:34:02.419000000", | |
| "message": "Patch Set 1:\n\nThis is the first message.", | |
| "_revision_number": 1 | |
| }, | |
| { | |
| "id": "WEEdhU", | |
| "author": { | |
| "_account_id": 1000097, | |
| "name": "Jane Roe", | |
| "email": "jane.roe@example.com", | |
| "username": "jroe" | |
| }, | |
| "date": "2013-03-23 21:36:52.332000000", | |
| "message": "Patch Set 1:\n\nThis is the second message.\n\nWith a line break.", | |
| "_revision_number": 1 | |
| } | |
| ] | |
| ---- | |
| [[get-change-message]] | |
| === Get Change Message | |
| Retrieves a change message including link:#detailed-accounts[detailed account information]. | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/messages/link:#change-message-id[\{change-message-id\}]' | |
| -- | |
| As response a link:#change-message-info[ChangeMessageInfo] entity is returned. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "id": "aaee04dcb46bafc8be24d8aa70b3b1beb7df5780", | |
| "author": { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com", | |
| "username": "jdoe" | |
| }, | |
| "date": "2013-03-23 21:34:02.419000000", | |
| "message": "a change message", | |
| "_revision_number": 1 | |
| } | |
| ---- | |
| [[delete-change-message]] | |
| === Delete Change Message | |
| -- | |
| 'DELETE /changes/link:#change-id[\{change-id\}]/messages/link:#change-message-id[\{change-message-id\}]' + | |
| 'POST /changes/link:#change-id[\{change-id\}]/messages/link:#change-message-id[\{change-message-id\}]/delete' | |
| -- | |
| Deletes a change message by replacing the change message with a new message, | |
| which contains the name of the user who deleted the change message and the | |
| reason why it was deleted. The reason can be provided in the request body as a | |
| link:#delete-change-message-input[DeleteChangeMessageInput] entity. | |
| Note that only users with the | |
| link:access-control.html#capability_administrateServer[Administrate Server] | |
| global capability are permitted to delete a change message. | |
| To delete a change message, send a DELETE request: | |
| .Request | |
| ---- | |
| DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/messages/aaee04dcb46bafc8be24d8aa70b3b1beb7df5780 HTTP/1.0 | |
| ---- | |
| To provide a reason for the deletion, use a POST request: | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/messages/aaee04dcb46bafc8be24d8aa70b3b1beb7df5780/delete HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "reason": "spam" | |
| } | |
| ---- | |
| As response a link:#change-message-info[ChangeMessageInfo] entity is returned that | |
| describes the updated change message. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "id": "aaee04dcb46bafc8be24d8aa70b3b1beb7df5780", | |
| "author": { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com", | |
| "username": "jdoe" | |
| }, | |
| "date": "2013-03-23 21:34:02.419000000", | |
| "message": "Change message removed by: Administrator\nReason: spam", | |
| "_revision_number": 1 | |
| } | |
| ---- | |
| [[check-submit-requirement]] | |
| === Check Submit Requirement | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/check.submit_requirement' | |
| -- | |
| Tests a submit requirement and returns the result as a | |
| link:#submit-requirement-result-info[SubmitRequirementResultInfo]. | |
| The submit requirement can be specified in one of the following ways: | |
| * In the request body as a link:#submit-requirement-input[SubmitRequirementInput]. | |
| * By passing the two request parameters `sr-name` and | |
| `refs-config-change-id`. The submit requirement will then be loaded from | |
| the project config pointed to by the latest patchset of this change ID. | |
| The `sr-name` should point to an existing submit-requirement and the | |
| `refs-config-change-id` must be a valid change identifier for a change in the | |
| refs/meta/config branch, otherwise the request would fail with | |
| `400 Bad Request`. | |
| Note that this endpoint does not modify the change resource. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/check.submit_requirement HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "name": "Code-Review", | |
| "submittability_expression": "label:Code-Review=+2" | |
| } | |
| ---- | |
| As response a link:#submit-requirement-result-info[SubmitRequirementResultInfo] | |
| entity is returned that describes the submit requirement result. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "name": "Code-Review", | |
| "status": "SATISFIED", | |
| "submittability_expression_result": { | |
| "expression": "label:Code-Review=+2", | |
| "fulfilled": true, | |
| "passingAtoms": [ | |
| "label:Code-Review=+2" | |
| ] | |
| }, | |
| "is_legacy": false | |
| } | |
| ---- | |
| [[evaluate-change-query-expression]] | |
| === Evaluate Change Query Expression | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/query?expression=\{expression\}' | |
| -- | |
| Evaluates whether the given change query expression matches the change. | |
| The following URL parameters are supported: | |
| [[change-query-expression]] | |
| -- | |
| * `expression`: link:user-search.html[Change query expression] for which it should be checked if | |
| the change matches. | |
| -- | |
| [[change-query-use-index]] | |
| -- | |
| * `use-index`: Whether the change query expression should be evaluated against the change state in | |
| the index. This is useful to avoid executing submit requirements when the query expression | |
| contains operators that require checking if the change is submittable (e.g. "is:submittable"). | |
| -- | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/query?expression=is:submittable label:Auto-Submit+1 HTTP/1.0 | |
| ---- | |
| As response a link:#evaluate-change-query-expression-result-info[ | |
| EvaluateChangeQueryExpressionResultInfo] entity is returned that describes whether the change | |
| matches the expression. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "status": false | |
| "passing_atoms": [ | |
| "label:Auto-Submit+1" | |
| ], | |
| "failing_atoms": [ | |
| "is:submittable" | |
| ] | |
| } | |
| ---- | |
| [[edit-endpoints]] | |
| == Change Edit Endpoints | |
| [[get-edit-detail]] | |
| === Get Change Edit Details | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/edit | |
| -- | |
| Retrieves the details of the change edit done by the caller to the given change. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit HTTP/1.0 | |
| ---- | |
| As response an link:#edit-info[EditInfo] entity is returned that | |
| describes the change edit, or "`204 No Content`" when change edit doesn't | |
| exist for this change. Change edits are stored on special branches and there | |
| can be max one edit per user per change. Edits aren't tracked in the database. | |
| When request parameter `list` is provided the response also includes the file | |
| list. When `base` request parameter is provided the file list is computed | |
| against this base revision. When request parameter `download-commands` is | |
| provided fetch info map is also included. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "commit": { | |
| "parents": [ | |
| { | |
| "commit": "1eee2c9d8f352483781e772f35dc586a69ff5646", | |
| } | |
| ], | |
| "author": { | |
| "name": "Shawn O. Pearce", | |
| "email": "sop@google.com", | |
| "date": "2012-04-24 18:08:08.000000000", | |
| "tz": -420 | |
| }, | |
| "committer": { | |
| "name": "Shawn O. Pearce", | |
| "email": "sop@google.com", | |
| "date": "2012-04-24 18:08:08.000000000", | |
| "tz": -420 | |
| }, | |
| "subject": "Use an EventBus to manage star icons", | |
| "message": "Use an EventBus to manage star icons\n\nImage widgets that need to ..." | |
| }, | |
| "base_patch_set_number": 1, | |
| "base_revision": "c35558e0925e6985c91f3a16921537d5e572b7a3", | |
| "ref": "refs/users/01/1000001/edit-76482/1" | |
| } | |
| ---- | |
| [[put-edit-file]] | |
| === Change file content in Change Edit | |
| -- | |
| 'PUT /changes/link:#change-id[\{change-id\}]/edit/path%2fto%2ffile' | |
| -- | |
| Put content of a file to a change edit. | |
| If one of the secondary emails associated with the user performing the operation was used as the | |
| committer email in the latest patch set, the same email will be used as the committer email in the | |
| new change edit commit; otherwise, the user's preferred email will be used. | |
| .Request | |
| ---- | |
| PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit/foo HTTP/1.0 | |
| ---- | |
| To upload a file as binary data a link:#file-content-input[FileContentInput] | |
| entity can be specified in the request body: | |
| .Request | |
| ---- | |
| PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit/foo HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "binary_content": "data:text/plain;base64,SGVsbG8sIFdvcmxkIQ==", | |
| "file_mode": 100755 | |
| } | |
| ---- | |
| When a change edit doesn't exist for this change yet it is created | |
| automatically. | |
| As response "`204 No Content`" is returned: | |
| .Response | |
| ---- | |
| HTTP/1.1 204 No Content | |
| ---- | |
| When the change edit is a no-op, for example when providing the same file | |
| content that the file already has, '409 no changes were made' is returned. | |
| .Response | |
| ---- | |
| HTTP/1.1 409 no changes were made | |
| ---- | |
| [[post-edit]] | |
| === Restore file content or rename files in Change Edit | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/edit' | |
| -- | |
| Creates empty change edit, restores file content or renames files in change | |
| edit. The request body needs to include a | |
| link:#change-edit-input[ChangeEditInput] entity when a file within change | |
| edit should be restored or old and new file names to rename a file. | |
| If one of the secondary emails associated with the user performing the operation was used as the | |
| committer email in the latest patch set, the same email will be used as the committer email in the | |
| new change edit commit; otherwise, the user's preferred email will be used. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "restore_path": "foo" | |
| } | |
| ---- | |
| or for rename: | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "old_path": "foo", | |
| "new_path": "bar" | |
| } | |
| ---- | |
| When change edit doesn't exist for this change yet it is created. When path | |
| and restore flag are provided in request body, this file is restored. When | |
| old and new file names are provided, the file is renamed. As response | |
| "`204 No Content`" is returned. | |
| .Response | |
| ---- | |
| HTTP/1.1 204 No Content | |
| ---- | |
| [[put-change-edit-message]] | |
| === Change commit message in Change Edit | |
| -- | |
| 'PUT /changes/link:#change-id[\{change-id\}]/edit:message' | |
| -- | |
| Modify commit message. The request body needs to include a | |
| link:#change-edit-message-input[ChangeEditMessageInput] | |
| entity. | |
| If one of the secondary emails associated with the user performing the operation was used as the | |
| committer email in the latest patch set, the same email will be used as the committer email in the | |
| new change edit commit; otherwise, the user's preferred email will be used. | |
| .Request | |
| ---- | |
| PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit:message HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "message": "New commit message\n\nChange-Id: I10394472cbd17dd12454f229e4f6de00b143a444" | |
| } | |
| ---- | |
| If a change edit doesn't exist for this change yet, it is created. As | |
| response "`204 No Content`" is returned. | |
| .Response | |
| ---- | |
| HTTP/1.1 204 No Content | |
| ---- | |
| [[delete-edit-file]] | |
| === Delete file in Change Edit | |
| -- | |
| 'DELETE /changes/link:#change-id[\{change-id\}]/edit/path%2fto%2ffile' | |
| -- | |
| Deletes a file from a change edit. This deletes the file from the repository | |
| completely. This is not the same as reverting or restoring a file to its | |
| previous contents. | |
| If one of the secondary emails associated with the user performing the operation was used as the | |
| committer email in the latest patch set, the same email will be used as the committer email in the | |
| new change edit commit; otherwise, the user's preferred email will be used. | |
| .Request | |
| ---- | |
| DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit/foo HTTP/1.0 | |
| ---- | |
| When change edit doesn't exist for this change yet it is created. | |
| .Response | |
| ---- | |
| HTTP/1.1 204 No Content | |
| ---- | |
| [[put-change-edit-committer-author-identity]] | |
| === Change author or committer identity in Change Edit | |
| -- | |
| 'PUT /changes/link:#change-id[\{change-id\}]/edit:identity' | |
| -- | |
| Modify author or committer identity. The request body needs to include a | |
| link:#change-edit-identity-input[ChangeEditIdentityInput] | |
| entity. Either `name` or `email` must be provided. `type` must be either `AUTHOR` or `COMMITTER`. | |
| .Request | |
| ---- | |
| PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit:identity HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "name": "John Doe", | |
| "email": "john.doe@example.com", | |
| "type": "COMMITTER" | |
| } | |
| ---- | |
| If a change edit doesn't exist for this change yet, it is created. As | |
| response "`204 No Content`" is returned. | |
| .Response | |
| ---- | |
| HTTP/1.1 204 No Content | |
| ---- | |
| [[get-edit-file]] | |
| === Retrieve file content from Change Edit | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/edit/path%2fto%2ffile | |
| -- | |
| Retrieves content of a file from a change edit. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit/foo HTTP/1.0 | |
| ---- | |
| The content of the file is returned as text encoded inside base64. | |
| The Content-Type header will always be `text/plain` reflecting the | |
| outer base64 encoding. A Gerrit-specific `X-FYI-Content-Type` header | |
| can be examined to find the server detected content type of the file. | |
| When the specified file was deleted in the change edit | |
| "`204 No Content`" is returned. | |
| If only the content type is required, callers should use HEAD to | |
| avoid downloading the encoded file contents. | |
| If the `base` parameter is set to true, the returned content is from the | |
| revision that the edit is based on. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: text/plain; charset=ISO-8859-1 | |
| X-FYI-Content-Encoding: base64 | |
| X-FYI-Content-Type: text/xml | |
| RnJvbSA3ZGFkY2MxNTNmZGVhMTdhYTg0ZmYzMmE2ZTI0NWRiYjY... | |
| ---- | |
| Alternatively, if the only value of the Accept request header is | |
| `application/json` the content is returned as JSON string and | |
| `X-FYI-Content-Encoding` is set to `json`. | |
| [[get-edit-meta-data]] | |
| === Retrieve meta data of a file from Change Edit | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/edit/path%2fto%2ffile/meta | |
| -- | |
| Retrieves meta data of a file from a change edit. Currently only | |
| web links are returned. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit/foo/meta HTTP/1.0 | |
| ---- | |
| This REST endpoint retrieves additional information for a file in a | |
| change edit. As result an link:#edit-file-info[EditFileInfo] entity is | |
| returned. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "web_links": [ | |
| { | |
| "show_on_side_by_side_diff_view": true, | |
| "name": "side-by-side preview diff", | |
| "image_url": "plugins/xdocs/static/sideBySideDiffPreview.png", | |
| "url": "#/x/xdocs/c/42/1..0/README.md", | |
| "target": "_self" | |
| }, | |
| { | |
| "show_on_unified_diff_view": true, | |
| "name": "unified preview diff", | |
| "image_url": "plugins/xdocs/static/unifiedDiffPreview.png", | |
| "url": "#/x/xdocs/c/42/1..0/README.md,unified", | |
| "target": "_self" | |
| } | |
| ]} | |
| ---- | |
| [[get-edit-message]] | |
| === Retrieve commit message from Change Edit or current patch set of the change | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/edit:message | |
| -- | |
| Retrieves commit message from change edit. | |
| If the `base` parameter is set to true, the returned message is from the | |
| revision that the edit is based on. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit:message HTTP/1.0 | |
| ---- | |
| The commit message is returned as base64 encoded string. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| VGhpcyBpcyBhIGNvbW1pdCBtZXNzYWdlCgpDaGFuZ2UtSWQ6IElhYzhmZGM1MGRlZjFiYWUzYjAz | |
| M2JhNjcxZTk0OTBmNzUxNDU5ZGUzCg== | |
| ---- | |
| Alternatively, if the only value of the Accept request header is | |
| `application/json` the commit message is returned as JSON string: | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| )]}' | |
| "Subject of the commit message\n\nThis is the body of the commit message.\n\nChange-Id: Iaf1ba916bf843c175673d675bf7f52862f452db9\n" | |
| ---- | |
| [[publish-edit]] | |
| === Publish Change Edit | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/edit:publish | |
| -- | |
| Promotes change edit to a regular patch set. | |
| Options can be provided in the request body as a | |
| link:#publish-change-edit-input[PublishChangeEditInput] entity. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit:publish HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "notify": "NONE" | |
| } | |
| ---- | |
| As response "`204 No Content`" is returned. | |
| .Response | |
| ---- | |
| HTTP/1.1 204 No Content | |
| ---- | |
| [[rebase-edit]] | |
| === Rebase Change Edit | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/edit:rebase' | |
| -- | |
| Rebases change edit on top of latest patch set. | |
| Optionally, input parameters may be specified in the request body as a | |
| link:#rebase-change-edit-input[RebaseChangeEditInput] entity. | |
| If one of the secondary emails associated with the user performing the operation was used as the | |
| committer email in the latest patch set, the same email will be used as the committer email in the | |
| new change edit commit; otherwise, the user's preferred email will be used. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit:rebase HTTP/1.0 | |
| ---- | |
| When the change was rebased on top of latest patch set, the response code is | |
| "`200 OK`" and the rebased change edit is returned as an | |
| link:#edit-info[EditInfo] entity. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "commit": { | |
| "parents": [ | |
| { | |
| "commit": "1eee2c9d8f352483781e772f35dc586a69ff5646", | |
| } | |
| ], | |
| "author": { | |
| "name": "Shawn O. Pearce", | |
| "email": "sop@google.com", | |
| "date": "2012-04-24 18:08:08.000000000", | |
| "tz": -420 | |
| }, | |
| "committer": { | |
| "name": "Shawn O. Pearce", | |
| "email": "sop@google.com", | |
| "date": "2012-04-24 18:08:08.000000000", | |
| "tz": -420 | |
| }, | |
| "subject": "Use an EventBus to manage star icons", | |
| "message": "Use an EventBus to manage star icons\n\nImage widgets that need to ..." | |
| }, | |
| "base_patch_set_number": s, | |
| "base_revision": "c35558e0925e6985c91f3a16921537d5e572b7a3", | |
| "ref": "refs/users/01/1000001/edit-76482/2" | |
| } | |
| ---- | |
| When the change edit is already based on top of the latest patch set, the | |
| response code is "`409 Conflict`". | |
| [[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 | |
| ---- | |
| [[flow-endpoints]] | |
| == Flow Endpoints | |
| [[is-flows-enabled]] | |
| === Is Flows Enabled | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/is-flows-enabled' | |
| -- | |
| Returns whether flows are enabled for this change. | |
| As result an link:#enabled-info[IsFlowsEnabledInfo] entity is returned. | |
| .Request | |
| ---- | |
| GET /changes/myProject~65178/is-flows-enabled HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "enabled": true | |
| } | |
| ---- | |
| [[list-flows]] | |
| === List Flows | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/flows/' | |
| -- | |
| Lists the flows of a change that are visible to the caller. | |
| As result a list of link:#flow-info[FlowInfo] entries is returned. | |
| The order of the returned flows is stable, but depends on the flow service | |
| implementation. | |
| .Request | |
| ---- | |
| GET /changes/myProject~65178/flows/ HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| [ | |
| { | |
| "uuid": "zgcFrmAM", | |
| "owner" { | |
| "_account_id": 1000600 | |
| }, | |
| "created": "2025-06-03 09:59:32.126000000", | |
| "stages": [ | |
| { | |
| "expression": { | |
| "condition": "com.google.gerrit[change:65779 is:merged]", | |
| "action": { | |
| "name": "MarkAsReady" | |
| } | |
| }, | |
| "state": "DONE" | |
| } | |
| ], | |
| "last_evaluated": "2025-06-03 10:32:12.083000000", | |
| }, | |
| { | |
| "uuid": "XvcXrmjM", | |
| "owner" { | |
| "_account_id": 1000600 | |
| }, | |
| "created": "2025-06-03 10:55:36.133000000", | |
| "stages": [ | |
| { | |
| "expression": { | |
| "condition": "com.google.gerrit[change:65178 label:Verified+1]", | |
| "action": { | |
| "name": "AddReviewer", | |
| "parameters": { | |
| "user": "foo@example.com" | |
| } | |
| } | |
| }, | |
| "state": "FAILED", | |
| "message": "user foo@example.com not found" | |
| }, | |
| { | |
| "expression": { | |
| "condition": "com.google.gerrit[change:65178 label:Code-Review+2]", | |
| "action": { | |
| "name": "Submit", | |
| "parameters": { | |
| "change": "65178" | |
| } | |
| } | |
| }, | |
| "state": "TERMINATED", | |
| "message": "stage 1 has failed" | |
| } | |
| ], | |
| "last_evaluated": "2025-06-03 12:12:10.084000000", | |
| } | |
| ] | |
| ---- | |
| Flows that are not visible to the caller are omitted from the result. Which | |
| permissions are required to see a flow depends on the flow service | |
| implementation. | |
| If no flow service is bound (i.e. if no plugin that provides a flow service is | |
| installed) `405 Method Not Allowed` is returned. | |
| [[flows-actions]] | |
| === List Flows Actions | |
| -- | |
| 'GET /changes/link:#change-id[{change-id}]/flows-actions/' | |
| -- | |
| Lists the flows actions that are configured for the given change. | |
| As result a list of link:#flow-action-type-info[FlowActionTypeInfo] entries is returned. | |
| .Request | |
| ---- | |
| GET /changes/myProject~65178/flows-actions/ HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| [ | |
| { | |
| "name": "add-reviewer" | |
| } | |
| ] | |
| ---- | |
| [[create-flow]] | |
| === Create Flow | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/flows/' | |
| -- | |
| Creates a flow on the change. | |
| The flow input must be provided as a link:#flow-input[FlowInput] entity in the | |
| request body. | |
| .Request | |
| ---- | |
| POST /changes/ HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "stage_expressions": [ | |
| { | |
| "condition": "com.google.gerrit[change:65178 label:Verified+1]", | |
| "action": { | |
| "name": "AddReviewer", | |
| "parameters": { | |
| "user": "foo@example.com" | |
| } | |
| } | |
| } | |
| ] | |
| } | |
| ---- | |
| The created flow is returned as a link:#flow-info[FlowInfo] entity. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "uuid": "XvcXrmjM", | |
| "owner" { | |
| "_account_id": 1000600 | |
| }, | |
| "created": "2025-06-03 09:59:32.126000000", | |
| "stages": [ | |
| { | |
| "expression": { | |
| "condition": "com.google.gerrit[change:65178 label:Verified+1]", | |
| "action": { | |
| "name": "AddReviewer", | |
| "parameters": { | |
| "user": "foo@example.com" | |
| } | |
| } | |
| } | |
| "state": "PENDING" | |
| } | |
| ] | |
| } | |
| ---- | |
| If the caller is not allowed to create the flow `403 Forbidden` is returned. | |
| Which permissions are required for creating a flow depends on the flow service | |
| implementation. | |
| If no flow service is bound (i.e. if no plugin that provides a flow service is | |
| installed) `405 Method Not Allowed` is returned. | |
| [[get-flow]] | |
| === Get Flow | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/flows/link:#flow-id[\{flow-id\}]' | |
| -- | |
| Gets a flow on the change. | |
| .Request | |
| ---- | |
| GET /changes/myProject~65178/flows/XvcXrmjM HTTP/1.0 | |
| ---- | |
| The flow is returned as a link:#flow-info[FlowInfo] entity. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "uuid": "XvcXrmjM", | |
| "owner" { | |
| "_account_id": 1000600 | |
| }, | |
| "created": "2025-06-03 09:59:32.126000000", | |
| "stages": [ | |
| { | |
| "expression": { | |
| "condition": "com.google.gerrit[change:65178 label:Verified+1]", | |
| "action": { | |
| "name": "AddReviewer", | |
| "parameters": { | |
| "user": "foo@example.com" | |
| } | |
| } | |
| } | |
| "state": "PENDING" | |
| } | |
| ] | |
| } | |
| ---- | |
| If the flow exists, but is not visible to the caller `404 Not Found` is | |
| returned. Which permissions are required to see a flow depends on the flow | |
| service implementation. | |
| If no flow service is bound (i.e. if no plugin that provides a flow service is | |
| installed) `405 Method Not Allowed` is returned. | |
| [[delete-flow]] | |
| === Delete Flow | |
| -- | |
| 'DELETE /changes/link:#change-id[\{change-id\}]/flows/link:#flow-id[\{flow-id\}]' | |
| -- | |
| Delete a flow on the change. | |
| .Request | |
| ---- | |
| DELETE /changes/myProject~65178/flows/XvcXrmjM HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 204 No Content | |
| ---- | |
| If the flow exists, but is not visible to the caller `404 Not Found` is | |
| returned. | |
| If the caller can see the flow but is not allowed to delete it `403 Forbidden` | |
| is returned. Which permissions are required to delete a flow depends on the flow | |
| service implementation. | |
| If no flow service is bound (i.e. if no plugin that provides a flow service is | |
| installed) `405 Method Not Allowed` is returned. | |
| [[reviewer-endpoints]] | |
| == Reviewer Endpoints | |
| [[list-reviewers]] | |
| === List Reviewers | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/reviewers/' | |
| -- | |
| Lists the reviewers of a change. | |
| As result a list of link:#reviewer-info[ReviewerInfo] entries is returned. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/ HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| [ | |
| { | |
| "approvals": { | |
| "Verified": "+1", | |
| "Code-Review": "+2" | |
| }, | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com" | |
| }, | |
| { | |
| "approvals": { | |
| "Verified": " 0", | |
| "Code-Review": "-1" | |
| }, | |
| "_account_id": 1000097, | |
| "name": "Jane Roe", | |
| "email": "jane.roe@example.com" | |
| } | |
| ] | |
| ---- | |
| [[suggest-reviewers]] | |
| === Suggest Reviewers | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/suggest_reviewers?q=J&n=5' | |
| -- | |
| Suggest the reviewers for a given query `q` and result limit `n`. If result | |
| limit is not passed, then the default 10 is used. | |
| This REST endpoint only suggests accounts that | |
| * are active | |
| * can see the change | |
| * are visible to the calling user: | |
| + | |
| Whether an account is visible to the calling user depends on the | |
| link:config-gerrit.html#accounts.visibility[accounts.visibility] setting of the | |
| server. Which account visibility is configured can be checked by opening | |
| `https://<HOST>/config/server/info?pp=1` in a browser (see field `accounts` > | |
| link:rest-api-config.html#accounts-config-info[visibility] in the returned | |
| JSON). | |
| * are not already reviewer on the change | |
| * don't own the change | |
| * are not service users (unless | |
| link:config.html#suggest.skipServiceUsers[skipServiceUsers] is set to `false`) | |
| Groups can be excluded from the results by specifying the 'exclude-groups' | |
| request parameter: | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/suggest_reviewers?q=J&n=5&exclude-groups' | |
| -- | |
| As result a list of link:#suggested-reviewer-info[SuggestedReviewerInfo] entries is returned. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/suggest_reviewers?q=J HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| [ | |
| { | |
| "account": { | |
| "_account_id": 1000097, | |
| "name": "Jane Roe", | |
| "email": "jane.roe@example.com" | |
| }, | |
| "count": 1 | |
| }, | |
| { | |
| "group": { | |
| "id": "4fd581c0657268f2bdcc26699fbf9ddb76e3a279", | |
| "name": "Joiner" | |
| }, | |
| "count": 5 | |
| } | |
| ] | |
| ---- | |
| To suggest CCs `reviewer-state=CC` can be specified as additional URL | |
| parameter. This includes existing reviewers in the result, but excludes | |
| existing CCs. | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/suggest_reviewers?q=J&reviewer-state=CC' | |
| -- | |
| [[get-reviewer]] | |
| === Get Reviewer | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/reviewers/link:rest-api-accounts.html#account-id[\{account-id\}]' | |
| -- | |
| Retrieves a reviewer of a change. | |
| As response a link:#reviewer-info[ReviewerInfo] entity is returned that | |
| describes the reviewer. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/john.doe@example.com HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "approvals": { | |
| "Verified": "+1", | |
| "Code-Review": "+2" | |
| }, | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com" | |
| } | |
| ---- | |
| [[add-reviewer]] | |
| === Add Reviewer | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/reviewers' | |
| -- | |
| Adds one user or all members of one group as reviewer to the change. | |
| NOTE: Adding multiple reviewers at once is possible via the | |
| link:#set-review[Set Review] REST endpoint. | |
| The reviewer to be added to the change must be provided in the request | |
| body as a link:#reviewer-input[ReviewerInput] entity. | |
| Users can be moved from reviewer to CC and vice versa. This means if a | |
| user is added as CC that is already a reviewer on the change, the | |
| reviewer state of that user is updated to CC. If a user that is already | |
| a CC on the change is added as reviewer, the reviewer state of that | |
| user is updated to reviewer. | |
| Adding a new reviewer also adds that reviewer to the attention set, unless | |
| the change is work in progress. | |
| Also, moving a reviewer to CC removes that user from the attention set. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "reviewer": "john.doe@example.com" | |
| } | |
| ---- | |
| As response an link:#reviewer-result[ReviewerResult] entity is | |
| returned that describes the newly added reviewers. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "input": "john.doe@example.com", | |
| "reviewers": [ | |
| { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com" | |
| "approvals": { | |
| "Verified": " 0", | |
| "Code-Review": " 0" | |
| }, | |
| } | |
| ] | |
| } | |
| ---- | |
| If a group is specified, adding the group members as reviewers is an | |
| atomic operation. This means if an error is returned, none of the | |
| members are added as reviewer. | |
| If a group with many members is added as reviewer a confirmation may be | |
| required. | |
| If a group is added as CC and members of this group are already | |
| reviewers on the change, these members stay reviewers on the change | |
| (they are not downgraded to CC). However if a group is added as | |
| reviewer, all group members become reviewer of the change, even if they | |
| have been added as CC before. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "reviewer": "MyProjectVerifiers" | |
| } | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "input": "MyProjectVerifiers", | |
| "error": "The group My Group has 15 members. Do you want to add them all as reviewers?", | |
| "confirm": true | |
| } | |
| ---- | |
| To confirm the addition of the reviewers, resend the request with the | |
| `confirmed` flag being set. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "input": "MyProjectVerifiers", | |
| "confirmed": true | |
| } | |
| ---- | |
| If link:config-project-config.html#reviewer.enableByEmail[reviewer.enableByEmail] is set | |
| for the project, reviewers and CCs are not required to have a Gerrit account. If you POST | |
| an email address of a reviewer or CC then, they will be added to the change even if they | |
| don't have a Gerrit account. | |
| If this option is disabled, the request would fail with `400 Bad Request` if the email | |
| address can't be resolved to an active Gerrit account. | |
| Note that the name is optional so both "un.registered@reviewer.com" and | |
| "John Doe <un.registered@reviewer.com>" are valid inputs. | |
| Reviewers without Gerrit accounts can only be added on changes visible to anonymous users. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "reviewer": "John Doe <un.registered@reviewer.com>" | |
| } | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "input": "John Doe <un.registered@reviewer.com>" | |
| } | |
| ---- | |
| .Notifications | |
| An email will be sent using the "newchange" template. | |
| [options="header",cols="1,1,1"] | |
| |============================= | |
| |WIP State |Default|notify=ALL | |
| |Ready for review|owner, reviewers, CCs|owner, reviewers, CCs | |
| |Work in progress|not sent|owner, reviewers, CCs | |
| |============================= | |
| [[delete-reviewer]] | |
| === Delete Reviewer | |
| -- | |
| 'DELETE /changes/link:#change-id[\{change-id\}]/reviewers/link:rest-api-accounts.html#account-id[\{account-id\}]' + | |
| 'POST /changes/link:#change-id[\{change-id\}]/reviewers/link:rest-api-accounts.html#account-id[\{account-id\}]/delete' | |
| -- | |
| Deletes a reviewer from a change. | |
| Deleting a reviewer also removes that user from the attention set. | |
| .Request | |
| ---- | |
| DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe HTTP/1.0 | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe/delete HTTP/1.0 | |
| ---- | |
| Options can be provided in the request body as a | |
| link:#delete-reviewer-input[DeleteReviewerInput] entity. | |
| Historically, this method allowed a body in the DELETE, but that behavior is | |
| link:https://www.gerritcodereview.com/releases/2.16.md[deprecated,role=external,window=_blank]. | |
| In this case, use a POST request instead: | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe/delete HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "notify": "NONE" | |
| } | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 204 No Content | |
| ---- | |
| .Notifications | |
| An email will be sent using the "deleteReviewer" template. If deleting the | |
| reviewer resulted in one or more approvals being removed, then the deleted | |
| reviewer will also receive a notification (unless notify=NONE). | |
| [options="header",cols="1,5"] | |
| |============================= | |
| |WIP State |Default Recipients | |
| |Ready for review|notify=ALL: deleted reviewer (if voted), owner, reviewers, CCs, stars, ALL_COMMENTS watchers | |
| |Work in progress|notify=NONE: deleted reviewer (if voted) | |
| |============================= | |
| [[list-votes]] | |
| === List Votes | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/reviewers/link:rest-api-accounts.html#account-id[\{account-id\}]/votes/' | |
| -- | |
| Lists the votes for a specific reviewer of the change. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe/votes/ HTTP/1.0 | |
| ---- | |
| As result a map is returned that maps the label name to the label value. | |
| The entries in the map are sorted by label name. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json;charset=UTF-8 | |
| )]}' | |
| { | |
| "Code-Review": -1, | |
| "Verified": 1 | |
| "Work-In-Progress": 1, | |
| } | |
| ---- | |
| [[delete-vote]] | |
| === Delete Vote | |
| -- | |
| 'DELETE /changes/link:#change-id[\{change-id\}]/reviewers/link:rest-api-accounts.html#account-id[\{account-id\}]/votes/link:#label-id[\{label-id\}]' + | |
| 'POST /changes/link:#change-id[\{change-id\}]/reviewers/link:rest-api-accounts.html#account-id[\{account-id\}]/votes/link:#label-id[\{label-id\}]/delete' | |
| -- | |
| Deletes a single vote from a change. Note, that even when the last vote of | |
| a reviewer is removed the reviewer itself is still listed on the change. | |
| If another user removed a user's vote, the user with the deleted vote will be | |
| added to the attention set. | |
| Note, removing votes is generally disallowed for merged changes as this could | |
| remove approvals that were necessary for the submission and it's confusing to | |
| see a merged change which doesn't have the necessary approvals to fulfill the | |
| submit requirements. | |
| See the description of the link:access-control.html#category_remove_label[ | |
| Remove Label] permission for when users are allowed to remove votes. | |
| The request returns: | |
| * '204 No Content' if the vote is deleted successfully; | |
| * '404 Not Found' when the vote to be deleted is zero or not present. | |
| * '409 Conflict' when the change is merged and hence deleting votes is not | |
| allowed | |
| .Request | |
| ---- | |
| DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe/votes/Code-Review HTTP/1.0 | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe/votes/Code-Review/delete HTTP/1.0 | |
| ---- | |
| Options can be provided in the request body as a | |
| link:#delete-vote-input[DeleteVoteInput] entity. | |
| Historically, this method allowed a body in the DELETE, but that behavior is | |
| link:https://www.gerritcodereview.com/releases/2.16.md[deprecated,role=external,window=_blank]. | |
| In this case, use a POST request instead: | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe/votes/Code-Review/delete HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "notify": "NONE" | |
| } | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 204 No Content | |
| ---- | |
| [[revision-endpoints]] | |
| == Revision Endpoints | |
| [[get-revision]] | |
| === Get Revision | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]' | |
| -- | |
| Retrieves a revision of a change. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1 HTTP/1.0 | |
| ---- | |
| As response a link:#revision-info[RevisionInfo] entity is returned that | |
| describes the revision. All fields that require a link:#query-options[change | |
| query option] to be set when the `RevisionInfo` is returned as part of | |
| `ChangeInfo` are populated. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "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": { | |
| "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 ..." | |
| }, | |
| "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-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 includes an `aiReview` entry only when the caller's `aiReview` | |
| permission is denied for the change. The entry is omitted when the permission | |
| is allowed (default) or when the permission backend errors; absence is treated | |
| by the UI as "allowed", preserving backwards compatibility with servers that | |
| do not emit the entry. | |
| Example: | |
| ---- | |
| { | |
| "aiReview": { | |
| "label": "AI Review", | |
| "title": "Run AI Review on this change", | |
| "enabled": false | |
| } | |
| } | |
| ---- | |
| The response is a flat map of possible revision REST endpoint names | |
| mapped to their link:#action-info[ActionInfo]. | |
| [[get-review]] | |
| === Get Review | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/review' | |
| -- | |
| Retrieves a review of a revision. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/review HTTP/1.0 | |
| ---- | |
| As response a link:#change-info[ChangeInfo] entity with | |
| link:#detailed-labels[detailed labels] and link:#detailed-accounts[ | |
| detailed accounts] is returned that describes the review of the | |
| revision. The revision for which the review is retrieved is contained | |
| in the `revisions` field. In addition the `current_revision` field is | |
| set if the revision for which the review is retrieved is the current | |
| revision of the change. Please note that the returned labels are always | |
| for the current patch set. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", | |
| "project": "myProject", | |
| "branch": "master", | |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", | |
| "subject": "Implementing Feature X", | |
| "status": "NEW", | |
| "created": "2013-02-01 09:59:32.126000000", | |
| "updated": "2013-02-21 11:16:36.775000000", | |
| "mergeable": true, | |
| "insertions": 34, | |
| "deletions": 45, | |
| "_number": 3965, | |
| "owner": { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com" | |
| }, | |
| "labels": { | |
| "Verified": { | |
| "all": [ | |
| { | |
| "value": 0, | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com" | |
| }, | |
| { | |
| "value": 0, | |
| "_account_id": 1000097, | |
| "name": "Jane Roe", | |
| "email": "jane.roe@example.com" | |
| } | |
| ], | |
| "values": { | |
| "-1": "Fails", | |
| " 0": "No score", | |
| "+1": "Verified" | |
| } | |
| }, | |
| "Code-Review": { | |
| "all": [ | |
| { | |
| "value": -1, | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com" | |
| }, | |
| { | |
| "value": 1, | |
| "_account_id": 1000097, | |
| "name": "Jane Roe", | |
| "email": "jane.roe@example.com" | |
| } | |
| ] | |
| "values": { | |
| "-2": "This shall not be submitted", | |
| "-1": "I would prefer this is not submitted as is", | |
| " 0": "No score", | |
| "+1": "Looks good to me, but someone else must approve", | |
| "+2": "Looks good to me, approved" | |
| } | |
| } | |
| }, | |
| "permitted_labels": { | |
| "Verified": [ | |
| "-1", | |
| " 0", | |
| "+1" | |
| ], | |
| "Code-Review": [ | |
| "-2", | |
| "-1", | |
| " 0", | |
| "+1", | |
| "+2" | |
| ] | |
| }, | |
| "removable_reviewers": [ | |
| { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com" | |
| }, | |
| { | |
| "_account_id": 1000097, | |
| "name": "Jane Roe", | |
| "email": "jane.roe@example.com" | |
| } | |
| ], | |
| "reviewers": { | |
| "REVIEWER": [ | |
| { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com" | |
| }, | |
| { | |
| "_account_id": 1000097, | |
| "name": "Jane Roe", | |
| "email": "jane.roe@example.com" | |
| } | |
| ] | |
| }, | |
| "current_revision_number": 2, | |
| "current_revision": "674ac754f91e64a0efb8087e59a176484bd534d1", | |
| "revisions": { | |
| "674ac754f91e64a0efb8087e59a176484bd534d1": { | |
| "kind": "REWORK", | |
| "_number": 2, | |
| "ref": "refs/changes/65/3965/2", | |
| "fetch": { | |
| "http": { | |
| "url": "http://gerrit/myProject", | |
| "ref": "refs/changes/65/3965/2" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| ---- | |
| [[get-related-changes]] | |
| === Get Related Changes | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/related' | |
| -- | |
| Retrieves related changes of a revision. Related changes are changes that either | |
| depend on, or are dependencies of the revision. | |
| Additional fields can be obtained by adding `o` parameters. Since these may slow | |
| down processing they are disabled by default. Currently a single parameter is | |
| supported: | |
| [[get-related-changes-submittable]] | |
| -- | |
| * `SUBMITTABLE`: Compute the `submittable` field in the returned | |
| link:#related-change-and-commit-info[RelatedChangeAndCommitInfo] entities. | |
| -- | |
| .Request | |
| ---- | |
| GET /changes/gerrit~master~I5e4fc08ce34d33c090c9e0bf320de1b17309f774/revisions/b1cb4caa6be46d12b94c25aa68aebabcbb3f53fe/related HTTP/1.0 | |
| ---- | |
| As result a link:#related-changes-info[RelatedChangesInfo] entity is returned | |
| describing the related changes. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "changes": [ | |
| { | |
| "project": "gerrit", | |
| "change_id": "Ic62ae3103fca2214904dbf2faf4c861b5f0ae9b5", | |
| "commit": { | |
| "commit": "78847477532e386f5a2185a4e8c90b2509e354e3", | |
| "parents": [ | |
| { | |
| "commit": "bb499510bbcdbc9164d96b0dbabb4aa45f59a87e" | |
| } | |
| ], | |
| "author": { | |
| "name": "David Ostrovsky", | |
| "email": "david@ostrovsky.org", | |
| "date": "2014-07-12 15:04:24.000000000", | |
| "tz": 120 | |
| }, | |
| "subject": "Remove Solr" | |
| }, | |
| "_change_number": 58478, | |
| "_revision_number": 2, | |
| "_current_revision_number": 2 | |
| "status": "NEW" | |
| }, | |
| { | |
| "project": "gerrit", | |
| "change_id": "I5e4fc08ce34d33c090c9e0bf320de1b17309f774", | |
| "commit": { | |
| "commit": "b1cb4caa6be46d12b94c25aa68aebabcbb3f53fe", | |
| "parents": [ | |
| { | |
| "commit": "d898f12a9b7a92eb37e7a80636195a1b06417aad" | |
| } | |
| ], | |
| "author": { | |
| "name": "David Pursehouse", | |
| "email": "david.pursehouse@sonymobile.com", | |
| "date": "2014-06-24 02:01:28.000000000", | |
| "tz": 540 | |
| }, | |
| "subject": "Add support for secondary index with Elasticsearch" | |
| }, | |
| "_change_number": 58081, | |
| "_revision_number": 10, | |
| "_current_revision_number": 10 | |
| "status": "NEW" | |
| } | |
| ] | |
| } | |
| ---- | |
| [[set-review]] | |
| === Set Review | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/review' | |
| -- | |
| Sets a review on a revision, optionally also publishing draft comments, setting | |
| labels, adding reviewers or CCs, and modifying the work in progress property. | |
| The review must be provided in the request body as a | |
| link:#review-input[ReviewInput] entity. | |
| If the labels are set, the user sending the request will automatically be | |
| added as a reviewer, otherwise (if they only commented) they are added to | |
| the CC list. | |
| Posting a review usually updates the link:user-attention-set.html[attention | |
| set]. | |
| A review cannot be set on a change edit. Trying to post a review for a | |
| change edit fails with `409 Conflict`. | |
| Here is an example of using this method to set labels: | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/review HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "tag": "jenkins", | |
| "message": "Some nits need to be fixed.", | |
| "labels": { | |
| "Code-Review": -1 | |
| }, | |
| "comments": { | |
| "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": [ | |
| { | |
| "line": 23, | |
| "message": "[nit] trailing whitespace" | |
| }, | |
| { | |
| "line": 49, | |
| "message": "[nit] s/conrtol/control" | |
| }, | |
| { | |
| "range": { | |
| "start_line": 50, | |
| "start_character": 0, | |
| "end_line": 55, | |
| "end_character": 20 | |
| }, | |
| "message": "Incorrect indentation" | |
| } | |
| ] | |
| } | |
| } | |
| ---- | |
| As response a link:#review-result[ReviewResult] entity is returned that | |
| describes the applied labels and any added reviewers (e.g. yourself, | |
| if you set a label but weren't previously a reviewer on this CL). | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "labels": { | |
| "Code-Review": -1 | |
| } | |
| } | |
| ---- | |
| It is also possible to add one or more reviewers or CCs | |
| to a change simultaneously with a review: | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/review HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "message": "I don't have context here. Jane and maybe John and the project leads should take a look.", | |
| "reviewers": [ | |
| { | |
| "reviewer": "jane.roe@example.com" | |
| }, | |
| { | |
| "reviewer": "john.doe@example.com", | |
| "state": "CC" | |
| } | |
| { | |
| "reviewer": "MyProjectVerifiers", | |
| } | |
| ] | |
| } | |
| ---- | |
| Each element of the `reviewers` list is an instance of | |
| link:#reviewer-input[ReviewerInput]. The corresponding result of | |
| adding each reviewer will be returned in a map of inputs to | |
| link:#reviewer-result[ReviewerResult]s. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "reviewers": { | |
| "jane.roe@example.com": { | |
| "input": "jane.roe@example.com", | |
| "reviewers": [ | |
| { | |
| "_account_id": 1000097, | |
| "name": "Jane Roe", | |
| "email": "jane.roe@example.com" | |
| "approvals": { | |
| "Verified": " 0", | |
| "Code-Review": " 0" | |
| }, | |
| }, | |
| ] | |
| }, | |
| "john.doe@example.com": { | |
| "input": "john.doe@example.com", | |
| "ccs": [ | |
| { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com" | |
| "approvals": { | |
| "Verified": " 0", | |
| "Code-Review": " 0" | |
| }, | |
| } | |
| ] | |
| }, | |
| "MyProjectVerifiers": { | |
| "input": "MyProjectVerifiers", | |
| "reviewers": [ | |
| { | |
| "_account_id": 1000098, | |
| "name": "Alice Ansel", | |
| "email": "alice.ansel@example.com" | |
| "approvals": { | |
| "Verified": " 0", | |
| "Code-Review": " 0" | |
| }, | |
| }, | |
| { | |
| "_account_id": 1000099, | |
| "name": "Bob Bollard", | |
| "email": "bob.bollard@example.com" | |
| "approvals": { | |
| "Verified": " 0", | |
| "Code-Review": " 0" | |
| }, | |
| }, | |
| ] | |
| } | |
| } | |
| } | |
| ---- | |
| If there are any errors returned for reviewers, the entire review request will | |
| be rejected with `400 Bad Request`. None of the entries will have the | |
| `reviewers` or `ccs` field set, and those which specifically failed will have | |
| the `errors` field set containing details of why they failed. | |
| .Error Response | |
| ---- | |
| HTTP/1.1 400 Bad Request | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "reviewers": { | |
| "jane.roe@example.com": { | |
| "input": "jane.roe@example.com", | |
| "error": "Account of jane.roe@example.com is inactive." | |
| }, | |
| "john.doe@example.com": { | |
| "input": "john.doe@example.com" | |
| }, | |
| "MyProjectVerifiers": { | |
| "input": "MyProjectVerifiers", | |
| "error": "The group My Group has 15 members. Do you want to add them all as reviewers?", | |
| "confirm": true | |
| } | |
| } | |
| } | |
| ---- | |
| [[set-review-notifications]] | |
| .Notifications | |
| An email will be sent using the "comment" template. | |
| If the top-level notify property is null or not set, then notification behavior | |
| depends on whether the change is WIP, whether it has started review, and whether | |
| the tag property is null. | |
| NOTE: If adding reviewers, the notify property of each ReviewerInput is *ignored*. | |
| Use the notify property of the top-level link:#review-input[ReviewInput] instead. | |
| For the purposes of this table, *everyone* means *owner, reviewers, CCs, stars, and ALL_COMMENTS | |
| watchers*. | |
| [options="header",cols="2,1,1,2,2"] | |
| |============================= | |
| |WIP State |Review Started|Tag Given|Default |notify=ALL | |
| |Ready for review|N/A |N/A |everyone|everyone | |
| |Work in progress|no |no |not sent|everyone | |
| |Work in progress|no |yes |owner |everyone | |
| |Work in progress|yes |no |everyone|everyone | |
| |Work in progress|yes |yes |owner |everyone | |
| |============================= | |
| If reviewers are added, then a second email will be sent using the "newchange" | |
| template. The notification logic for this email is the same as for | |
| link:#add-reviewer[Add Reviewer]. | |
| [options="header",cols="1,1,1"] | |
| |============================= | |
| |WIP State |Default |notify=ALL | |
| |Ready for review|owner, reviewers, CCs|owner, reviewers, CCs | |
| |Work in progress|not sent |owner, reviewers, CCs | |
| |============================= | |
| [[rebase-revision]] | |
| === Rebase Revision | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/rebase' | |
| -- | |
| Rebases a revision. | |
| Optionally, the parent revision can be changed to another patch set through the | |
| link:#rebase-input[RebaseInput] entity. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I3ea943139cb62e86071996f2480e58bf3eeb9dd2/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/rebase HTTP/1.0 | |
| Content-Type: application/json;charset=UTF-8 | |
| { | |
| "base" : "1234", | |
| } | |
| ---- | |
| As response a link:#change-info[ChangeInfo] entity is returned that | |
| describes the rebased change. Information about the current patch set | |
| is included. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "id": "myProject~master~I3ea943139cb62e86071996f2480e58bf3eeb9dd2", | |
| "project": "myProject", | |
| "branch": "master", | |
| "change_id": "I3ea943139cb62e86071996f2480e58bf3eeb9dd2", | |
| "subject": "Implement Feature X", | |
| "status": "NEW", | |
| "created": "2013-02-01 09:59:32.126000000", | |
| "updated": "2013-02-21 11:16:36.775000000", | |
| "mergeable": false, | |
| "insertions": 21, | |
| "deletions": 21, | |
| "_number": 4799, | |
| "owner": { | |
| "name": "John Doe" | |
| }, | |
| "current_revision_number": 2, | |
| "current_revision": "27cc4558b5a3d3387dd11ee2df7a117e7e581822", | |
| "revisions": { | |
| "27cc4558b5a3d3387dd11ee2df7a117e7e581822": { | |
| "kind": "REWORK", | |
| "_number": 2, | |
| "ref": "refs/changes/99/4799/2", | |
| "fetch": { | |
| "http": { | |
| "url": "http://gerrit:8080/myProject", | |
| "ref": "refs/changes/99/4799/2" | |
| } | |
| }, | |
| "commit": { | |
| "parents": [ | |
| { | |
| "commit": "b4003890dadd406d80222bf1ad8aca09a4876b70", | |
| "subject": "Implement Feature A" | |
| } | |
| ], | |
| "author": { | |
| "name": "John Doe", | |
| "email": "john.doe@example.com", | |
| "date": "2013-05-07 15:21:27.000000000", | |
| "tz": 120 | |
| }, | |
| "committer": { | |
| "name": "Gerrit Code Review", | |
| "email": "gerrit-server@example.com", | |
| "date": "2013-05-07 15:35:43.000000000", | |
| "tz": 120 | |
| }, | |
| "subject": "Implement Feature X", | |
| "message": "Implement Feature X\n\nAdded feature X." | |
| } | |
| } | |
| } | |
| ---- | |
| If the revision cannot be rebased, e.g. due to conflicts, the response is | |
| "`409 Conflict`" and the error message is contained in the response | |
| body. | |
| .Response | |
| ---- | |
| HTTP/1.1 409 Conflict | |
| Content-Disposition: attachment | |
| Content-Type: text/plain; charset=UTF-8 | |
| The change could not be rebased due to a path conflict during merge. | |
| ---- | |
| [[submit-revision]] | |
| === Submit Revision | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/submit' | |
| -- | |
| Submits a revision. | |
| Submitting a change also removes all users from the link:user-attention-set.html[attention set]. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/submit HTTP/1.0 | |
| ---- | |
| As response a link:#change-info[ChangeInfo] entity is returned that | |
| describes the submitted/merged change. | |
| Submission may submit multiple changes, but we still only return one ChangeInfo | |
| object. To query for all submitted changes, please use the submission_id that is | |
| part of the response. | |
| Changes that will also be submitted: | |
| 1. All changes of the same topic if | |
| link:config-gerrit.html#change.submitWholeTopic[`change.submitWholeTopic`] | |
| configuration is set to true. | |
| 2. All dependent changes. | |
| 3. The closure of the above (e.g if a dependent change has a topic, all changes | |
| of *that* topic will also be submitted). | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", | |
| "project": "myProject", | |
| "branch": "master", | |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", | |
| "subject": "Implementing Feature X", | |
| "status": "MERGED", | |
| "created": "2013-02-01 09:59:32.126000000", | |
| "updated": "2013-02-21 11:16:36.775000000", | |
| "submitted": "2013-02-21 11:16:36.615000000", | |
| "_number": 3965, | |
| "owner": { | |
| "name": "John Doe" | |
| }, | |
| "current_revision_number": 2 | |
| } | |
| ---- | |
| If the revision cannot be submitted, e.g. because the submit rule | |
| doesn't allow submitting the revision or the revision is not the | |
| current revision, the response is "`409 Conflict`" and the error | |
| message is contained in the response body. | |
| .Response | |
| ---- | |
| HTTP/1.1 409 Conflict | |
| Content-Type: text/plain; charset=UTF-8 | |
| "revision 674ac754f91e64a0efb8087e59a176484bd534d1 is not current revision" | |
| ---- | |
| [[get-patch]] | |
| === Get Patch | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/patch' | |
| -- | |
| Gets the formatted patch for one revision. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/patch HTTP/1.0 | |
| ---- | |
| The formatted patch is returned as text encoded inside base64: | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: text/plain; charset=ISO-8859-1 | |
| X-FYI-Content-Encoding: base64 | |
| X-FYI-Content-Type: application/mbox | |
| RnJvbSA3ZGFkY2MxNTNmZGVhMTdhYTg0ZmYzMmE2ZTI0NWRiYjY... | |
| ---- | |
| Adding query parameter `zip` (for example `/changes/.../patch?zip`) | |
| returns the patch as a single file inside of a ZIP archive. Clients | |
| can expand the ZIP to obtain the plain text patch, avoiding the | |
| need for a base64 decoding step. This option implies `download`. | |
| Adding query parameter `raw` (for example `/changes/.../patch?raw`) will return | |
| the patch as a plain-text patch file. | |
| 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. | |
| If the `parent` parameter is set, the value is used as the 1-based index of the | |
| parent's position in the commit object and the returned content is a diff | |
| compared to that parent. | |
| Adding query parameter `context` (e.g. `/changes/.../patch?context=10`) | |
| sets the number of context lines that are displayed in the patch. If the | |
| context is not set, the default of 3 is used. It can also be abbreviated as | |
| `U`. | |
| [[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 change has already been merged, the endpoint still returns | |
| `200 OK`. In that case the change is considered mergeable because its | |
| revision is already integrated into the destination branch. The response | |
| also sets `commit_merged` and `content_merged`, so clients can tell this | |
| case apart from an open change that could still be submitted. | |
| .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, | |
| commit_merged: true, | |
| content_merged: true | |
| } | |
| ---- | |
| If the change is abandoned, then by definition the change is not mergeable. | |
| The endpoint returns `200 OK` with: | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| submit_type: "MERGE_IF_NECESSARY", | |
| strategy: "recursive", | |
| mergeable: false, | |
| commit_merged: false, | |
| content_merged: false | |
| } | |
| ---- | |
| If the `other-branches` parameter is specified, the mergeability will also be | |
| checked for all other branches which are listed in the | |
| link:config-project-config.html#branchOrder-section[branchOrder] section in the | |
| project.config file. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/mergeable?other-branches HTTP/1.0 | |
| ---- | |
| The response will then contain a list of all other branches where this changes | |
| could merge cleanly. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| submit_type: "MERGE_IF_NECESSARY", | |
| mergeable: true, | |
| mergeable_into: [ | |
| "refs/heads/stable-2.7", | |
| "refs/heads/stable-2.8", | |
| ] | |
| } | |
| ---- | |
| [[get-submit-type]] | |
| === Get Submit Type | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/submit_type' | |
| -- | |
| Gets the method the server will use to submit (merge) the change. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/submit_type HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| "MERGE_IF_NECESSARY" | |
| ---- | |
| [[test-submit-type]] | |
| === Test Submit Type | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/test.submit_type' | |
| -- | |
| Tests the submit_type Prolog rule in the project, or the one given. | |
| Request body may be either the Prolog code as `text/plain` or a | |
| link:#rule-input[RuleInput] object. The query parameter `filters` | |
| may be set to `SKIP` to bypass parent project filters while testing | |
| a project-specific rule. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/test.submit_type HTTP/1.0 | |
| Content-Type: text/plain; charset=UTF-8 | |
| submit_type(cherry_pick). | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| "CHERRY_PICK" | |
| ---- | |
| [[test-submit-rule]] | |
| === Test Submit Rule | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/test.submit_rule' | |
| -- | |
| Tests the submit_rule Prolog rule in the project, or the one given. | |
| Request body may be either the Prolog code as `text/plain` or a | |
| link:#rule-input[RuleInput] object. The query parameter `filters` | |
| may be set to `SKIP` to bypass parent project filters while testing | |
| a project-specific rule. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/test.submit_rule?filters=SKIP HTTP/1.0 | |
| Content-Type: text/plain; charset=UTF-8 | |
| submit_rule(submit(R)) :- | |
| R = label('Any-Label-Name', reject(_)). | |
| ---- | |
| The response is a link:#submit-record[SubmitRecord] describing the | |
| permutations that satisfy the tested submit rule. | |
| If the submit rule was a no-op, the response is "`204 No Content`". | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "status": "NOT_READY", | |
| "reject": { | |
| "Any-Label-Name": {} | |
| } | |
| } | |
| ---- | |
| When testing with the `curl` command line client the | |
| `--data-binary @rules.pl` flag should be used to ensure | |
| all LFs are included in the Prolog code: | |
| ---- | |
| curl -X POST \ | |
| -H 'Content-Type: text/plain; charset=UTF-8' \ | |
| --data-binary @rules.pl \ | |
| http://.../test.submit_rule | |
| ---- | |
| [[list-drafts]] | |
| === List Revision Drafts | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/drafts/' | |
| -- | |
| Lists the draft comments of a revision that belong to the calling | |
| user. | |
| Returns a map of file paths to lists of link:#comment-info[CommentInfo] | |
| entries. The entries in the map are sorted by file path. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/drafts/ HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": [ | |
| { | |
| "id": "TvcXrmjM", | |
| "line": 23, | |
| "message": "[nit] trailing whitespace", | |
| "updated": "2013-02-26 15:40:43.986000000" | |
| }, | |
| { | |
| "id": "TveXwFiA", | |
| "line": 49, | |
| "in_reply_to": "TfYX-Iuo", | |
| "message": "Done", | |
| "updated": "2013-02-26 15:40:45.328000000" | |
| } | |
| ] | |
| } | |
| ---- | |
| [[create-draft]] | |
| === Create Draft | |
| -- | |
| 'PUT /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/drafts' | |
| -- | |
| Creates a draft comment on a revision. | |
| The new draft comment must be provided in the request body inside a | |
| link:#comment-input[CommentInput] entity. | |
| .Request | |
| ---- | |
| PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/drafts HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", | |
| "line": 23, | |
| "message": "[nit] trailing whitespace" | |
| } | |
| ---- | |
| As response a link:#comment-info[CommentInfo] entity is returned that | |
| describes the draft comment. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "id": "TvcXrmjM", | |
| "path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", | |
| "line": 23, | |
| "message": "[nit] trailing whitespace", | |
| "updated": "2013-02-26 15:40:43.986000000" | |
| } | |
| ---- | |
| [[get-draft]] | |
| === Get Draft | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/drafts/link:#draft-id[\{draft-id\}]' | |
| -- | |
| Retrieves a draft comment of a revision that belongs to the calling | |
| user. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/drafts/TvcXrmjM HTTP/1.0 | |
| ---- | |
| As response a link:#comment-info[CommentInfo] entity is returned that | |
| describes the draft comment. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "id": "TvcXrmjM", | |
| "path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", | |
| "line": 23, | |
| "message": "[nit] trailing whitespace", | |
| "updated": "2013-02-26 15:40:43.986000000" | |
| } | |
| ---- | |
| [[update-draft]] | |
| === Update Draft | |
| -- | |
| 'PUT /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/drafts/link:#draft-id[\{draft-id\}]' | |
| -- | |
| Updates a draft comment on a revision. | |
| The new draft comment must be provided in the request body inside a | |
| link:#comment-input[CommentInput] entity. | |
| .Request | |
| ---- | |
| PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/drafts/TvcXrmjM HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", | |
| "line": 23, | |
| "message": "[nit] trailing whitespace" | |
| } | |
| ---- | |
| As response a link:#comment-info[CommentInfo] entity is returned that | |
| describes the draft comment. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "id": "TvcXrmjM", | |
| "path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", | |
| "line": 23, | |
| "message": "[nit] trailing whitespace", | |
| "updated": "2013-02-26 15:40:43.986000000" | |
| } | |
| ---- | |
| [[delete-draft]] | |
| === Delete Draft | |
| -- | |
| 'DELETE /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/drafts/link:#draft-id[\{draft-id\}]' | |
| -- | |
| Deletes a draft comment from a revision. | |
| .Request | |
| ---- | |
| DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/drafts/TvcXrmjM HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 204 No Content | |
| ---- | |
| [[list-comments]] | |
| === List Revision Comments | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/comments/' | |
| -- | |
| Lists the published comments of a revision. | |
| As result a map is returned that maps the file path to a list of | |
| link:#comment-info[CommentInfo] entries. The entries in the map are | |
| sorted by file path and only include file (or inline) comments. Use | |
| the link:#get-change-detail[Get Change Detail] endpoint to retrieve | |
| the general change message (or comment). | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/comments/ HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": [ | |
| { | |
| "id": "TvcXrmjM", | |
| "line": 23, | |
| "message": "[nit] trailing whitespace", | |
| "updated": "2013-02-26 15:40:43.986000000", | |
| "author": { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com" | |
| } | |
| }, | |
| { | |
| "id": "TveXwFiA", | |
| "line": 49, | |
| "in_reply_to": "TfYX-Iuo", | |
| "message": "Done", | |
| "updated": "2013-02-26 15:40:45.328000000", | |
| "author": { | |
| "_account_id": 1000097, | |
| "name": "Jane Roe", | |
| "email": "jane.roe@example.com" | |
| } | |
| } | |
| ] | |
| } | |
| ---- | |
| [[get-comment]] | |
| === Get Comment | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/comments/link:#comment-id[\{comment-id\}]' | |
| -- | |
| Retrieves a published comment of a revision. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/comments/TvcXrmjM HTTP/1.0 | |
| ---- | |
| As response a link:#comment-info[CommentInfo] entity is returned that | |
| describes the published comment. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "id": "TvcXrmjM", | |
| "path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", | |
| "line": 23, | |
| "message": "[nit] trailing whitespace", | |
| "updated": "2013-02-26 15:40:43.986000000", | |
| "author": { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com" | |
| } | |
| } | |
| ---- | |
| [[delete-comment]] | |
| === Delete Comment | |
| -- | |
| 'DELETE /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/comments/link:#comment-id[\{comment-id\}]' + | |
| 'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/comments/link:#comment-id[\{comment-id\}]/delete' | |
| -- | |
| Deletes a published comment of a revision. Instead of deleting the | |
| whole comment, this endpoint just replaces the comment's message | |
| with a new message, which contains the name of the user who deletes | |
| the comment and the reason why it's deleted. | |
| This endpoint also marks the comment as resolved since deleted comments are not | |
| actionable. | |
| Note that only users with the | |
| link:access-control.html#capability_administrateServer[Administrate Server] | |
| global capability are permitted to delete a comment. | |
| Deletion reason can be provided in the request body as a | |
| link:#delete-comment-input[DeleteCommentInput] entity. | |
| Historically, this method allowed a body in the DELETE, but that behavior is | |
| link:https://www.gerritcodereview.com/releases/2.16.md[deprecated,role=external,window=_blank]. | |
| In this case, use a POST request instead: | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/comments/TvcXrmjM/delete HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "reason": "contains confidential information" | |
| } | |
| ---- | |
| As response a link:#comment-info[CommentInfo] entity is returned that | |
| describes the updated comment. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "id": "TvcXrmjM", | |
| "path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", | |
| "line": 23, | |
| "message": "Comment removed by: Administrator; Reason: contains confidential information", | |
| "updated": "2013-02-26 15:40:43.986000000", | |
| "author": { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com" | |
| } | |
| } | |
| ---- | |
| [[list-ported-comments]] | |
| === List Ported Comments | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/ported_comments' | |
| -- | |
| Ports comments of other revisions to the requested revision. | |
| Only comments added on earlier patchsets are ported. That set of comments is filtered even further | |
| due to some additional rules. Callers of this endpoint shouldn't rely on the exact logic of which | |
| comments are ported as that logic might change in the future. Instead, callers must be able to | |
| handle any smaller/larger set of comments returned by this endpoint. | |
| Typically, a comment thread is returned fully or excluded fully. However, draft comments | |
| are ignored and not returned via this endpoint. | |
| The returned comments are organized in a map of file path to link:#comment-info[CommentInfo] entries | |
| in the same fashion as for the link:#list-comments[List Revision Comments] endpoint. | |
| The map is filled with the original comment attributes except for these attributes: `path`, `line`, | |
| and `range` point to the computed position in the target revision. If the exactly correct position | |
| can't be determined, those fields will be filled with the next best position. That can also mean | |
| not filling the `line` or `range` attribute anymore and thus converting the comment to a file | |
| comment (or even moving the comment to a different file or the patchset level). Callers of this | |
| endpoint must be able to deal with this and not rely on the original comment position. | |
| It's possible that this endpoint returns different link:#comment-info[CommentInfo] entries with | |
| the same comment UUID. This is not a bug but a feature. If a comment appears on a file which Gerrit | |
| recognizes as copied between patchsets, the ported version of this comment consists of two ported | |
| instances having the same UUID but different `file`/`line`/`range` positions. Callers must be able | |
| to handle this situation. | |
| Repeated calls of this endpoint might produce different results. Internal errors during the | |
| position computation are mapped to fallback locations for affected comments. Those errors might | |
| have vanished on later calls, upon which this endpoint returns the actually mapped position. In | |
| addition, comments can be deleted and draft comments can be published, upon which the set of ported | |
| comments may change. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/4/ported_comments/ HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": [ | |
| { | |
| "id": "TvcXrmjM", | |
| "patch_set": 2, | |
| "line": 23, | |
| "message": "[nit] trailing whitespace", | |
| "updated": "2013-02-26 15:40:43.986000000", | |
| "author": { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com" | |
| }, | |
| "unresolved": true | |
| }, | |
| { | |
| "id": "TveXwFiA", | |
| "patch_set": 2, | |
| "line": 23, | |
| "in_reply_to": "TvcXrmjM", | |
| "message": "Done", | |
| "updated": "2013-02-26 15:40:45.328000000", | |
| "author": { | |
| "_account_id": 1000097, | |
| "name": "Jane Roe", | |
| "email": "jane.roe@example.com" | |
| }, | |
| "unresolved": true | |
| } | |
| ] | |
| } | |
| ---- | |
| [[list-ported-drafts]] | |
| === List Ported Drafts | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/ported_drafts' | |
| -- | |
| Ports draft comments of other revisions to the requested revision. | |
| This endpoint behaves similarly to the link:#list-ported-comments[List Ported Comments] endpoint. | |
| With this endpoint, only draft comments of the calling user are ported, though. If a draft comment | |
| is a reply to a published comment, only the ported draft comment is returned. | |
| Depending on the filtering rules, it's possible that this endpoint returns a draft comment which is | |
| a reply to a comment thread which is not returned by the | |
| link:#list-ported-comments[List Ported Comments] endpoint. That's intended behavior. Callers must be | |
| able to handle this situation. | |
| Different than the link:#list-ported-comments[List Ported Comments] endpoint, the `author` of the | |
| returned comments is not filled for this endpoint as only comments of the calling user are returned. | |
| This endpoint requires authentication. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/ported_drafts/ HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": [ | |
| { | |
| "id": "TveXwFiA", | |
| "patch_set": 2, | |
| "line": 23, | |
| "in_reply_to": "TvcXrmjM", | |
| "message": "Done", | |
| "updated": "2013-02-26 15:40:45.328000000", | |
| "unresolved": true | |
| } | |
| ] | |
| } | |
| ---- | |
| [[apply-stored-fix]] | |
| === Apply Stored Fix | |
| -- | |
| 'POST /changes/<<change-id,\{change-id\}>>/revisions/<<revision-id,\{revision-id\}>>/fixes/<<fix-id,\{fix-id\}>>/apply' | |
| -- | |
| Applies a suggested fix by creating a change edit which includes the | |
| modifications indicated by the fix suggestion. If a change edit already exists, | |
| it will be updated accordingly. A fix can only be applied if no change edit | |
| exists and the fix refers to the current patch set, or the fix refers to the | |
| patch set on which the change edit is based. | |
| If one of the secondary emails associated with the user performing the operation was used as the | |
| committer email in the current patch set, the same email will be used as the committer email in the | |
| new change edit commit; otherwise, the user's preferred email will be used. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/fixes/8f605a55_f6aa4ecc/apply HTTP/1.0 | |
| ---- | |
| If the fix was successfully applied, an <<edit-info,EditInfo>> describing the | |
| resulting change edit is returned. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "commit": { | |
| "parents": [ | |
| { | |
| "commit": "1eee2c9d8f352483781e772f35dc586a69ff5646", | |
| } | |
| ], | |
| "author": { | |
| "name": "John Doe", | |
| "email": "john.doe@example.com", | |
| "date": "2013-05-07 15:21:27.000000000", | |
| "tz": 120 | |
| }, | |
| "committer": { | |
| "name": "Jane Doe", | |
| "email": "jane.doe@example.com", | |
| "date": "2013-05-07 15:35:43.000000000", | |
| "tz": 120 | |
| }, | |
| "subject": "Implement feature X", | |
| "message": "Implement feature X\n\nWith this feature ..." | |
| }, | |
| "base_patch_set_number": 1, | |
| "base_revision": "674ac754f91e64a0efb8087e59a176484bd534d1" | |
| "ref": "refs/users/01/1000001/edit-42622/1" | |
| } | |
| ---- | |
| If the application failed e.g. due to conflicts with an existing change edit, | |
| the response "`409 Conflict`" including an error message in the response body | |
| is returned. | |
| .Response | |
| ---- | |
| HTTP/1.1 409 Conflict | |
| Content-Disposition: attachment | |
| Content-Type: text/plain; charset=UTF-8 | |
| Rebasing change edit onto another patchset results in merge conflicts. Download the edit patchset and rebase manually to preserve changes. | |
| ---- | |
| [[apply-provided-fix]] | |
| ==== Apply Provided Fix | |
| -- | |
| 'POST /changes/<<change-id,\{change-id\}>>/revisions/<<revision-id,\{revision-id\}>>/fix:apply' | |
| -- | |
| Applies a list of <<fix-replacement-info,FixReplacementInfo>> loaded from the | |
| <<apply-provided-fix-input,ApplyProvidedFixInput>> entity. The fixes are passed as part of the request body. The | |
| application of the fixes creates a new change edit. `Apply Provided Fix` can only be applied on the current | |
| patchset. To apply a fix that was suggested to a non-current patchset, set `originalPatchsetForFix` to a patchset | |
| number where the fix was suggested. When `originalPatchsetForFix` is set, gerrit generates a patch (using | |
| `fix-replacement-info` and `originalPatchsetForFix`) and then tries to apply it to the current patchset. | |
| If it is not possible to apply a patch, an error is returned (see below for the list of errors). | |
| If the provided fix modifies the commit message and the message was changed between `originalPatchsetForFix` | |
| and the current patchset, the request is rejected.. | |
| If one of the secondary emails associated with the user performing the operation was used as the | |
| committer email in the current patch set, the same email will be used as the committer email in the | |
| new change edit commit; otherwise, the user's preferred email will be used. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/fix:apply HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "fix_replacement_infos": [ | |
| { | |
| "path": "abcd.txt", | |
| "range": { | |
| "start_line": 2, | |
| "start_character": 2, | |
| "end_line": 2, | |
| "end_character": 5 | |
| }, | |
| "replacement": "abcdefg" | |
| } | |
| ] | |
| } | |
| ---- | |
| If the `ApplyProvidedFixInput` was successfully applied, an link:#edit-info[EditInfo] describing the | |
| resulting change edit is returned. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "commit": { | |
| "commit": "bd43e48c33d2b1a03485040eba38cefc505f7997", | |
| "parents": [ | |
| { | |
| "commit": "9825962f8ab6da89afebad3f5034db05fb4b7560" | |
| } | |
| ], | |
| "author": { | |
| "name": "John Doe", | |
| "email": "john.doe@example.com", | |
| "date": "2022-05-07 15:21:27.000000000", | |
| "tz": 120 | |
| }, | |
| "committer": { | |
| "name": "Jane Doe", | |
| "email": "jane.doe@example.com", | |
| "date": "2022-05-07 15:35:43.000000000", | |
| "tz": 120 | |
| }, | |
| "subject": "Implement feature X", | |
| "message": "Implement feature X\n\nWith this feature ..." | |
| }, | |
| "base_patch_set_number": 1, | |
| "base_revision": "86d87686ce0ef7f7c536bfc7e9a66f5a6fa5d658", | |
| "ref": "refs/users/01/1000001/edit-1/1" | |
| } | |
| ---- | |
| If the application failed due to presence of an existing change edit, | |
| the response "`400 Bad Request`" including an error message in the response body | |
| is returned. | |
| .Response | |
| ---- | |
| HTTP/1.1 400 Bad Request | |
| Content-Disposition: attachment | |
| Content-Type: text/plain; charset=UTF-8 | |
| Change edit already exists. A new change edit can't be created | |
| ---- | |
| If the application failed due to application on a previous patch set, the response | |
| "`409 Conflict`" including an error message in the response body is returned. | |
| .Response | |
| ---- | |
| HTTP/1.1 409 Conflict | |
| Content-Disposition: attachment | |
| Content-Type: text/plain; charset=UTF-8 | |
| A change edit may only be created for the current patch set 1,2 (and not for 1,1) | |
| ---- | |
| [[list-files]] | |
| === List Files | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/files/' | |
| -- | |
| Lists the files that were modified, added or deleted in a revision. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/ HTTP/1.0 | |
| ---- | |
| As result a map is returned that maps the link:#file-id[file path] to a | |
| link:#file-info[FileInfo] entry. The entries in the map are | |
| sorted by file path. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "/COMMIT_MSG": { | |
| "status": "A", | |
| "lines_inserted": 7, | |
| "size_delta": 551, | |
| "size": 551 | |
| }, | |
| "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": { | |
| "lines_inserted": 5, | |
| "lines_deleted": 3, | |
| "size_delta": 98, | |
| "size": 23348 | |
| } | |
| } | |
| ---- | |
| The request parameter `reviewed` changes the response to return a list | |
| of the paths the caller has marked as reviewed. Clients that also | |
| need the FileInfo should make two requests. | |
| The request parameter `q` changes the response to return a list | |
| of all files (modified or unmodified) that contain that substring | |
| in the path name. This is useful to implement suggestion services | |
| finding a file by partial name. Clients that also need the FileInfo | |
| should make two requests. | |
| For merge commits only, the integer-valued request parameter `parent` | |
| changes the response to return a map of the files which are different | |
| in this commit compared to the given parent commit. The value is the | |
| 1-based index of the parent's position in the commit object, | |
| with the first parent always belonging to the target branch. If not | |
| specified, the response contains a map of the files different in the | |
| auto merge result. | |
| The request parameter `base` changes the response to return a map of the | |
| files which are different in this commit compared to the given revision. The | |
| revision must correspond to a patch set in the change. | |
| The `reviewed`, `q`, `parent`, and `base` options are mutually exclusive. | |
| That is, only one of them may be used at a time. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/?reviewed HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| [ | |
| "/COMMIT_MSG", | |
| "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", | |
| ] | |
| ---- | |
| [[get-content]] | |
| === Get Content | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/files/link:#file-id[\{file-id\}]/content' | |
| -- | |
| Gets the content of a file from a certain revision. | |
| The optional, integer-valued `parent` parameter can be specified to request | |
| the named file from a parent commit of the specified revision. The value is | |
| the 1-based index of the parent's position in the commit object. If the | |
| parameter is omitted or the value is non-positive, the patch set is referenced. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/content HTTP/1.0 | |
| ---- | |
| The content is returned as base64 encoded string. The HTTP response | |
| Content-Type is always `text/plain`, reflecting the base64 wrapping. | |
| A Gerrit-specific `X-FYI-Content-Type` header is returned describing | |
| the server detected content type of the file. | |
| If only the content type is required, callers should use HEAD to | |
| avoid downloading the encoded file contents. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: text/plain; charset=ISO-8859-1 | |
| X-FYI-Content-Encoding: base64 | |
| X-FYI-Content-Type: text/xml | |
| Ly8gQ29weXJpZ2h0IChDKSAyMDEwIFRoZSBBbmRyb2lkIE9wZW4gU291cmNlIFByb2plY... | |
| ---- | |
| Alternatively, if the only value of the Accept request header is | |
| `application/json` the content is returned as JSON string and | |
| `X-FYI-Content-Encoding` is set to `json`. | |
| [[get-safe-content]] | |
| === Download Content | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/files/link:#file-id[\{file-id\}]/download' | |
| -- | |
| Downloads the content of a file from a certain revision, in a safe format | |
| that poses no risk for inadvertent execution of untrusted code. | |
| If the content type is defined as safe, the binary file content is returned | |
| verbatim. If the content type is not safe, the file is stored inside a ZIP | |
| file, containing a single entry with a random, unpredictable name having the | |
| same base and suffix as the true filename. The ZIP file is returned in | |
| verbatim binary form. | |
| See link:config-gerrit.html#mimetype.name.safe[Gerrit config documentation] | |
| for information about safe file type configuration. | |
| The HTTP resource Content-Type is dependent on the file type: the | |
| applicable type for safe files, or "application/zip" for unsafe files. | |
| The optional, integer-valued `parent` parameter can be specified to request | |
| the named file from a parent commit of the specified revision. The value is | |
| the 1-based index of the parent's position in the commit object. If the | |
| parameter is omitted or the value non-positive, the patch set is referenced. | |
| Filenames are decorated with a suffix of `_new` for the current patch, | |
| `_old` for the only parent, or `_oldN` for the Nth parent of many. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/website%2Freleases%2Flogo.png/download HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment; filename="logo.png" | |
| Content-Type: image/png | |
| `[binary data for logo.png]` | |
| ---- | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/download?suffix=new HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: Content-Disposition:attachment; filename="RefControl_new-931cdb73ae9d97eb500a3533455b055d90b99944.java.zip" | |
| Content-Type:application/zip | |
| `[binary ZIP archive containing a single file, "RefControl_new-cb218df1337df48a0e7ab30a49a8067ac7321881.java"]` | |
| ---- | |
| [[get-diff]] | |
| === Get Diff | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/files/link:#file-id[\{file-id\}]/diff' | |
| -- | |
| Gets the diff of a file from a certain revision. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/diff HTTP/1.0 | |
| ---- | |
| As response a link:#diff-info[DiffInfo] entity is returned that describes the diff. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )] | |
| { | |
| "meta_a": { | |
| "name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", | |
| "content_type": "text/x-java-source", | |
| "lines": 372 | |
| }, | |
| "meta_b": { | |
| "name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", | |
| "content_type": "text/x-java-source", | |
| "lines": 578 | |
| }, | |
| "change_type": "MODIFIED", | |
| "diff_header": [ | |
| "diff --git a/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java b/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", | |
| "index 59b7670..9faf81c 100644", | |
| "--- a/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", | |
| "+++ b/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java" | |
| ], | |
| "content": [ | |
| { | |
| "ab": [ | |
| "// Copyright (C) 2010 The Android Open Source Project", | |
| "//", | |
| "// Licensed under the Apache License, Version 2.0 (the \"License\");", | |
| "// you may not use this file except in compliance with the License.", | |
| "// You may obtain a copy of the License at", | |
| "//", | |
| "// http://www.apache.org/licenses/LICENSE-2.0", | |
| "//", | |
| "// Unless required by applicable law or agreed to in writing, software", | |
| "// distributed under the License is distributed on an \"AS IS\" BASIS,", | |
| "// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.", | |
| "// See the License for the specific language governing permissions and", | |
| "// limitations under the License." | |
| ] | |
| }, | |
| { | |
| "b": [ | |
| "//", | |
| "// Add some more lines in the header." | |
| ] | |
| }, | |
| { | |
| "ab": [ | |
| "", | |
| "package com.google.gerrit.server.project;", | |
| "", | |
| "import com.google.common.collect.Maps;", | |
| ... | |
| ] | |
| } | |
| ... | |
| ] | |
| } | |
| ---- | |
| If the `intraline` parameter is specified, intraline differences are included in the diff. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/b6b9c10649b9041884046119ab794374470a1b45/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/diff?intraline HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )] | |
| { | |
| "meta_a": { | |
| "name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", | |
| "content_type": "text/x-java-source", | |
| "lines": 372 | |
| }, | |
| "meta_b": { | |
| "name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", | |
| "content_type": "text/x-java-source", | |
| "lines": 578 | |
| }, | |
| "change_type": "MODIFIED", | |
| "diff_header": [ | |
| "diff --git a/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java b/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", | |
| "index 59b7670..9faf81c 100644", | |
| "--- a/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", | |
| "+++ b/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java" | |
| ], | |
| "content": [ | |
| ... | |
| { | |
| "a": [ | |
| "/** Manages access control for Git references (aka branches, tags). */" | |
| ], | |
| "b": [ | |
| "/** Manages access control for the Git references (aka branches, tags). */" | |
| ], | |
| "edit_a": [], | |
| "edit_b": [ | |
| [ | |
| 31, | |
| 4 | |
| ] | |
| ] | |
| } | |
| ] | |
| } | |
| ---- | |
| The `base` parameter can be specified to control the base patch set from which the diff should | |
| be generated. | |
| The integer-valued request parameter `parent` can be specified to control the | |
| parent commit number against which the diff should be generated. This is useful | |
| for supporting review of merge commits. The value is the 1-based index of the | |
| parent's position in the commit object. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/b6b9c10649b9041884046119ab794374470a1b45/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/diff?base=2 HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )] | |
| { | |
| "meta_a": { | |
| "name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", | |
| "content_type": "text/x-java-source", | |
| "lines": 578 | |
| }, | |
| "meta_b": { | |
| "name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", | |
| "content_type": "text/x-java-source", | |
| "lines": 578 | |
| }, | |
| "change_type": "MODIFIED", | |
| "content": [ | |
| { | |
| "skip": 578 | |
| } | |
| ] | |
| } | |
| ---- | |
| The `whitespace` parameter can be specified to control how whitespace | |
| differences are reported in the result. Valid values are `IGNORE_NONE`, | |
| `IGNORE_TRAILING`, `IGNORE_LEADING_AND_TRAILING` or `IGNORE_ALL`. | |
| [[preview-stored-fix]] | |
| === Preview Stored Fix | |
| -- | |
| 'GET /changes/<<change-id,\{change-id\}>>/revisions/<<revision-id,\{revision-id\}>>/fixes/<<fix-id,\{fix-id\}>>/preview' | |
| -- | |
| Gets the diffs of all files for a certain <<fix-id,\{fix-id\}>>. | |
| As response, a map of link:#diff-info[DiffInfo] entities is returned that describes the diffs. | |
| Each link:#diff-info[DiffInfo] is the differences between the patch set indicated by revision-id and a virtual patch set with the applied fix. | |
| [[preview-provided-fix]] | |
| === Preview Provided fix | |
| -- | |
| 'POST /changes/<<change-id,\{change-id\}>>/revisions/<<revision-id,\{revision-id\}>>/fix:preview' | |
| -- | |
| Gets the diffs of all files for a list of <<fix-replacement-info,FixReplacementInfo>> loaded from | |
| the <<apply-provided-fix-input,ApplyProvidedFixInput>> entity. The fixes are passed as part of the | |
| request body. | |
| As response, a map of link:#diff-info[DiffInfo] is returned that describes the diffs. | |
| Each link:#diff-info[DiffInfo] is the differences between the patch set indicated by revision-id | |
| and a virtual patch set with the applied fix. No content on the server will be modified as part of this request. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~Id6f0b9d946791f8aba90ace53074eda565983452/revisions/1/fix:preview HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "fix_replacement_infos": [ | |
| { | |
| "path": "abcd.txt", | |
| "range": { | |
| "start_line": 2, | |
| "start_character": 2, | |
| "end_line": 2, | |
| "end_character": 5 | |
| }, | |
| "replacement": "abcdefg" | |
| } | |
| ] | |
| } | |
| ---- | |
| If the `Preview Provided Fix` operation was successful, a link:#diff-info[DiffInfo] previewing the | |
| change is returned. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "abcd.txt": { | |
| "meta_a": { | |
| "name": "abcd.txt", | |
| "content_type": "text/plain", | |
| "lines": 3 | |
| }, | |
| "meta_b": { | |
| "name": "abcd.txt", | |
| "content_type": "text/plain", | |
| "lines": 3 | |
| }, | |
| "intraline_status": "OK", | |
| "change_type": "MODIFIED", | |
| "content": [ | |
| { | |
| "ab": [ | |
| "ABCDEFGHI" | |
| ] | |
| }, | |
| { | |
| "a": [ | |
| "JKLMNOPQR" | |
| ], | |
| "b": [ | |
| "JKabcdefgOPQR" | |
| ], | |
| "edit_a": [ | |
| [ | |
| 2, | |
| 3 | |
| ] | |
| ], | |
| "edit_b": [ | |
| [ | |
| 2, | |
| 7 | |
| ] | |
| ] | |
| }, | |
| { | |
| "ab": [ | |
| "" | |
| ] | |
| } | |
| ] | |
| } | |
| } | |
| ---- | |
| [[get-blame]] | |
| === Get Blame | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/files/link:#file-id[\{file-id\}]/blame' | |
| -- | |
| Gets the blame of a file from a certain revision. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/blame HTTP/1.0 | |
| ---- | |
| As response a link:#blame-info[BlameInfo] entity is returned that describes the | |
| blame. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )] | |
| { | |
| [ | |
| { | |
| "author": "Joe Daw", | |
| "id": "64e140b4de5883a4dd74d06c2b62ccd7ffd224a7", | |
| "time": 1421441349, | |
| "commit_msg": "RST test\n\nChange-Id: I11e9e24bd122253f4bb10c36dce825ac2410d646\n", | |
| "ranges": [ | |
| { | |
| "start": 1, | |
| "end": 10 | |
| }, | |
| { | |
| "start": 16, | |
| "end": 296 | |
| } | |
| ] | |
| }, | |
| { | |
| "author": "Jane Daw", | |
| "id": "8d52621a0e2ac6adec73bd3a49f2371cd53137a7", | |
| "time": 1421825421, | |
| "commit_msg": "add banner\n\nChange-Id: I2eced9b2691015ae3c5138f4d0c4ca2b8fb15be9\n", | |
| "ranges": [ | |
| { | |
| "start": 13, | |
| "end": 13 | |
| } | |
| ] | |
| } | |
| ] | |
| } | |
| ---- | |
| The `base` parameter can be specified to control the base patch set from which | |
| the blame should be generated. | |
| [[set-reviewed]] | |
| === Set Reviewed | |
| -- | |
| 'PUT /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/files/link:#file-id[\{file-id\}]/reviewed' | |
| -- | |
| Marks a file of a revision as reviewed by the calling user. | |
| .Request | |
| ---- | |
| PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/reviewed HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 201 Created | |
| ---- | |
| If the file was already marked as reviewed by the calling user the | |
| response is "`200 OK`". | |
| [[delete-reviewed]] | |
| === Delete Reviewed | |
| -- | |
| 'DELETE /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/files/link:#file-id[\{file-id\}]/reviewed' | |
| -- | |
| Deletes the reviewed flag of the calling user from a file of a revision. | |
| .Request | |
| ---- | |
| DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/reviewed HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 204 No Content | |
| ---- | |
| [[cherry-pick]] | |
| === Cherry Pick Revision | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/cherrypick' | |
| -- | |
| Cherry picks a revision to a destination branch. | |
| If one of the secondary emails associated with the user performing the operation was used as the | |
| committer email in the original revision, the same email will be used as the committer email | |
| in the new patch set; otherwise, the user's preferred email will be used. | |
| To cherry pick a commit with no change-id associated with it, see | |
| link:rest-api-projects.html#cherry-pick-commit[CherryPickCommit]. | |
| The commit message and destination branch must be provided in the request body inside a | |
| link:#cherrypick-input[CherryPickInput] entity. If the commit message | |
| does not specify a Change-Id, a new one is picked for the destination change. | |
| When cherry-picking a change into a branch that already contains the Change-Id | |
| that we want to cherry-pick, the cherry-pick will create a new patch-set on the | |
| destination's branch's appropriate Change-Id. If the change is closed on the | |
| destination branch, the cherry-pick will fail. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/cherrypick HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "message" : "Implementing Feature X", | |
| "destination" : "release-branch" | |
| } | |
| ---- | |
| As response a link:#change-info[ChangeInfo] entity is returned that | |
| describes the resulting cherry-pick change. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9941", | |
| "project": "myProject", | |
| "branch": "release-branch", | |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9941", | |
| "subject": "Implementing Feature X", | |
| "status": "NEW", | |
| "created": "2013-02-01 09:59:32.126000000", | |
| "updated": "2013-02-21 11:16:36.775000000", | |
| "mergeable": true, | |
| "insertions": 12, | |
| "deletions": 11, | |
| "_number": 3965, | |
| "owner": { | |
| "name": "John Doe" | |
| }, | |
| "current_revision_number": 2 | |
| } | |
| ---- | |
| [[revision-reviewer-endpoints]] | |
| == Revision Reviewer Endpoints | |
| [[list-revision-reviewers]] | |
| === List Revision Reviewers | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/reviewers/' | |
| -- | |
| Lists the reviewers of a revision. | |
| Please note that only the current revision is supported. | |
| As result a list of link:#reviewer-info[ReviewerInfo] entries is returned. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/reviewers/ HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| [ | |
| { | |
| "approvals": { | |
| "Verified": "+1", | |
| "Code-Review": "+2" | |
| }, | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com" | |
| }, | |
| { | |
| "approvals": { | |
| "Verified": " 0", | |
| "Code-Review": "-1" | |
| }, | |
| "_account_id": 1000097, | |
| "name": "Jane Roe", | |
| "email": "jane.roe@example.com" | |
| } | |
| ] | |
| ---- | |
| [[list-revision-votes]] | |
| === List Revision Votes | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/reviewers/link:rest-api-accounts.html#account-id[\{account-id\}]/votes/' | |
| -- | |
| Lists the votes for a specific reviewer of the revision. | |
| Please note that only the current revision is supported. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/reviewers/John%20Doe/votes/ HTTP/1.0 | |
| ---- | |
| As result a map is returned that maps the label name to the label value. | |
| The entries in the map are sorted by label name. | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json;charset=UTF-8 | |
| )]}' | |
| { | |
| "Code-Review": -1, | |
| "Verified": 1, | |
| "Work-In-Progress": 1 | |
| } | |
| ---- | |
| [[delete-revision-vote]] | |
| === Delete Revision Vote | |
| -- | |
| 'DELETE /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}] | |
| /reviewers/link:rest-api-accounts.html#account-id[\{account-id\}]/votes/link:#label-id[\{label-id\}]' + | |
| 'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}] | |
| /reviewers/link:rest-api-accounts.html#account-id[\{account-id\}]/votes/link:#label-id[\{label-id\}]/delete' | |
| -- | |
| Deletes a single vote from a revision. The deletion will be possible only | |
| if the revision is the current revision. By using this endpoint you can prevent | |
| deleting the vote (with same label) from a newer patch set by mistake. | |
| Note, that even when the last vote of a reviewer is removed the reviewer itself | |
| is still listed on the change. | |
| If another user removed a user's vote, the user with the deleted vote will be | |
| added to the attention set. | |
| .Request | |
| ---- | |
| DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/reviewers/John%20Doe/votes/Code-Review HTTP/1.0 | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/reviewers/John%20Doe/votes/Code-Review/delete HTTP/1.0 | |
| ---- | |
| Options can be provided in the request body as a | |
| link:#delete-vote-input[DeleteVoteInput] entity. | |
| Historically, this method allowed a body in the DELETE, but that behavior is | |
| link:https://www.gerritcodereview.com/releases/2.16.md[deprecated,role=external,window=_blank]. | |
| In this case, use a POST request instead: | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/reviewers/John%20Doe/votes/Code-Review/delete HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "notify": "NONE" | |
| } | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 204 No Content | |
| ---- | |
| [[attention-set-endpoints]] | |
| == Attention Set Endpoints | |
| [[get-attention-set]] | |
| === Get Attention Set | |
| -- | |
| 'GET /changes/link:#change-id[\{change-id\}]/attention' | |
| -- | |
| Returns all users that are currently in the attention set. | |
| As response a list of link:#attention-set-info[AttentionSetInfo] | |
| entity is returned. | |
| .Request | |
| ---- | |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/attention HTTP/1.0 | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| [ | |
| { | |
| "account": { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com", | |
| "username": "jdoe" | |
| }, | |
| "last_update": "2013-02-01 09:59:32.126000000", | |
| "reason": "reviewer or cc replied" | |
| }, | |
| { | |
| "account": { | |
| "_account_id": 1000097, | |
| "name": "Jane Doe", | |
| "email": "jane.doe@example.com", | |
| "username": "janedoe" | |
| }, | |
| "last_update": "2013-02-01 09:59:32.126000000", | |
| "reason": "Reviewer was added" | |
| } | |
| ] | |
| ---- | |
| [[add-to-attention-set]] | |
| === Add To Attention Set | |
| -- | |
| 'POST /changes/link:#change-id[\{change-id\}]/attention' | |
| -- | |
| Adds a single user to the attention set of a change. | |
| A user can only be added if they are not in the attention set. | |
| If a user is added while already in the attention set, the | |
| request is silently ignored. | |
| The user must be a reviewer, cc, uploader, or owner on the change. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/attention HTTP/1.0 | |
| ---- | |
| Details should be provided in the request body as an | |
| link:#attention-set-input[AttentionSetInput] entity. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/attention HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "user": "John Doe", | |
| "reason": "reason" | |
| } | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 200 OK | |
| Content-Disposition: attachment | |
| Content-Type: application/json; charset=UTF-8 | |
| )]}' | |
| { | |
| "_account_id": 1000096, | |
| "name": "John Doe", | |
| "email": "john.doe@example.com", | |
| "username": "jdoe" | |
| } | |
| ---- | |
| [[remove-from-attention-set]] | |
| === Remove from Attention Set | |
| -- | |
| 'DELETE /changes/link:#change-id[\{change-id\}]/attention/link:rest-api-accounts.html#account-id[\{account-id\}]' + | |
| 'POST /changes/link:#change-id[\{change-id\}]/attention/link:rest-api-accounts.html#account-id[\{account-id\}]/delete' | |
| -- | |
| Deletes a single user from the attention set of a change. | |
| A user can only be removed from the attention set if they | |
| are currently in the attention set. Otherwise, the request | |
| is silently ignored. | |
| .Request | |
| ---- | |
| DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/attention/John%20Doe HTTP/1.0 | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/attention/John%20Doe/delete HTTP/1.0 | |
| ---- | |
| Reason can be provided in the request body as an | |
| link:#attention-set-input[AttentionSetInput] entity. | |
| User must be left empty, or the user must be exactly | |
| the same user as in the request header. | |
| .Request | |
| ---- | |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/attention/John%20Doe/delete HTTP/1.0 | |
| Content-Type: application/json; charset=UTF-8 | |
| { | |
| "reason": "reason" | |
| } | |
| ---- | |
| .Response | |
| ---- | |
| HTTP/1.1 204 No Content | |
| ---- | |
| [[ids]] | |
| == IDs | |
| [[account-id]] | |
| === link:rest-api-accounts.html#account-id[\{account-id\}] | |
| -- | |
| -- | |
| [[change-id]] | |
| === \{change-id\} | |
| Identifier that uniquely identifies one change. It contains the URL-encoded | |
| project name as well as the change number: "<project>~<changeNumber>" | |
| ==== Alternative identifiers | |
| Gerrit also supports an array of other change identifiers. | |
| [NOTE] | |
| Even though these identifiers will work in the majority of cases it is highly | |
| recommended to use "<project>~<changeNumber>" whenever possible. | |
| Since these identifiers require additional lookups from index and caches, to | |
| be translated to the "<project>~<changeNumber>" identifier, they | |
| may result in both false-positives and false-negatives. | |
| Furthermore the additional lookup mean that they come with a performance penalty. | |
| * an ID of the change in the format "<project>\~<branch>~<Change-Id>", | |
| where for the branch the `refs/heads/` prefix can be omitted | |
| ("myProject\~master~I8473b95934b5732ac55d26311a706c9c2bde9940") | |
| * a Change-Id if it uniquely identifies one change | |
| ("I8473b95934b5732ac55d26311a706c9c2bde9940") | |
| * a change number if it uniquely identifies one change ("4247") | |
| [[change-message-id]] | |
| === \{change-message-id\} | |
| ID of a change message returned in a link:#change-message-info[ChangeMessageInfo]. | |
| [[comment-id]] | |
| === \{comment-id\} | |
| UUID of a published comment. | |
| [[draft-id]] | |
| === \{draft-id\} | |
| UUID of a draft comment. | |
| [[flow-id]] | |
| === \{flow-id\} | |
| UUID of a flow. | |
| [[label-id]] | |
| === \{label-id\} | |
| The name of the label. | |
| [[file-id]] | |
| === \{file-id\} | |
| The path of the file. | |
| The following magic paths are supported: | |
| * `/COMMIT_MSG`: | |
| + | |
| The commit message and headers with the parent commit(s), the author | |
| information and the committer information. | |
| * `/MERGE_LIST` (for merge commits only): | |
| + | |
| The list of commits that are being integrated into the destination | |
| branch by submitting the merge commit. | |
| * `/PATCHSET_LEVEL`: | |
| + | |
| This file path is used exclusively for posting and indicating | |
| patchset-level comments, thus not relevant for other use-cases. | |
| [[fix-id]] | |
| === \{fix-id\} | |
| UUID of a suggested fix. | |
| [[revision-id]] | |
| === \{revision-id\} | |
| Identifier that uniquely identifies one revision of a change. | |
| This can be: | |
| * the literal `current` to name the current patch set/revision | |
| * a commit ID ("674ac754f91e64a0efb8087e59a176484bd534d1") | |
| * an abbreviated commit ID that uniquely identifies one revision of the | |
| change ("674ac754"), at least 4 digits are required | |
| * a numeric patch number ("1" for first patch set of the change) | |
| * "0" or the literal `edit` for a change edit | |
| [[json-entities]] | |
| == JSON Entities | |
| [[abandon-input]] | |
| === AbandonInput | |
| The `AbandonInput` entity contains information for abandoning a change. | |
| [options="header",cols="1,^1,5"] | |
| |============================= | |
| |Field Name ||Description | |
| |`message` |optional| | |
| Message to be added as review comment to the change when abandoning the | |
| change. | |
| |`notify` |optional| | |
| Notify handling that defines to whom email notifications should be sent after | |
| the change is abandoned. + | |
| Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. + | |
| If not set, the default is `ALL`. | |
| |`notify_details`|optional| | |
| Additional information about whom to notify about the update as a map | |
| of link:user-notify.html#recipient-types[recipient type] to | |
| link:#notify-info[NotifyInfo] entity. | |
| |============================= | |
| [[action-info]] | |
| === ActionInfo | |
| The `ActionInfo` entity describes a REST API call the client can | |
| make to manipulate a resource. These are frequently implemented by | |
| plugins and may be discovered at runtime. | |
| [options="header",cols="1,^1,5"] | |
| |==================================== | |
| |Field Name ||Description | |
| |`method` |optional| | |
| HTTP method to use with the action. Most actions use `POST`, `PUT` | |
| or `DELETE` to cause state changes. | |
| |`label` |optional| | |
| Short title to display to a user describing the action. In the | |
| Gerrit web interface the label is used as the text on the button | |
| presented in the UI. | |
| |`title` |optional| | |
| Longer text to display describing the action. In a web UI this | |
| should be the title attribute of the element, displaying when | |
| the user hovers the mouse. | |
| |`enabled` |optional| | |
| If true the action is permitted at this time and the caller is | |
| likely allowed to execute it. This may change if state is updated | |
| at the server or permissions are modified. Not present if false. | |
| |`enabled_options` |optional| | |
| Optional list of enabled options. + | |
| See the list of suppported options link:#action-options[below]. | |
| |==================================== | |
| [[action-options]] | |
| ==== Action Options | |
| Options that are returned via the `enabled_options` field of | |
| link:#action-info[ActionInfo]. | |
| [options="header",cols="1,^1,5"] | |
| |=================================== | |
| |REST view |Option |Description | |
| |`rebase` |`rebase`| | |
| Present if the user can rebase the change. + | |
| This is the case for the change owner and users with the | |
| link:access-control.html#category_submit[Submit] or | |
| link:access-control.html#category_rebase[Rebase] permission if they | |
| have the link:access-control.html#category_push[Push] permission. | |
| |`rebase` |`rebase_on_behalf_of_uploader`| | |
| Present if the user can rebase the change on behalf of the uploader. + | |
| This is the case for the change owner and users with the | |
| link:access-control.html#category_submit[Submit] or | |
| link:access-control.html#category_rebase[Rebase] permission. | |
| |`rebase:chain`|`rebase`| | |
| Present if the user can rebase the chain. + | |
| This is the case if the calling user can rebase each change in the | |
| chain. | |
| Rebasing a change is allowed for the change owner and users with the | |
| link:access-control.html#category_submit[Submit] or | |
| link:access-control.html#category_rebase[Rebase] permission if they | |
| have the link:access-control.html#category_push[Push] permission. | |
| |`rebase:chain`|`rebase_on_behalf_of_uploader`| | |
| Present if the user can rebase the chain on behalf of the uploader. + | |
| This is the case if the calling user can rebase each change in the | |
| chain on behalf of the uploader. | |
| Rebasing a change on behalf of the uploader is allowed for the change | |
| owner and users with the link:access-control.html#category_submit[Submit] | |
| or link:access-control.html#category_rebase[Rebase] permission. | |
| |=================================== | |
| For all other REST views no options are returned. | |
| [[applypatch-input]] | |
| === ApplyPatchInput | |
| The `ApplyPatchInput` entity contains information about a patch to apply. | |
| A new commit will be created from the patch, and saved as a new patch set. | |
| [options="header",cols="1,^1,5"] | |
| |================================= | |
| |Field Name ||Description | |
| |`patch` |required| | |
| The patch to be applied. Must be compatible with `git diff` output. | |
| For example, link:#get-patch[Get Patch] output. | |
| The patch must be provided as UTF-8 text, either directly or base64-encoded. | |
| |`allow_conflicts` |optional| | |
| If true, tolerate conflicts and add conflict markers where required. | |
| |================================= | |
| [[applypatchpatchset-input]] | |
| === ApplyPatchPatchSetInput | |
| The `ApplyPatchPatchSetInput` entity contains information for creating a new patch set from a | |
| given patch. | |
| [options="header",cols="1,^1,5"] | |
| |================================= | |
| |Field Name ||Description | |
| |`patch` |required| | |
| The details of the patch to be applied as a link:#applypatch-input[ApplyPatchInput] entity. | |
| |`commit_message` |optional| | |
| The commit message for the new patch set. If not specified, the latest patch-set message will be | |
| used. | |
| |`base` |optional| | |
| 40-hex digit SHA-1 of the commit which will be the parent commit of the newly created patch set. | |
| If set, it must be a merged commit or a change revision on the destination branch. | |
| Otherwise, the target change's branch tip will be used. | |
| |`author` |optional| | |
| The author of the commit to create. Must be an | |
| link:rest-api-accounts.html#account-input[AccountInput] entity with at least | |
| the `name` and `email` fields set. | |
| The caller needs "Forge Author" permission when using this field, unless specifies their own details. | |
| This field does not affect the owner of the change, which will continue to use the identity of the | |
| caller. | |
| |`response_format_options` |optional| | |
| List of link:#query-options[query options] to format the response. | |
| |`amend` |optional| | |
| If true, the revision from the URL will be amended by the patch. This will use the tree of the | |
| revision, apply the patch and create a new commit whose tree is the resulting tree of the operation | |
| and whose parent(s) are the parent(s) of the revision. Cannot be used together with `base`. | |
| |================================= | |
| [[approval-info]] | |
| === ApprovalInfo | |
| The `ApprovalInfo` entity contains information about an approval from a | |
| user for a label on a change. | |
| `ApprovalInfo` has the same fields as | |
| link:rest-api-accounts.html#account-info[AccountInfo]. | |
| In addition `ApprovalInfo` has the following fields: | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name ||Description | |
| |`value` |optional| | |
| The vote that the user has given for the label. If present and zero, the | |
| user is permitted to vote on the label. If absent, the user is not | |
| permitted to vote on that label. | |
| |`permitted_voting_range` |optional| | |
| The link:#voting-range-info[VotingRangeInfo] the user is authorized to vote | |
| on that label. If present, the user is permitted to vote on the label | |
| regarding the range values. If absent, the user is not permitted to vote | |
| on that label. | |
| |`date` |optional| | |
| The time and date describing when the approval was made. | |
| |`tag` |optional| | |
| Value of the `tag` field from link:#review-input[ReviewInput] set | |
| while posting the review. Votes/comments that contain `tag` with | |
| 'autogenerated:' prefix can be filtered out in the web UI. | |
| NOTE: To apply different tags on different votes/comments multiple | |
| invocations of the REST call are required. | |
| |`post_submit` |not set if `false`| | |
| If true, this vote was made after the change was submitted. | |
| |=========================== | |
| [[attention-set-info]] | |
| === AttentionSetInfo | |
| The `AttentionSetInfo` entity contains details of users that are in | |
| the link:user-attention-set.html[attention set]. | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name ||Description | |
| |`account` || link:rest-api-accounts.html#account-info[AccountInfo] entity. | |
| |`last_update` || The link:rest-api.html#timestamp[timestamp] of the last update. | |
| |`reason` || | |
| The reason for adding or removing the user. | |
| If the update was caused by another user, that account is represented by | |
| account ID in reason as `<GERRIT_ACCOUNT_18419>` and the corresponding | |
| link:rest-api-accounts.html#account-info[AccountInfo] can be found in `reason_account` field. | |
| |`reason_account` || | |
| link:rest-api-accounts.html#account-info[AccountInfo] of the user who caused the update. | |
| |=========================== | |
| [[attention-set-input]] | |
| === AttentionSetInput | |
| The `AttentionSetInput` entity contains details for adding users to the | |
| link:user-attention-set.html[attention set] and removing them from it. | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name ||Description | |
| |`user` |optional| link:rest-api-accounts.html#account-id[ID] | |
| of the account that should be added to the attention set. For removals, | |
| this field should be empty or the same as the field in the request header. | |
| |`reason` || The reason of for adding or removing the user. | |
| |`notify` |optional| | |
| Notify handling that defines to whom email notifications should be sent | |
| after the change is created. + | |
| Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. + | |
| If not set, the default is `OWNER`. | |
| |`notify_details` |optional| | |
| Additional information about whom to notify about the change creation | |
| as a map of link:user-notify.html#recipient-types[recipient type] to | |
| link:#notify-info[NotifyInfo] entity. | |
| |=========================== | |
| [[blame-info]] | |
| === BlameInfo | |
| The `BlameInfo` entity stores the commit metadata with the row coordinates where | |
| it applies. | |
| [options="header",cols="1,6"] | |
| |=========================== | |
| |Field Name | Description | |
| |`author` | The author of the commit. | |
| |`id` | The id of the commit. | |
| |`time` | Commit time. | |
| |`commit_msg` | The commit message. | |
| |`ranges` | | |
| The blame row coordinates as link:#range-info[RangeInfo] entities. | |
| |=========================== | |
| [[change-edit-input]] | |
| === ChangeEditInput | |
| The `ChangeEditInput` entity contains information for restoring a | |
| path within change edit. | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name ||Description | |
| |`restore_path`|optional|Path to file to restore. | |
| |`old_path` |optional|Old path to file to rename. | |
| |`new_path` |optional|New path to file to rename. | |
| |=========================== | |
| [[change-edit-message-input]] | |
| === ChangeEditMessageInput | |
| The `ChangeEditMessageInput` entity contains information for changing | |
| the commit message within a change edit. | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name ||Description | |
| |`message` ||New commit message. | |
| |=========================== | |
| [[change-edit-identity-input]] | |
| === ChangeEditIdentityInput | |
| The `ChangeEditIdentityInput` entity contains information for changing | |
| the author or committer identity within a change edit. | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name ||Description | |
| |`name` |optional|The name of the author/committer. If not specified, the existing name will be used. | |
| |`email` |optional|The email of the author/committer. If not specified, the existing email will be used. | |
| |`type` ||Type of the identity being edited. Must be either `AUTHOR` or `COMMITTER`. | |
| |=========================== | |
| [[change-info]] | |
| === ChangeInfo | |
| The `ChangeInfo` entity contains information about a change. | |
| [options="header",cols="1,^1,5"] | |
| |================================== | |
| |Field Name ||Description | |
| |`id` || | |
| The ID of the change. The format is "'<project>\~<_number>'". | |
| 'project' and '_number' are URL encoded. The callers must not rely on the format. | |
| |`triplet_id` || | |
| The ID of the change in the format "'<project>\~<branch>~<Change-Id>'", | |
| where 'project' and 'branch' are URL encoded. For 'branch' the | |
| `refs/heads/` prefix is omitted. | |
| |`project` ||The name of the project. | |
| |`branch` || | |
| The name of the target branch. + | |
| The `refs/heads/` prefix is omitted. | |
| |`full_branch` || | |
| The full name of the target branch. + | |
| Always starts with `refs/`. | |
| |`topic` |optional|The topic to which this change belongs. | |
| |`attention_set` |optional| | |
| The map that maps link:rest-api-accounts.html#account-id[account IDs] | |
| to link:#attention-set-info[AttentionSetInfo] of that account. Those are all | |
| accounts that are currently in the attention set. | |
| |`removed_from_attention_set` |optional| | |
| The map that maps link:rest-api-accounts.html#account-id[account IDs] | |
| to link:#attention-set-info[AttentionSetInfo] of that account. Those are all | |
| accounts that were in the attention set but were removed. The | |
| link:#attention-set-info[AttentionSetInfo] is the latest and most recent removal | |
| of the account from the attention set. | |
| |`hashtags` |optional| | |
| List of hashtags that are set on the change. | |
| |`custom_keyed_values` |optional| | |
| A map that maps custom keys to custom values that are tied to a specific change, | |
| both in the form of strings. Only set if link:#custom-keyed-values[custom keyed | |
| values] are requested. | |
| |`change_id` ||The Change-Id of the change. | |
| |`subject` || | |
| The subject of the change (header line of the commit message). | |
| |`status` || | |
| The status of the change (`NEW`, `MERGED`, `ABANDONED`). | |
| |`created` || | |
| The link:rest-api.html#timestamp[timestamp] of when the change was | |
| created. | |
| |`updated` || | |
| The link:rest-api.html#timestamp[timestamp] of when the change was last | |
| updated. | |
| |`submitted` |only set for merged changes| | |
| The link:rest-api.html#timestamp[timestamp] of when the change was | |
| submitted. | |
| |`submitter` |only set for merged changes| | |
| The user who submitted the change, as an | |
| link:rest-api-accounts.html#account-info[ AccountInfo] entity. | |
| |`starred` |not set if `false`| | |
| Whether the calling user has starred this change. | |
| Only set if link:#star[requested]. | |
| |`reviewed` |not set if `false`| | |
| Whether the change was reviewed by the calling user. | |
| Only set if link:#reviewed[reviewed] is requested. | |
| |`submit_type` |optional| | |
| The link:config-project-config.html#submit-type[submit type] of the change. + | |
| Not set for merged changes. | |
| |`mergeable` |optional| | |
| Whether the change is mergeable. + | |
| Only set for open changes if | |
| link:config-gerrit.html#change.mergeabilityComputationBehavior[change.mergeabilityComputationBehavior] | |
| is `API_REF_UPDATED_AND_CHANGE_REINDEX`. | |
| |`submittable` |optional| | |
| Whether the change has been approved by the project submit rules. + | |
| Only set if link:#submittable[requested]. | |
| |`insertions` || | |
| Number of inserted lines. | |
| |`deletions` || | |
| Number of deleted lines. | |
| |`total_comment_count` || | |
| Total number of inline comments across all patch sets. | |
| |`unresolved_comment_count` || | |
| Number of unresolved inline comment threads across all patch sets. | |
| |`_number` || | |
| The change number. (The underscore is just a relict of a prior | |
| attempt to deprecate the change number.) | |
| |`virtual_id_number` || | |
| The virtual id number is globally unique. For local changes, it is equal to the | |
| `_number` attribute. For imported changes, the original `_number` is processed | |
| through a function designed to prevent conflicts with local change numbers. | |
| Note that its usage is intended solely for Gerrit's internals and UI, and | |
| adoption outside these scenarios is not advised. | |
| |`owner` || | |
| The owner of the change as an link:rest-api-accounts.html#account-info[ | |
| AccountInfo] entity. | |
| |`actions` |optional| | |
| Actions the caller might be able to perform on this revision. The | |
| information is a map of view name to link:#action-info[ActionInfo] | |
| entities. | |
| |`submit_records` |optional| | |
| List of the link:rest-api-changes.html#submit-record-info[SubmitRecordInfo] | |
| containing the submit records for the change at the latest patchset. This field | |
| is deprecated in favour of `submit_requirements`. | |
| Only set if link:#submit-requirements[`SUBMIT_REQUIREMENTS`] is requested. | |
| |`requirements` |optional| | |
| List of the link:rest-api-changes.html#requirement[requirements] to be met before this change | |
| can be submitted. This field is deprecated in favour of `submit_requirements`. | |
| Only set if link:#submit-requirements[`SUBMIT_REQUIREMENTS`] is requested. | |
| |`submit_requirements` |optional| | |
| List of the link:#submit-requirement-result-info[SubmitRequirementResultInfo] | |
| containing the evaluated submit requirements for the change. | |
| Only set if link:#submit-requirements[`SUBMIT_REQUIREMENTS`] is requested. | |
| |`labels` |optional| | |
| The labels of the change as a map that maps the label names to | |
| link:#label-info[LabelInfo] entries. + | |
| Only set if link:#labels[labels] or link:#detailed-labels[detailed | |
| labels] are requested. | |
| |`permitted_labels` |optional| | |
| A map of the permitted labels that maps a label name to the list of | |
| values that the current user can vote on. + | |
| Only set if link:#detailed-labels[detailed labels] are requested. | |
| |`removable_labels` |optional| | |
| A map of the removable labels that maps a label name to the map of | |
| values and reviewers ( | |
| link:rest-api-accounts.html#account-info[AccountInfo] entities) | |
| that are allowed to be removed from the change. + | |
| Only set if link:#labels[labels] or | |
| link:#detailed-labels[detailed labels] are requested. | |
| |`removable_reviewers`|optional| | |
| The reviewers that can be removed by the calling user as a list of | |
| link:rest-api-accounts.html#account-info[AccountInfo] entities. + | |
| Only set if link:#labels[labels] or | |
| link:#detailed-labels[detailed labels] are requested. | |
| |`reviewers` |optional| | |
| The reviewers as a map that maps a reviewer state to a list of | |
| link:rest-api-accounts.html#account-info[AccountInfo] entities. | |
| Possible reviewer states are `REVIEWER`, `CC`. + | |
| `REVIEWER`: Users with at least one non-zero vote on the change. + | |
| `CC`: Users that were added to the change, but have not voted. + | |
| Only set if link:#labels[labels] or | |
| link:#detailed-labels[detailed labels] are requested. | |
| |`pending_reviewers` |optional| | |
| Updates to `reviewers` that have been made while the change was in the | |
| WIP state. Only present on WIP changes and only if there are pending | |
| reviewer updates to report. These are reviewers who have not yet been | |
| notified about being added to or removed from the change. + | |
| Only set if link:#labels[labels] or | |
| link:#detailed-labels[detailed labels] are requested. | |
| Possible states are `REVIEWER`, `CC` and `REMOVED`. + | |
| `REVIEWER`: Users with at least one non-zero vote on the change. + | |
| `CC`: Users that were added to the change, but have not voted. + | |
| `REMOVED`: Users that were previously reviewers on the change, but have | |
| been removed. | |
| |`reviewer_updates`|optional| | |
| Updates to reviewers set for the change as | |
| link:#review-update-info[ReviewerUpdateInfo] entities. | |
| Only set if link:#reviewer-updates[reviewer updates] are requested. | |
| |`messages`|optional| | |
| Messages associated with the change as a list of | |
| link:#change-message-info[ChangeMessageInfo] entities. + | |
| Only set if link:#messages[messages] are requested. | |
| |`current_revision_number`||The number of the current patch set of this | |
| change. + | |
| |`current_revision` |optional| | |
| The commit ID of the current patch set of this change. + | |
| Only set if link:#current-revision[the current revision] is requested | |
| or if link:#all-revisions[all revisions] are requested. | |
| |`revisions` |optional| | |
| All patch sets of this change as a map that maps the commit ID of the | |
| patch set to a link:#revision-info[RevisionInfo] entity. + | |
| Only set if link:#current-revision[the current revision] is requested | |
| (in which case it will only contain a key for the current revision) or | |
| if link:#all-revisions[all revisions] are requested. | |
| |`meta_rev_id` |optional| | |
| The SHA-1 of the NoteDb meta ref. | |
| |`tracking_ids` |optional| | |
| A list of link:#tracking-id-info[TrackingIdInfo] entities describing | |
| references to external tracking systems. Only set if | |
| link:#tracking-ids[tracking ids] are requested. | |
| |`_more_changes` |optional, not set if `false`| | |
| Whether the query would deliver more results if not limited. + | |
| Only set on the last change that is returned. | |
| |`problems` |optional| | |
| A list of link:#problem-info[ProblemInfo] entities describing potential | |
| problems with this change. Only set if link:#check[CHECK] is set. | |
| |`is_private` |optional, not set if `false`| | |
| When present, change is marked as private. | |
| |`work_in_progress` |optional, not set if `false`| | |
| When present, change is marked as Work In Progress. | |
| |`has_review_started` |optional, not set if `false`| | |
| When present, change has been marked Ready at some point in time. | |
| |`revert_of` |optional| | |
| The change number of the change that this change reverts. | |
| |`submission_id` |optional| | |
| ID of the submission of this change. Only set if the status is `MERGED`. | |
| This ID is equal to the change number of the change that triggered the | |
| submission. If the change that triggered the submission also has a topic, | |
| it will be "<id>-<topic>" of the change that triggered the submission. | |
| The callers must not rely on the format of the submission ID. | |
| |`cherry_pick_of_change` |optional| | |
| The change number of the change that this change was cherry-picked from. | |
| Only set if the cherry-pick has been done through the Gerrit REST API (and | |
| not if a cherry-picked commit was pushed). | |
| |`cherry_pick_of_patch_set`|optional| | |
| The patchset number of the change that this change was cherry-picked from. | |
| Only set if the cherry-pick has been done through the Gerrit REST API (and | |
| not if a cherry-picked commit was pushed). | |
| |`contains_git_conflicts` |optional, not set if `false`| | |
| Whether the change contains conflicts. + | |
| If `true`, some of the file contents of the change contain git conflict | |
| markers to indicate the conflicts. + | |
| Only set if this change info is returned in response to a request that | |
| creates a new change or patch set and conflicts are allowed. In | |
| particular this field is only populated if the change info is returned | |
| by one of the following REST endpoints:link:#apply-patch[Apply Patch], | |
| link:#create-change[Create Change], | |
| link:#create-merge-patch-set-for-change[Create Merge Patch Set For Change], | |
| link:#cherry-pick[Cherry Pick Revision], | |
| link:rest-api-project.html#cherry-pick-commit[Cherry Pick Commit], | |
| link:#rebase-change[Rebase Change] | |
| |================================== | |
| [[change-input]] | |
| === ChangeInput | |
| The `ChangeInput` entity contains information about creating a new change. | |
| [options="header",cols="1,^1,5"] | |
| |================================== | |
| |Field Name ||Description | |
| |`project` ||The name of the project. | |
| |`branch` || | |
| The name of the target branch. + | |
| The `refs/heads/` prefix is omitted. | |
| |`subject` || | |
| The commit message of the change. Comment lines (beginning with `#`) | |
| will be removed. If the commit message contains a Change-Id (as a | |
| "Change-Id: I..." footer) that Change-Id will be used for the newly | |
| created changed. If a change with this Change-Id already exists for | |
| same repository and branch, the request is rejected since Change-Ids | |
| must be unique per repository and branch. If the commit message doesn't | |
| contain a Change-Id, a newly generated Change-Id is automatically | |
| inserted into the commit message. | |
| |`topic` |optional|The topic to which this change belongs. | |
| Topic can't contain quotation marks. | |
| |`status` |optional, default to `NEW`| | |
| The status of the change (only `NEW` accepted here). | |
| |`is_private` |optional, default to `false`| | |
| Whether the new change should be marked as private. | |
| |`work_in_progress` |optional, default to `false`| | |
| Whether the new change should be set to work in progress. | |
| |`base_change` |optional| | |
| A link:#change-id[\{change-id\}] that identifies the base change for a create | |
| change operation. + | |
| Mutually exclusive with `base_commit`. + | |
| If neither `base_commit` nor `base_change` are set, the target branch tip will | |
| be used as the parent commit. | |
| |`base_commit` |optional| | |
| A 40-digit hex SHA-1 of the commit which will be the parent commit of the newly | |
| created change. If set, it must be a merged commit on the destination branch. + | |
| Mutually exclusive with `base_change`. + | |
| If neither `base_commit` nor `base_change` are set, the target branch tip will | |
| be used as the parent commit. | |
| |`new_branch` |optional, default to `false`| | |
| Allow creating a new branch when set to `true`. Using this option is | |
| only possible for non-merge commits (if the `merge` field is not set). | |
| |`validation_options` |optional| | |
| Map with key-value pairs that are forwarded as options to the commit validation | |
| listeners (e.g. can be used to skip certain validations). Which validation | |
| options are supported depends on the installed commit validation listeners. | |
| Gerrit core doesn't support any validation options, but commit validation | |
| listeners that are implemented in plugins may. Please refer to the | |
| documentation of the installed plugins to learn whether they support validation | |
| options. Unknown validation options are silently ignored. | |
| |`custom_keyed_values`|optional|Custom keyed values as a | |
| map from custom keys to values. | |
| |`merge` |optional| | |
| The detail of a merge commit as a link:#merge-input[MergeInput] entity. | |
| If set, the target branch (see `branch` field) must exist (it is not | |
| possible to create it automatically by setting the `new_branch` field | |
| to `true`. | |
| |`patch` |optional| | |
| The detail of a patch to be applied as an link:#applypatch-input[ApplyPatchInput] entity. | |
| |`author` |optional| | |
| The author of the commit to create. Must be an | |
| link:rest-api-accounts.html#account-input[AccountInput] entity with at least | |
| the `name` and `email` fields set. | |
| The caller needs "Forge Author" permission when using this field. | |
| This field does not affect the owner of the change, which will | |
| continue to use the identity of the caller. | |
| |`notify` |optional| | |
| Notify handling that defines to whom email notifications should be sent | |
| after the change is created. + | |
| Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. + | |
| If not set, the default is `OWNER` for WIP changes and `ALL` otherwise. | |
| |`notify_details` |optional| | |
| Additional information about whom to notify about the change creation | |
| as a map of link:user-notify.html#recipient-types[recipient type] to | |
| link:#notify-info[NotifyInfo] entity. | |
| |`response_format_options` |optional| | |
| List of link:#query-options[query options] to format the response. | |
| |================================== | |
| [[change-message-info]] | |
| === ChangeMessageInfo | |
| The `ChangeMessageInfo` entity contains information about a message | |
| attached to a change. | |
| [options="header",cols="1,^1,5"] | |
| |================================== | |
| |Field Name ||Description | |
| |`id` ||The ID of the message. | |
| |`author` |optional| | |
| Author of the message as an | |
| link:rest-api-accounts.html#account-info[AccountInfo] entity. + | |
| Unset if written by the Gerrit system. | |
| |`real_author` |optional| | |
| Real author of the message as an | |
| link:rest-api-accounts.html#account-info[AccountInfo] entity. + | |
| Only set if the message was posted on behalf of another user. | |
| |`date` || | |
| The link:rest-api.html#timestamp[timestamp] this message was posted. | |
| |`message` || | |
| The text left by the user or Gerrit system. Accounts are served as account IDs | |
| inlined in the text as `<GERRIT_ACCOUNT_18419>`. | |
| All accounts, used in message, can be found in `accounts_in_message` | |
| field. | |
| |`accounts_in_message` || | |
| link:rest-api-accounts.html#account-info[AccountInfo] list, used in `message`. | |
| |`tag` |optional| | |
| Value of the `tag` field from link:#review-input[ReviewInput] set | |
| while posting the review. Votes/comments that contain `tag` with | |
| 'autogenerated:' prefix can be filtered out in the web UI. | |
| NOTE: To apply different tags on different votes/comments multiple | |
| invocations of the REST call are required. | |
| |`_revision_number` |optional| | |
| Which patchset (if any) generated this message. | |
| |================================== | |
| [[cherrypick-input]] | |
| === CherryPickInput | |
| The `CherryPickInput` entity contains information for cherry-picking a change to a new branch. | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name ||Description | |
| |`message` |optional| | |
| Commit message for the cherry-pick change. If not set, the commit message of | |
| the cherry-picked commit is used. | |
| |`destination` ||Destination branch | |
| |`base` |optional| | |
| 40-hex digit SHA-1 of the commit which will be the parent commit of the newly created change. | |
| If set, it must be a merged commit or a change revision on the destination branch. | |
| |`parent` |optional, defaults to 1| | |
| Number of the parent relative to which the cherry-pick should be considered. | |
| |`notify` |optional| | |
| Notify handling that defines to whom email notifications should be sent | |
| after the cherry-pick. + | |
| Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. + | |
| If not set, the default is `ALL`. | |
| |`notify_details` |optional| | |
| Additional information about whom to notify about the update as a map | |
| of link:user-notify.html#recipient-types[recipient type] to | |
| link:#notify-info[NotifyInfo] entity. | |
| |`keep_reviewers` |optional, defaults to false| | |
| If `true`, carries reviewers and ccs over from original change to newly created one. | |
| |`allow_conflicts` |optional, defaults to false| | |
| If `true`, the cherry-pick uses content merge and succeeds also if | |
| there are conflicts. If there are conflicts the file contents of the | |
| created change contain git conflict markers to indicate the conflicts. | |
| Callers can find out if there were conflicts by checking the | |
| `contains_git_conflicts` field in the link:#change-info[ChangeInfo]. If | |
| there are conflicts the cherry-pick change is marked as | |
| work-in-progress. | |
| |`topic` |optional| | |
| The topic of the created cherry-picked change. If not set, the default depends | |
| on the source. If the source is a change with a topic, the resulting topic | |
| of the cherry-picked change will be {source_change_topic}-{destination_branch}. | |
| Otherwise, if the source change has no topic, or the source is a commit, | |
| the created change will have no topic. | |
| If the change already exists, the topic will not change if not set. If set, the | |
| topic will be overridden. | |
| |`allow_empty` |optional, defaults to false| | |
| If `true`, the cherry-pick succeeds also if the created commit will be empty. | |
| If `false`, a cherry-pick that would create an empty commit fails without creating | |
| the commit. | |
| |`committer_email`|optional| | |
| Cherry-pick is committed using this email address. Only the registered emails | |
| of the calling user are considered valid. Defaults to source commit's committer | |
| email if it is a registered email of the calling user, else defaults to calling | |
| user's preferred email. | |
| |`validation_options`|optional| | |
| Map with key-value pairs that are forwarded as options to the commit validation | |
| listeners (e.g. can be used to skip certain validations). Which validation | |
| options are supported depends on the installed commit validation listeners. | |
| Gerrit core doesn't support any validation options, but commit validation | |
| listeners that are implemented in plugins may. Please refer to the | |
| documentation of the installed plugins to learn whether they support validation | |
| options. Unknown validation options are silently ignored. | |
| |=========================== | |
| [[comment-info]] | |
| === CommentInfo | |
| The `CommentInfo` entity contains information about an inline comment. | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name ||Description | |
| |`patch_set` |optional| | |
| The patch set number for the comment; only set in contexts where + | |
| comments may be returned for multiple patch sets. | |
| |`id` ||The URL encoded UUID of the comment. | |
| |`path` |optional| | |
| link:#file-id[The file path] for which the inline comment was done. + | |
| Not set if returned in a map where the key is the file path. | |
| |`side` |optional| | |
| The side on which the comment was added. + | |
| Allowed values are `REVISION` and `PARENT`. + | |
| If not set, the default is `REVISION`. | |
| |`parent` |optional| | |
| The 1-based parent number. Used only for merge commits when `side == PARENT`. | |
| When not set the comment is for the auto-merge tree. | |
| |`line` |optional| | |
| The number of the line for which the comment was done. + | |
| If range is set, this equals the end line of the range. + | |
| If neither line nor range is set, it's a file comment. | |
| |`range` |optional| | |
| The range of the comment as a link:#comment-range[CommentRange] | |
| entity. | |
| |`in_reply_to` |optional| | |
| The URL encoded UUID of the comment to which this comment is a reply. | |
| |`message` |optional|The comment message. | |
| |`updated` || | |
| The link:rest-api.html#timestamp[timestamp] of when this comment was | |
| written. | |
| |`author` |optional| | |
| The author of the message as an | |
| link:rest-api-accounts.html#account-info[AccountInfo] entity. + | |
| Unset for draft comments, assumed to be the calling user. | |
| |`tag` |optional| | |
| Value of the `tag` field from link:#review-input[ReviewInput] set | |
| while posting the review. | |
| NOTE: To apply different tags on different votes/comments multiple | |
| invocations of the REST call are required. | |
| |`unresolved` |optional| | |
| Whether or not the comment must be addressed by the user. The state of | |
| resolution of a comment thread is stored in the last comment in that thread | |
| chronologically. | |
| |`change_message_id` |optional| | |
| Available with the link:#list-change-comments[list change comments] endpoint. | |
| Contains the link:rest-api-changes.html#change-message-info[id] of the change | |
| message that this comment is linked to. | |
| |`commit_id` |optional| | |
| Hex commit SHA-1 (40 characters string) of the commit of the patchset to which | |
| this comment applies. | |
| |`context_lines` |optional| | |
| A list of link:#context-line[ContextLine] containing the lines of the source | |
| file where the comment was written. Available only if the "enable-context" | |
| parameter (see link:#list-change-comments[List Change Comments]) is set. | |
| |`source_content_type` |optional| | |
| Mime type of the file where the comment is written. Available only if the | |
| "enable-context" parameter (see link:#list-change-comments[List Change Comments]) | |
| is set. | |
| |`fix_suggestions`|optional|Suggested fixes for this comment as a list of | |
| <<fix-suggestion-info,FixSuggestionInfo>> entities. | |
| |=========================== | |
| [[comment-input]] | |
| === CommentInput | |
| The `CommentInput` entity contains information for creating an inline | |
| comment. | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name ||Description | |
| |`id` |optional| | |
| The URL encoded UUID of the comment if an existing draft comment should | |
| be updated. | |
| |`path` |optional| | |
| link:#file-id[The file path] for which the inline comment should be added. + | |
| Doesn't need to be set if contained in a map where the key is the file | |
| path. | |
| |`side` |optional| | |
| The side on which the comment should be added. + | |
| Allowed values are `REVISION` and `PARENT`. + | |
| If not set, the default is `REVISION`. | |
| |`line` |optional| | |
| The number of the line for which the comment should be added. + | |
| `0` if it is a file comment. + | |
| If neither line nor range is set, a file comment is added. + | |
| If range is set, this value is ignored in favor of the `end_line` of the range. | |
| |`range` |optional| | |
| The range of the comment as a link:#comment-range[CommentRange] | |
| entity. | |
| |`in_reply_to` |optional| | |
| The URL encoded UUID of the comment to which this comment is a reply. | |
| |`updated` |optional| | |
| The link:rest-api.html#timestamp[timestamp] of this comment. + | |
| Accepted but ignored. | |
| |`message` |optional| | |
| The comment message. + | |
| If not set and an existing draft comment is updated, the existing draft | |
| comment is deleted. | |
| |`tag` |optional, drafts only| | |
| Value of the `tag` field. Only allowed on link:#create-draft[draft comment] + | |
| inputs; for published comments, use the `tag` field in + | |
| link:#review-input[ReviewInput]. Votes/comments that contain `tag` with | |
| 'autogenerated:' prefix can be filtered out in the web UI. | |
| |`unresolved` |optional| | |
| Whether or not the comment must be addressed by the user. This value will | |
| default to false if the comment is an orphan, or the value of the `in_reply_to` | |
| comment if it is supplied. | |
| |`fix_suggestions`|optional|Suggested fixes for this comment as a list of | |
| <<fix-suggestion-info,FixSuggestionInfo>> entities. | |
| |=========================== | |
| [[comment-range]] | |
| === CommentRange | |
| The `CommentRange` entity describes the range of an inline comment. | |
| The comment range is a range from the start position, specified by `start_line` | |
| and `start_character`, to the end position, specified by `end_line` and | |
| `end_character`. The start position is *inclusive* and the end position is | |
| *exclusive*. | |
| So, a range over part of a line will have `start_line` equal to | |
| `end_line`; however a range with `end_line` set to 5 and `end_character` equal | |
| to 0 will not include any characters on line 5, | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name ||Description | |
| |`start_line` ||The start line number of the range. (1-based) | |
| |`start_character` ||The character position in the start line. (0-based) | |
| |`end_line` ||The end line number of the range. (1-based) | |
| |`end_character` ||The character position in the end line. (0-based) | |
| |=========================== | |
| [[context-line]] | |
| === ContextLine | |
| The `ContextLine` entity contains the line number and line text of a single | |
| line of the source file content. | |
| [options="header",cols="1,6"] | |
| |=========================== | |
| |Field Name |Description | |
| |`line_number` |The line number of the source line. | |
| |`context_line` |String containing the line text. | |
| |=========================== | |
| [[commit-info]] | |
| === CommitInfo | |
| The `CommitInfo` entity contains information about a commit. | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name ||Description | |
| |`commit` |Optional| | |
| The commit ID. Not set if included in a link:#revision-info[ | |
| RevisionInfo] entity that is contained in a map which has the commit ID | |
| as key. | |
| |`parents` || | |
| The parent commits of this commit as a list of | |
| link:#commit-info[CommitInfo] entities. In each parent | |
| only the `commit` and `subject` fields are populated. | |
| |`author` ||The author of the commit as a | |
| link:#git-person-info[GitPersonInfo] entity. | |
| |`committer` ||The committer of the commit as a | |
| link:#git-person-info[GitPersonInfo] entity. | |
| |`subject` || | |
| The subject of the commit (header line of the commit message). | |
| |`message` ||The commit message. | |
| |`web_links` |optional| | |
| Links to the patch set in external sites as a list of | |
| link:#web-link-info[WebLinkInfo] entities. | |
| |`resolve_conflicts_web_links` |optional| | |
| Links to the commit in external sites for resolving conflicts as a list of | |
| link:#web-link-info[WebLinkInfo] entities. | |
| |=========================== | |
| [[commit-message-info]] | |
| === CommitMessageInfo | |
| The `CommitMessageInfo` entity contains information about the commit | |
| message of a change. | |
| [options="header",cols="1,6"] | |
| |============================ | |
| |Field Name |Description | |
| |`subject` |The subject of the change (first line of the commit | |
| message). | |
| |`full_message` |Full commit message of the change. | |
| |`footers` |The footers from the commit message as a map of | |
| key-value pairs. If there are multiple footers with the same key, only the last | |
| footer with that key is returned. | |
| |============================ | |
| [[commit-message-input]] | |
| === CommitMessageInput | |
| The `CommitMessageInput` entity contains information for changing | |
| the commit message of a change. | |
| [options="header",cols="1,^1,5"] | |
| |============================= | |
| |Field Name ||Description | |
| |`message` ||New commit message. | |
| |`committer_email`|optional| | |
| New message is committed using this email address. Only the | |
| registered emails of the calling user are considered valid. | |
| |`notify` |optional| | |
| Notify handling that defines to whom email notifications should be sent | |
| after the commit message was updated. + | |
| Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. + | |
| If not set, the default is `OWNER` for WIP changes and `ALL` otherwise. | |
| |`notify_details`|optional| | |
| Additional information about whom to notify about the update as a map | |
| of link:user-notify.html#recipient-types[recipient type] to | |
| link:#notify-info[NotifyInfo] entity. | |
| |============================= | |
| [[conflicts-info]] | |
| === ConflictsInfo | |
| The `ConflictsInfo` entity contains information about conflicts in a revision. | |
| [options="header",cols="1,^1,5"] | |
| |============================= | |
| |Field Name ||Description | |
| |`base` |optional| | |
| The SHA1 of the commit that was used as the base commit for the Git merge that created the | |
| revision. + | |
| A base is not set if: + | |
| - the merged commits do not have a common ancestor (in this case `no_base_reason` is | |
| `NO_COMMON_ANCESTOR`). + | |
| - the merged commits have multiple merge bases (happens for criss-cross-merges) and the base was | |
| computed (in this case `no_base_reason` is `COMPUTED_BASE`). + | |
| - a one sided merge strategy (e.g. `ours` or `theirs`) has been used and computing a base was not | |
| required for the merge (in this case `no_base_reason` is `ONE_SIDED_MERGE_STRATEGY`). + | |
| - the revision was not created by performing a Git merge operation (in this case `no_base_reason` | |
| is `NO_MERGE_PERFORMED`). + | |
| - the revision has been created before Gerrit started to store the base for conflicts (in this case | |
| `no_base_reason` is `HISTORIC_DATA_WITHOUT_BASE`). | |
| |`ours` |optional| | |
| The SHA1 of the commit that was used as "ours" for the Git merge that created the revision. + | |
| - For merge commits that are created by the link:#create-change[Create Change] REST endpoint | |
| "ours" is the SHA1 of the change's target branch (the branch that is specified as `branch` in the | |
| link:#change-input[ChangeInput]). + | |
| - For merge commits that are created by the link:#create-merge-patch-set-for-change[Create Merge | |
| Patch Set For Change] REST endpoint "ours" is the SHA1 of the change's target branch (if in the | |
| link:#merge-patch-set-input[MergePatchSetInput] `inherit_parent` is `false` and `base_change` is | |
| not set), the current parent of the change (if in the | |
| link:#merge-patch-set-input[MergePatchSetInput] `inherit_parent` is `true`) or the current | |
| revision of the base change (if in the link:#merge-patch-set-input[MergePatchSetInput] | |
| `inherit_parent` is `false` and `base_change` is set). + | |
| - For the link:#cherry-pick[Cherry Pick Revision] and the | |
| link:rest-api-projects.html#cherry-pick-commit[Cherry Pick Commit] REST endpoints "ours" is the | |
| SHA1 of the commit onto which the revision/commit is being cherry-picked (e.g. the head of the | |
| target branch or the revision of the base change). + | |
| - For the link:#rebase-change[Rebase Change], the link:#rebase-revision[Rebase Revision] and the | |
| link:#rebase-chain[Rebase Chain] REST endpoints "ours" is the SHA1 of the patch set that is being | |
| rebased. + | |
| Guaranteed to be set if `contains_conflicts` is `true`. If `contains_conflicts` is `false`, only | |
| set if the revision was created by Gerrit as a result of performing a Git merge. | |
| |`theirs` |optional| | |
| The SHA1 of the commit that was used as "theirs" for the Git merge that created the revision. + | |
| - For merge commits that are created by the link:#create-change[Create Change] and the | |
| link:#create-merge-patch-set-for-change[Create Merge Patch Set For Change] REST endpoints "theirs" | |
| is the SHA1 of the source branch (the branch that is specified as `source` in the | |
| link:#merge-input[MergeInput]). + | |
| - For the link:#cherry-pick[Cherry Pick Revision] and the | |
| link:rest-api-projects.html#cherry-pick-commit[Cherry Pick Commit] REST endpoints "theirs" is the | |
| SHA1 of the revision/commit that is being cherry-picked. + | |
| - For the link:#rebase-change[Rebase Change], the link:#rebase-revision[Rebase Revision] and the | |
| link:#rebase-chain[Rebase Chain] REST endpoints" theirs" is the SHA1 of the new base onto which the | |
| patch set is being rebased. + | |
| Guaranteed to be set if `contains_conflicts` is `true`. If `contains_conflicts` is `false`, only | |
| set if the revision was created by Gerrit as a result of performing a Git merge. | |
| |`merge_strategy` |optional| | |
| The merge strategy was used for the Git merge that created the revision. + | |
| Possible values: `resolve`, `recursive`, `simple-two-way-in-core`, `ours` and `theirs`. | |
| |`no_base_reason` |optional| | |
| Reason why `base` is not set. + | |
| Only set if `base` is not set. + | |
| Possible values are: + | |
| - `NO_COMMON_ANCESTOR`: The merged commits do not have a common ancestor. + | |
| - `COMPUTED_BASE`: The merged commits have multiple merge bases (happens for criss-cross-merges) | |
| and the base was computed. + | |
| - `ONE_SIDED_MERGE_STRATEGY`: A one sided merge strategy (e.g. `ours` or `theirs`) has been used | |
| and computing a base was not required for the merge. + | |
| - `NO_MERGE_PERFORMED`: The revision was not created by performing a Git merge operation. + | |
| - `HISTORIC_DATA_WITHOUT_BASE`: The revision has been created before Gerrit started to store the | |
| base for conflicts. | |
| |`contains_conflicts` || | |
| Whether any of the files in the revision has a conflict due to merging "ours" and "theirs". + | |
| If "true" at least one of the files in the revision has a conflict and contains Git conflict | |
| markers. The conflicts occurred while performing a merge between "ours" and "theirs". + | |
| If "false", and "ours" and "theirs" are present, merging "ours" and "theirs" didn't have any | |
| conflict. In this case the files in the revision may only contain Git conflict markers if they | |
| were already present in "ours" or "theirs". + | |
| If "false", and "ours" and "theirs" are not present, the revision was not created as a result of | |
| performing a Git merge and hence doesn't contain conflicts. | |
| |============================= | |
| [[delete-change-message-input]] | |
| === DeleteChangeMessageInput | |
| The `DeleteChangeMessageInput` entity contains the options for deleting a change message. | |
| [options="header",cols="1,^1,5"] | |
| |============================= | |
| |Field Name ||Description | |
| |`reason` |optional| | |
| The reason why the change message should be deleted. + | |
| If set, the change message will be replaced with | |
| "Change message removed by: `name`\nReason: `reason`", | |
| or just "Change message removed by: `name`." if not set. | |
| |============================= | |
| [[delete-comment-input]] | |
| === DeleteCommentInput | |
| The `DeleteCommentInput` entity contains the option for deleting a comment. | |
| [options="header",cols="1,^1,5"] | |
| |============================= | |
| |Field Name ||Description | |
| |`reason` |optional| | |
| The reason why the comment should be deleted. + | |
| If set, the comment's message will be replaced with | |
| "Comment removed by: `name`; Reason: `reason`", | |
| or just "Comment removed by: `name`." if not set. | |
| |============================= | |
| [[delete-reviewer-input]] | |
| === DeleteReviewerInput | |
| The `DeleteReviewerInput` entity contains options for the deletion of a | |
| reviewer. | |
| [options="header",cols="1,^1,5"] | |
| |============================= | |
| |Field Name ||Description | |
| |`notify` |optional| | |
| Notify handling that defines to whom email notifications should be sent | |
| after the reviewer is deleted. + | |
| Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. + | |
| If not set, the default is `ALL`. | |
| |`notify_details`|optional| | |
| Additional information about whom to notify about the update as a map | |
| of link:user-notify.html#recipient-types[recipient type] to | |
| link:#notify-info[NotifyInfo] entity. | |
| |============================= | |
| [[delete-vote-input]] | |
| === DeleteVoteInput | |
| The `DeleteVoteInput` entity contains options for the deletion of a | |
| vote. | |
| [options="header",cols="1,^1,5"] | |
| |============================= | |
| |Field Name ||Description | |
| |`label` |optional| | |
| The label for which the vote should be deleted. + | |
| If set, must match the label in the URL. | |
| |`notify` |optional| | |
| Notify handling that defines to whom email notifications should be sent | |
| after the vote is deleted. + | |
| Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. + | |
| If not set, the default is `ALL`. | |
| |`notify_details`|optional| | |
| Additional information about whom to notify about the update as a map | |
| of link:user-notify.html#recipient-types[recipient type] to | |
| link:#notify-info[NotifyInfo] entity. | |
| |`ignore_automatic_attention_set_rules`|optional| | |
| If set to true, ignore all automatic attention set rules described in the | |
| link:user-attention-set.html[attention set]. When not set, the default is false. | |
| |`reason` |optional| | |
| The reason why this vote is deleted. Will + | |
| go into the change message. | |
| |============================= | |
| [[description-input]] | |
| === DescriptionInput | |
| The `DescriptionInput` entity contains information for setting a description. | |
| [options="header",cols="1,6"] | |
| |=========================== | |
| |Field Name |Description | |
| |`description` |The description text. | |
| |=========================== | |
| [[diff-content]] | |
| === DiffContent | |
| The `DiffContent` entity contains information about the content differences | |
| in a file. | |
| [options="header",cols="1,^1,5"] | |
| |========================== | |
| |Field Name ||Description | |
| |`a` |optional|Content only in the file on side A (deleted in B). | |
| |`b` |optional|Content only in the file on side B (added in B). | |
| |`ab` |optional|Content in the file on both sides (unchanged). | |
| |`edit_a` |only present when the `intraline` parameter is set and the | |
| DiffContent is a replace, i.e. both `a` and `b` are present| | |
| Text sections deleted from side A as a | |
| link:#diff-intraline-info[DiffIntralineInfo] entity. | |
| |`edit_b` |only present when the `intraline` parameter is set and the | |
| DiffContent is a replace, i.e. both `a` and `b` are present| | |
| Text sections inserted in side B as a | |
| link:#diff-intraline-info[DiffIntralineInfo] entity. | |
| |`due_to_rebase`|not set if `false`|Indicates whether this entry was introduced by a | |
| rebase. | |
| |`due_to_move`|not set if `false`|Indicates whether this entry was introduced by a | |
| move operation. | |
| |`skip` |optional|count of lines skipped on both sides when the file is | |
| too large to include all common lines. | |
| |`common` |optional|Set to `true` if the region is common according | |
| to the requested ignore-whitespace parameter, but a and b contain | |
| differing amounts of whitespace. When present and true a and b are | |
| used instead of ab. | |
| |========================== | |
| [[diff-file-meta-info]] | |
| === DiffFileMetaInfo | |
| The `DiffFileMetaInfo` entity contains meta information about a file diff. | |
| [options="header",cols="1,^1,5"] | |
| |========================== | |
| |Field Name ||Description | |
| |`name` ||The name of the file. | |
| |`content_type`||The content type of the file. For the commit message and merge | |
| list the value is `text/x-gerrit-commit-message` and `text/x-gerrit-merge-list` | |
| respectively. For git links the value is `x-git/gitlink`. For symlinks the value | |
| is `x-git/symlink`. For regular files the value is the file mime type (e.g. | |
| `text/x-java`, `text/x-c++src`, etc...). | |
| |`lines` ||The total number of lines in the file. | |
| |`web_links` |optional| | |
| Links to the file in external sites as a list of | |
| link:rest-api-changes.html#web-link-info[WebLinkInfo] entries. | |
| |========================== | |
| [[diff-info]] | |
| === DiffInfo | |
| The `DiffInfo` entity contains information about the diff of a file | |
| in a revision. | |
| If the link:#weblinks-only[weblinks-only] parameter is specified, only | |
| the `web_links` field is set. | |
| [options="header",cols="1,^1,5"] | |
| |========================== | |
| |Field Name ||Description | |
| |`meta_a` |not present when the file is added| | |
| Meta information about the file on side A as a | |
| link:#diff-file-meta-info[DiffFileMetaInfo] entity. | |
| |`meta_b` |not present when the file is deleted| | |
| Meta information about the file on side B as a | |
| link:#diff-file-meta-info[DiffFileMetaInfo] entity. | |
| |`change_type` ||The type of change (`ADDED`, `MODIFIED`, `DELETED`, `RENAMED` | |
| `COPIED`, `REWRITE`). | |
| |`intraline_status`|only set when the `intraline` parameter was specified in the request| | |
| Intraline status (`OK`, `ERROR`, `TIMEOUT`). | |
| |`diff_header` ||A list of strings representing the patch set diff header. | |
| |`content` ||The content differences in the file as a list of | |
| link:#diff-content[DiffContent] entities. | |
| |`web_links` |optional| | |
| Links to the file diff in external sites as a list of | |
| link:rest-api-changes.html#diff-web-link-info[DiffWebLinkInfo] entries. | |
| |`edit_web_links` |optional| | |
| Links to edit the file in external sites as a list of | |
| link:rest-api-changes.html#web-link-info[WebLinkInfo] entries. | |
| |`binary` |not set if `false`|Whether the file is binary. | |
| |========================== | |
| [[diff-intraline-info]] | |
| === DiffIntralineInfo | |
| The `DiffIntralineInfo` entity contains information about intraline edits in a | |
| file. | |
| The information consists of a list of `<skip length, edit length>` pairs, where | |
| the skip length is the number of characters between the end of the previous edit | |
| and the start of this edit, and the edit length is the number of edited characters | |
| following the skip. The start of the edits is from the beginning of the related | |
| diff content lines. If the list is empty, the entire DiffContent should be considered | |
| as unedited. | |
| Note that the implied newline character at the end of each line is included in | |
| the length calculation, and thus it is possible for the edits to span newlines. | |
| [[diff-web-link-info]] | |
| === DiffWebLinkInfo | |
| The `DiffWebLinkInfo` entity extends link:#web-link-info[WebLinkInfo] and | |
| describes a link on a diff screen to an external site. | |
| [options="header",cols="1,^1,5"] | |
| |======================= | |
| |Field Name||Description | |
| |`name` ||See link:#web-link-info[WebLinkInfo] | |
| |`tooltip` |optional|See link:#web-link-info[WebLinkInfo] | |
| |`url` ||See link:#web-link-info[WebLinkInfo] | |
| |`image_url`|optional|See link:#web-link-info[WebLinkInfo] | |
| |show_on_side_by_side_diff_view|| | |
| Whether the web link should be shown on the side-by-side diff screen. | |
| |show_on_unified_diff_view|| | |
| Whether the web link should be shown on the unified diff screen. | |
| |======================= | |
| [[apply-provided-fix-input]] | |
| === ApplyProvidedFixInput | |
| The `ApplyProvidedFixInput` entity contains the fixes to be applied on a review. | |
| [[custom-keyed-values-input]] | |
| === CustomKeyedValuesInput | |
| The `CustomKeyedValuesInput` entity contains information about custom keyed values | |
| to add to, and/or remove from, a change. | |
| [options="header",cols="1,^1,5"] | |
| |======================= | |
| |Field Name||Description | |
| |`add` |optional|The map of custom keyed values to be added to the change. | |
| |`remove` |optional|The list of custom keys to be removed from the change. | |
| |======================= | |
| [options="header",cols="1,6"] | |
| |======================= | |
| |Field Name |Description | |
| |`fix_replacement_infos` |A list of <<fix-replacement-info,FixReplacementInfo>>. | |
| |======================= | |
| [[edit-file-info]] | |
| === EditFileInfo | |
| The `EditFileInfo` entity contains additional information | |
| of a file within a change edit. | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name ||Description | |
| |`web_links` |optional| | |
| Links to the diff info in external sites as a list of | |
| link:#web-link-info[WebLinkInfo] entities. | |
| |=========================== | |
| [[edit-info]] | |
| === EditInfo | |
| The `EditInfo` entity contains information about a change edit. | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name ||Description | |
| |`commit` ||The commit of change edit as | |
| link:#commit-info[CommitInfo] entity. | |
| |`base_patch_set_number`||The patch set number of the patch set the change edit is based on. | |
| |`base_revision` ||The revision of the patch set the change edit is based on. | |
| |`ref` ||The ref of the change edit. | |
| |`fetch` |optional| | |
| Information about how to fetch this patch set. The fetch information is | |
| provided as a map that maps the protocol name ("`git`", "`http`", | |
| "`ssh`") to link:#fetch-info[FetchInfo] entities. | |
| |`files` |optional| | |
| The files of the change edit as a map that maps the file names to | |
| link:#file-info[FileInfo] entities. | |
| |`contains_git_conflicts` |optional, not set if `false`| | |
| Whether the change edit contains conflicts. + | |
| If `true`, some of the file contents of the change edit contain git conflict | |
| markers to indicate the conflicts. + | |
| Only set if this edit info is returned in response to a request that | |
| link:#rebase-edit[rebases the change edit] and conflicts are allowed. | |
| |=========================== | |
| [[enabled-info]] | |
| === IsFlowsEnabledInfo | |
| The `IsFlowsEnabledInfo` entity contains information about whether flows is enabled. | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name ||Description | |
| |`enabled` ||A boolean indicating whether the feature is enabled. | |
| |=========================== | |
| [[evaluate-change-query-expression-result-info]] | |
| === EvaluateChangeQueryExpressionResultInfo | |
| The `EvaluateChangeQueryExpressionResultInfo` entity contains the result of | |
| evaluating a change query expression. | |
| [options="header",cols="1,^1,5"] | |
| |=============================== | |
| |Field Name ||Description | |
| |`status` ||Whether the change matches the change query expression. | |
| |`passing_atoms` ||List of passing leaf atoms (atoms that match the change). | |
| |`failing_atoms` ||List of failing leaf atoms (atoms that do not match the | |
| change). | |
| |`atom_explanation`|optional|Explanations for why atoms pass or fail. | |
| Explanations are only available for a few atoms, for most atoms no explanation | |
| is provided. Not set if none of the atoms has an explanation. | |
| |=============================== | |
| [[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-content-input]] | |
| === FileContentInput | |
| The `FileContentInput` entity contains information for creating/updating a file | |
| in a change edit. | |
| [options="header",cols="1,^1,5"] | |
| |============================== | |
| |Field Name ||Description | |
| |`binary_content` |optional|The file content as a base-64 encoded data URI. If | |
| no content is provided, an empty is created or if an existing file is updated | |
| the file content is removed so that the file becomes empty. The content must be | |
| a SHA1 if the file mode is `160000` (gitlink). | |
| |`file_mode` |optional|The file mode in octal format. Supported values are | |
| `100644` (regular file), `100755` (executable file), `120000` (symlink) and | |
| `160000` (gitlink). If unset, new files are created with file mode `100644` | |
| (regular file) and for existing files the existing file mode is kept. | |
| |============================== | |
| [[file-info]] | |
| === FileInfo | |
| The `FileInfo` entity contains information about a file in a patch set. | |
| [options="header",cols="1,^1,5"] | |
| |============================= | |
| |Field Name ||Description | |
| |`status` |optional| | |
| The status of the file ("`A`"=Added, "`D`"=Deleted, "`R`"=Renamed, | |
| "`C`"=Copied, "`W`"=Rewritten). + | |
| Not set if the file was Modified ("`M`"). | |
| |`binary` |not set if `false`|Whether the file is binary. | |
| |`old_path` |optional| | |
| The old file path. + | |
| Only set if the file was renamed or copied. | |
| |`lines_inserted`|optional| | |
| Number of inserted lines. + | |
| Not set for binary files or if no lines were inserted. + | |
| An empty last line is not included in the count and hence this number can | |
| differ by one from details provided in <<diff-info,DiffInfo>>. | |
| |`lines_deleted` |optional| | |
| Number of deleted lines. + | |
| Not set for binary files or if no lines were deleted. + | |
| An empty last line is not included in the count and hence this number can | |
| differ by one from details provided in <<diff-info,DiffInfo>>. | |
| |`size_delta` || | |
| Number of bytes by which the file size increased/decreased. | |
| |`size` || File size in bytes. | |
| |`old_mode` |optional|File mode in octal (e.g. 100644) at the old commit. | |
| The first three digits indicate the file type and the last three digits contain | |
| the file permission bits. For added files, this field will not be present. | |
| |`new_mode` |optional|File mode in octal (e.g. 100644) at the new commit. | |
| The first three digits indicate the file type and the last three digits contain | |
| the file permission bits. For deleted files, this field will not be present. | |
| |`old_sha` |optional|SHA-1 of the file content at the old commit. | |
| For added files, this field will not be present. | |
| |`new_sha` |optional|SHA-1 of the file content at the new commit. | |
| For deleted files, this field will not be present. | |
| |============================= | |
| [[fix-input]] | |
| === FixInput | |
| The `FixInput` entity contains options for fixing commits using the | |
| link:#fix-change[fix change] endpoint. | |
| [options="header",cols="1,6"] | |
| |========================== | |
| |Field Name |Description | |
| |`delete_patch_set_if_commit_missing`|If true, delete patch sets from the | |
| database if they refer to missing commit options. | |
| |`expect_merged_as` |If set, check that the change is | |
| merged into the destination branch as this exact SHA-1. If not, insert | |
| a new patch set referring to this commit. | |
| |========================== | |
| [[fix-suggestion-info]] | |
| === FixSuggestionInfo | |
| The `FixSuggestionInfo` entity represents a suggested fix. | |
| [options="header",cols="1,^1,5"] | |
| |========================== | |
| |Field Name ||Description | |
| |`fix_id` |generated, don't set|The <<fix-id,UUID>> of the suggested | |
| fix. It will be generated automatically and hence will be ignored if it's set | |
| for input objects. | |
| |`description` ||A description of the suggested fix. | |
| |`replacements` ||A list of <<fix-replacement-info,FixReplacementInfo>> | |
| entities indicating how the content of one or several files should be modified. | |
| Within a file, they should refer to non-overlapping regions. | |
| |========================== | |
| [[fix-replacement-info]] | |
| === FixReplacementInfo | |
| The `FixReplacementInfo` entity describes how the content of a file should be | |
| replaced by another content. | |
| [options="header",cols="1,6"] | |
| |========================== | |
| |Field Name |Description | |
| |`path` |The path of the file which should be modified. Any file in | |
| the repository may be modified. The commit message can be modified via the | |
| magic file `/COMMIT_MSG` though only the part below the generated header of | |
| that magic file can be modified. References to the header lines will result in | |
| errors when the fix is applied. | |
| |`range` |A <<comment-range,CommentRange>> indicating which content | |
| of the file should be replaced. Lines in the file are assumed to be separated | |
| by the line feed character. | |
| |`replacement` |The content which should be used instead of the current one. | |
| |========================== | |
| [[flow-info]] | |
| === FlowInfo | |
| The `FlowInfo` entity contains information about a flow. A flow is an automation | |
| rule on a change that triggers actions on the change when the flow conditions | |
| become satisfied. For example, a flow can be an automation rule that adds a | |
| reviewer to the change when the change has been verified by the CI. | |
| [options="header",cols="1,^1,5"] | |
| |============================== | |
| |Field Name ||Description | |
| |`uuid` ||The universally unique identifier that identifies the flow. | |
| |`owner` ||The owner of the flow as an | |
| link:rest-api-accounts.html#account-info[AccountInfo] entity. | |
| |`created` ||The link:rest-api.html#timestamp[timestamp] of when the flow | |
| was created. | |
| |`stages` ||The stages of this flow as a list of | |
| link:#flow-stage-info[FlowStageInfo] entities (sorted by execution order). | |
| |`last_evaluated` |optional|The link:rest-api.html#timestamp[timestamp] of when | |
| the flow was last evaluated. Not set if the flow has not been evaluated yet. | |
| |============================== | |
| [[flow-action-info]] | |
| === FlowActionInfo | |
| The `FlowActionInfo` entity contains information about a flow action. A flow | |
| action is an action that should be triggered when the condition of a | |
| link:#flow-expression-info[FlowExpressionInfo] becomes satisfied. | |
| [options="header",cols="1,6"] | |
| |========================= | |
| |Field Name |Description | |
| |`name` |The name of the action. Which actions are supported depends on | |
| the flow service implementation. | |
| |`parameters` |Parameters for the action as list of strings. Which parameters | |
| are supported and their format depends on the flow service implementation. | |
| |========================= | |
| [[flow-action-type]] | |
| === FlowActionTypeInfo | |
| The `FlowActionTypeInfo` entity describes an action that may be used in a flow. | |
| [options="header",cols="1,6"] | |
| |========================= | |
| |Field Name |Description | |
| |`name` |The name of the action. | |
| |========================= | |
| [[flow-expression-info]] | |
| === FlowExpressionInfo | |
| The `FlowExpressionInfo` entity contains information about a flow expression. A | |
| flow expression defines an action that should be triggered when a condition | |
| becomes satisfied. | |
| [options="header",cols="1,6"] | |
| |======================== | |
| |Field Name ||Description | |
| |`condition` ||The condition which must be satisfied for the action to be | |
| triggered. Can contain multiple conditions separated by comma. The syntax of the | |
| condition depends on the flow service implementation. | |
| |`action` |optional|The action that should be triggered when the condition is | |
| satisfied as a link:#flow-action-info[FlowActionInfo] entity. | |
| |======================== | |
| [[flow-input]] | |
| === FlowInput | |
| The `FlowInput` entity defines the properties for creating a new flow. | |
| [options="header",cols="1,6"] | |
| |================================ | |
| |Field Name |Description | |
| |`stage_expressions` |The expressions for the stages of the flow (sorted by | |
| execution order) as a list of link:#flow-expression-info[FlowExpressionInfo] | |
| entities. | |
| |================================ | |
| [[flow-stage-info]] | |
| === FlowStageInfo | |
| The `FlowStageInfo` entity contains information about a stage in a flow. A flow | |
| stage consists out of a flow expression that defines an action that should be | |
| triggered when a condition becomes satisfied and a status. | |
| [options="header",cols="1,^1,5"] | |
| |========================== | |
| |Field Name ||Description | |
| |`expression` ||The expression defining the condition and the action of | |
| this stage as a link:#flow-expression-info[FlowExpressionInfo] entity. | |
| |`state` ||The state for this stage. Can be `PENDING` (the condition of | |
| the stage is not satisfied yet or the action has not been executed yet), `DONE` | |
| (the condition of the stage is satisfied and the action has been executed), | |
| `FAILED` (the stage has a non-recoverable error, e.g. performing the action has | |
| failed) or `TERMINATED` (the stage has been terminated without having been | |
| executed, e.g. because a previous stage failed or because it wasn't done within | |
| a timeout). | |
| |`message` |optional|Optional message for the stage. | |
| |========================== | |
| [[git-person-info]] | |
| === GitPersonInfo | |
| The `GitPersonInfo` entity contains information about the | |
| author/committer of a commit. | |
| [options="header",cols="1,6"] | |
| |========================== | |
| |Field Name |Description | |
| |`name` |The name of the author/committer. | |
| |`email` |The email address of the author/committer. | |
| |`date` |The link:rest-api.html#timestamp[timestamp] of when | |
| this identity was constructed. | |
| |`tz` |The timezone offset from UTC of when this identity was | |
| constructed. | |
| |========================== | |
| [[group-base-info]] | |
| === GroupBaseInfo | |
| The `GroupBaseInfo` entity contains base information about the group. | |
| [options="header",cols="1,6"] | |
| |========================== | |
| |Field Name |Description | |
| |`id` |The UUID of the group. | |
| |`name` |The name of the group. | |
| |========================== | |
| [[hashtags-input]] | |
| === HashtagsInput | |
| The `HashtagsInput` entity contains information about hashtags to add to, | |
| and/or remove from, a change. | |
| [options="header",cols="1,^1,5"] | |
| |======================= | |
| |Field Name||Description | |
| |`add` |optional|The list of hashtags to be added to the change. | |
| |`remove` |optional|The list of hashtags to be removed from the change. | |
| |======================= | |
| [[included-in-info]] | |
| === IncludedInInfo | |
| The `IncludedInInfo` entity contains information about the branches a | |
| change was merged into and tags it was tagged with. The branch or tag | |
| must have 'refs/heads/' or 'refs/tags/' prefix respectively. | |
| Branch and tag lists are sorted in lexicographical order. | |
| [options="header",cols="1,^1,5"] | |
| |======================= | |
| |Field Name||Description | |
| |`branches`||The list of branches this change was merged into. | |
| Each branch is listed without the 'refs/head/' prefix. | |
| |`tags` ||The list of tags this change was tagged with. | |
| Each tag is listed without the 'refs/tags/' prefix. | |
| |`external`|optional|A map that maps a name to a list of external | |
| systems that include this change, e.g. a list of servers on which this | |
| change is deployed. | |
| |======================= | |
| [[label-info]] | |
| === LabelInfo | |
| The `LabelInfo` entity contains information about a label on a change, always | |
| corresponding to the current patch set. | |
| There are two options that control the contents of `LabelInfo`: | |
| link:#labels[`LABELS`] and link:#detailed-labels[`DETAILED_LABELS`]. | |
| * Using `LABELS` will skip the `all.permitted_voting_range` attribute. | |
| * Using `DETAILED_LABELS` will include the `all.permitted_voting_range` | |
| attribute. | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name ||Description | |
| |`optional` |not set if `false`| | |
| Whether the label is optional. Optional means the label may be set, but | |
| it's neither necessary for submission nor does it block submission if | |
| set. | |
| |`description` |optional| The description of the label. | |
| |`approved` |optional|One user who approved this label on the change | |
| (voted the maximum value) as an | |
| link:rest-api-accounts.html#account-info[AccountInfo] entity. | |
| |`rejected` |optional|One user who rejected this label on the change | |
| (voted the minimum value) as an | |
| link:rest-api-accounts.html#account-info[AccountInfo] entity. | |
| |`recommended` |optional|One user who recommended this label on the | |
| change (voted positively, but not the maximum value) as an | |
| link:rest-api-accounts.html#account-info[AccountInfo] entity. | |
| |`disliked` |optional|One user who disliked this label on the change | |
| (voted negatively, but not the minimum value) as an | |
| link:rest-api-accounts.html#account-info[AccountInfo] entity. | |
| |`blocking` |optional|If `true`, the label blocks submit operation. | |
| If not set, the default is false. | |
| |`value` |optional|The voting value of the user who | |
| recommended/disliked this label on the change if it is not | |
| "`+1`"/"`-1`". | |
| |`default_value`|optional|The default voting value for the label. | |
| This value may be outside the range specified in permitted_labels. | |
| |votes|optional|A list of integers containing the vote values applied to this | |
| label at the latest patchset. | |
| |`all` |optional|List of all approvals for this label as a list | |
| of link:#approval-info[ApprovalInfo] entities. Items in this list may | |
| not represent actual votes cast by users; if a user votes on any label, | |
| a corresponding ApprovalInfo will appear in this list for all labels. + | |
| The `permitted_voting_range` attribute is only set if the `DETAILED_LABELS` | |
| option is requested. | |
| |`values` |optional|A map of all values that are allowed for this | |
| label. The map maps the values ("`-2`", "`-1`", " `0`", "`+1`", "`+2`") | |
| to the value descriptions. | |
| |=========================== | |
| [[mergeable-info]] | |
| === MergeableInfo | |
| The `MergeableInfo` entity contains information about the mergeability of a | |
| change. | |
| [options="header",cols="1,^1,5"] | |
| |============================ | |
| |Field Name ||Description | |
| |`submit_type` || | |
| Submit type used for this change, can be `MERGE_IF_NECESSARY`, | |
| `FAST_FORWARD_ONLY`, `REBASE_IF_NECESSARY`, `REBASE_ALWAYS`, `MERGE_ALWAYS` or | |
| `CHERRY_PICK`. | |
| |`strategy` |optional| | |
| The strategy of the merge, can be `recursive`, `resolve`, | |
| `simple-two-way-in-core`, `ours` or `theirs`. | |
| |`mergeable` || | |
| `true` if this change is cleanly mergeable or already merged, `false` otherwise | |
| |`commit_merged` |optional| | |
| `true` if this change is already merged, `false` otherwise | |
| |`content_merged`|optional| | |
| `true` if the content of this change is already merged, `false` otherwise | |
| |`conflicts` |optional| | |
| A list of paths with conflicts | |
| |`mergeable_into`|optional| | |
| A list of other branch names where this change could merge cleanly | |
| |============================ | |
| [[merge-input]] | |
| === MergeInput | |
| The `MergeInput` entity contains information about the merge | |
| [options="header",cols="1,^1,5"] | |
| |============================== | |
| |Field Name ||Description | |
| |`source` || | |
| The source to merge from, e.g. a complete or abbreviated commit SHA-1, | |
| a complete reference name, a short reference name under `refs/heads`, `refs/tags`, | |
| or `refs/remotes` namespace, etc. | |
| |`source_branch` |optional| | |
| A branch from which `source` is reachable. If specified, | |
| `source` is checked for visibility and reachability against only this | |
| branch. This speeds up the operation, especially for large repos with | |
| many branches. | |
| |`strategy` |optional| | |
| The strategy of the merge, can be `recursive`, `resolve`, | |
| `simple-two-way-in-core`, `ours` or `theirs`, default will use project settings. | |
| |`allow_conflicts`|optional, defaults to false| | |
| If `true`, creating the merge succeeds also if there are conflicts. + | |
| If there are conflicts the file contents of the created change contain | |
| git conflict markers to indicate the conflicts. + | |
| Callers can find out whether there were conflicts by checking the | |
| `contains_git_conflicts` field in the link:#change-info[ChangeInfo]. + | |
| If there are conflicts the change is marked as work-in-progress. + | |
| This option is not supported for all merge strategies (e.g. it's | |
| supported for `recursive` and `resolve`, but not for | |
| `simple-two-way-in-core`). | |
| |============================== | |
| [[merge-patch-set-input]] | |
| === MergePatchSetInput | |
| The `MergePatchSetInput` entity contains information about updating a new | |
| change by creating a new merge commit. | |
| [options="header",cols="1,^1,5"] | |
| |================================== | |
| |Field Name ||Description | |
| |`subject` |optional| | |
| The new subject for the change, if not specified, will reuse the current patch | |
| set's subject | |
| |`inherit_parent` |optional, default to `false`| | |
| Use the current patch set's first parent as the merge tip when set to `true`. | |
| |`base_change` |optional| | |
| A link:#change-id[\{change-id\}] that identifies a change. When `inherit_parent` | |
| is `false`, the merge tip will be the current patch set of the `base_change` if | |
| it's set. Otherwise, the current branch tip of the destination branch will be used. | |
| |`merge` || | |
| The detail of the source commit for merge as a link:#merge-input[MergeInput] | |
| entity. | |
| |`author` |optional| | |
| The author of the commit to create. Must be an | |
| link:rest-api-accounts.html#account-input[AccountInput] entity with at least | |
| the `name` and `email` fields set. | |
| The caller needs "Forge Author" permission when using this field. | |
| This field does not affect the owner or the committer of the change, which will | |
| continue to use the identity of the caller. | |
| |`validation_options` |optional| | |
| Map with key-value pairs that are forwarded as options to the commit validation | |
| listeners (e.g. can be used to skip certain validations). Which validation | |
| options are supported depends on the installed commit validation listeners. | |
| Gerrit core doesn't support any validation options, but commit validation | |
| listeners that are implemented in plugins may. Please refer to the | |
| documentation of the installed plugins to learn whether they support validation | |
| options. Unknown validation options are silently ignored. | |
| |================================== | |
| [[move-input]] | |
| === MoveInput | |
| The `MoveInput` entity contains information for moving a change to a new branch. | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name ||Description | |
| |`destination_branch`||Destination branch | |
| |`message` |optional| | |
| A message to be posted in this change's comments | |
| |`keep_all_votes` |optional, defaults to false| | |
| By default, only veto votes that are blocking the change from submission are moved to | |
| the destination branch. Using this option is only allowed for administrators, | |
| because it can affect the submission behaviour of the change (depending on the label access | |
| configuration and submissions rules). | |
| |=========================== | |
| [[notify-info]] | |
| === NotifyInfo | |
| The `NotifyInfo` entity contains detailed information about who should | |
| be notified about an update. These notifications are sent out even if a | |
| `notify` option in the request input disables normal notifications. | |
| `NotifyInfo` entities are normally contained in a `notify_details` map | |
| in the request input where the key is the | |
| link:user-notify.html#recipient-types[recipient type]. | |
| [options="header",cols="1,^1,5"] | |
| |======================= | |
| |Field Name||Description | |
| |`accounts`|optional| | |
| A list of link:rest-api-accounts.html#account-id[account IDs] that | |
| identify the accounts that should be should be notified. | |
| |======================= | |
| [[parent-info]] | |
| === ParentInfo | |
| The `ParentInfo` entity contains information about the parent commit of a | |
| patch-set. | |
| [options="header",cols="1,^1,5"] | |
| |======================= | |
| |Field Name||Description | |
| |`branch_name` |optional|Name of the target branch into which the parent commit | |
| is merged. | |
| |`commit_id` |optional|The commit SHA-1 of the parent commit, or null if the | |
| current commit is root. | |
| |`is_merged_in_target_branch` |optional, default to false| Set to true if the | |
| parent commit is merged into the target branch. | |
| |`change_id` |optional| If the parent commit is a patch-set of another gerrit | |
| change, this field will hold the change ID of the parent change. Otherwise, | |
| will be null. | |
| |`change_number` |optional|If the parent commit is a patch-set of another gerrit | |
| change, this field will hold the change number of the parent change. Otherwise, | |
| will be null. | |
| |`patch_set_number` |optional|If the parent commit is a patch-set of another gerrit | |
| change, this field will hold the patch-set number of the parent change. Otherwise, | |
| will be null. | |
| |`change_status` |optional|If the parent commit is a patch-set of another gerrit | |
| change, this field will hold the change status of the parent change. Otherwise, | |
| will be null. | |
| |======================= | |
| [[private-input]] | |
| === PrivateInput | |
| The `PrivateInput` entity contains information for changing the private | |
| flag on a change. | |
| [options="header",cols="1,^1,5"] | |
| |======================= | |
| |Field Name||Description | |
| |`message` |optional|Message describing why the private flag was changed. | |
| |======================= | |
| [[problem-info]] | |
| === ProblemInfo | |
| The `ProblemInfo` entity contains a description of a potential consistency problem | |
| with a change. These are not related to the code review process, but rather | |
| indicate some inconsistency in Gerrit's database or repository metadata related | |
| to the enclosing change. | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name||Description | |
| |`message` ||Plaintext message describing the problem with the change. | |
| |`status` |optional| | |
| The status of fixing the problem (`FIXED`, `FIX_FAILED`). Only set if a | |
| fix was attempted. | |
| |`outcome` |optional| | |
| If `status` is set, an additional plaintext message describing the | |
| outcome of the fix. | |
| |=========================== | |
| [[publish-change-edit-input]] | |
| === PublishChangeEditInput | |
| The `PublishChangeEditInput` entity contains options for the publishing of | |
| change edit. | |
| [options="header",cols="1,^1,5"] | |
| |============================= | |
| |Field Name ||Description | |
| |`notify` |optional| | |
| Notify handling that defines to whom email notifications should be sent | |
| after the change edit is published. + | |
| Allowed values are `NONE` and `ALL`. + | |
| If not set, the default is `ALL`. | |
| |`notify_details`|optional| | |
| Additional information about whom to notify about the update as a map | |
| of link:user-notify.html#recipient-types[recipient type] to | |
| link:#notify-info[NotifyInfo] entity. | |
| |============================= | |
| [[pure-revert-info]] | |
| === PureRevertInfo | |
| The `PureRevertInfo` entity describes the result of a pure revert check. | |
| [options="header",cols="1,6"] | |
| |====================== | |
| |Field Name |Description | |
| |`is_pure_revert` |Outcome of the check as boolean. | |
| |====================== | |
| [[push-certificate-info]] | |
| === PushCertificateInfo | |
| The `PushCertificateInfo` entity contains information about a push | |
| certificate provided when the user pushed for review with `git push | |
| --signed HEAD:refs/for/<branch>`. Only used when signed push is | |
| link:config-gerrit.html#receive.enableSignedPush[enabled] on the server. | |
| [options="header",cols="1,6"] | |
| |=========================== | |
| |Field Name|Description | |
| |`certificate`|Signed certificate payload and GPG signature block. | |
| |`key` | | |
| Information about the key that signed the push, along with any problems | |
| found while checking the signature or the key itself, as a | |
| link:rest-api-accounts.html#gpg-key-info[GpgKeyInfo] entity. | |
| |=========================== | |
| [[range-info]] | |
| === RangeInfo | |
| The `RangeInfo` entity stores the coordinates of a range. | |
| [options="header",cols="1,6"] | |
| |=========================== | |
| |Field Name | Description | |
| |`start` | First index. | |
| |`end` | Last index. | |
| |=========================== | |
| [[rebase-change-edit-input]] | |
| === RebaseChangeEditInput | |
| The `RebaseChangeEditInput` entity contains information for rebasing a change edit. | |
| [options="header",cols="1,^1,5"] | |
| |==================================== | |
| |Field Name ||Description | |
| |`allow_conflicts` |optional, defaults to false| | |
| If `true`, the rebase also succeeds if there are conflicts. + | |
| If there are conflicts the file contents of the rebased patch set contain | |
| git conflict markers to indicate the conflicts. + | |
| Callers can find out whether there were conflicts by checking the | |
| `contains_git_conflicts` field in the returned link:#edit-info[EditInfo]. | |
| |==================================== | |
| [[rebase-input]] | |
| === RebaseInput | |
| The `RebaseInput` entity contains information for changing parent when rebasing. | |
| [options="header",cols="1,^1,5"] | |
| |==================================== | |
| |Field Name ||Description | |
| |`base` |optional| | |
| The new parent revision. This can be a ref or a SHA-1 to a concrete patchset. + | |
| Alternatively, a change number can be specified, in which case the current | |
| patch set is inferred. + | |
| Empty string is used for rebasing directly on top of the target branch, | |
| which effectively breaks dependency towards a parent change. | |
| |`strategy` |optional| | |
| The strategy of the merge, can be `recursive`, `resolve`, | |
| `simple-two-way-in-core`, `ours` or `theirs`, default will use project settings. | |
| |`allow_conflicts` |optional, defaults to false| | |
| If `true`, the rebase also succeeds if there are conflicts. + | |
| If there are conflicts the file contents of the rebased patch set contain | |
| git conflict markers to indicate the conflicts. + | |
| Callers can find out whether there were conflicts by checking the | |
| `contains_git_conflicts` field in the returned link:#change-info[ChangeInfo]. + | |
| If there are conflicts the change is marked as work-in-progress. + | |
| Cannot be combined with the `on_behalf_of_uploader` option. | |
| |`on_behalf_of_uploader`|optional, defaults to false| | |
| If `true`, the rebase is done on behalf of the uploader. + | |
| This means the uploader of the current patch set will also be the uploader of | |
| the rebased patch set. The calling user will be recorded as the real user. + | |
| Rebasing on behalf of the uploader is only supported for trivial rebases. | |
| This means this option cannot be combined with the `allow_conflicts` option. + | |
| In addition, rebasing on behalf of the uploader is only supported for the | |
| current patch set of a change. + | |
| If the caller is the uploader this flag is ignored and a normal rebase is done. | |
| |`committer_email`|optional| | |
| Rebase is committed using this email address. Only the registered emails | |
| of the calling user or uploader (when `on_behalf_of_uploader` is `true`) are | |
| considered valid. This option is not supported when rebasing a chain. | |
| |`validation_options` |optional| | |
| Map with key-value pairs that are forwarded as options to the commit validation | |
| listeners (e.g. can be used to skip certain validations). Which validation | |
| options are supported depends on the installed commit validation listeners. | |
| Gerrit core doesn't support any validation options, but commit validation | |
| listeners that are implemented in plugins may. Please refer to the | |
| documentation of the installed plugins to learn whether they support validation | |
| options. Unknown validation options are silently ignored. | |
| |==================================== | |
| [[rebase-chain-info]] | |
| === RebaseChainInfo | |
| The `RebaseChainInfo` entity contains information about a chain of changes | |
| that were rebased. | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name ||Description | |
| |`rebased_changes` ||List of the unsubmitted ancestors, as link:#change-info[ChangeInfo] | |
| entities. Includes both rebased changes, and previously up-to-date ancestors. The list is ordered by | |
| ancestry, where the oldest ancestor is the first. | |
| |`contains_git_conflicts` ||Whether any of the rebased changes has conflicts | |
| due to rebasing. | |
| |=========================== | |
| [[related-change-and-commit-info]] | |
| === RelatedChangeAndCommitInfo | |
| The `RelatedChangeAndCommitInfo` entity contains information about | |
| a related change and commit. | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name ||Description | |
| |`project` ||The project of the change or commit. | |
| |`change_id` |optional|The Change-Id of the change. | |
| |`commit` ||The commit as a | |
| link:#commit-info[CommitInfo] entity. | |
| |`_change_number` |optional|The change number. | |
| |`_revision_number` |optional|The revision number. | |
| |`_current_revision_number`|optional|The current revision number. | |
| |`status` |optional|The status of the change. The status of | |
| the change is one of (`NEW`, `MERGED`, `ABANDONED`). | |
| |`submittable` |optional|Boolean indicating whether the change is | |
| submittable. + | |
| Only populated if link:#get-related-changes-submittable[requested]. | |
| |`work_in_progress` |optional, not set if `false`|Boolean indicating whether the change is | |
| work in progress. | |
| |=========================== | |
| [[related-changes-info]] | |
| === RelatedChangesInfo | |
| The `RelatedChangesInfo` entity contains information about related | |
| changes. | |
| [options="header",cols="1,6"] | |
| |=========================== | |
| |Field Name |Description | |
| |`changes` |A list of | |
| link:#related-change-and-commit-info[RelatedChangeAndCommitInfo] entities | |
| describing the related changes. Sorted by git commit order, newest to | |
| oldest. Empty if there are no related changes. | |
| |=========================== | |
| [[requirement]] | |
| === Requirement | |
| The `Requirement` entity contains information about a requirement relative to a change. | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name | |Description | |
| |`status` | | Status of the requirement. Can be either `OK`, `NOT_READY` or `RULE_ERROR`. | |
| |`fallback_text` | | A human readable reason | |
| |`type` | | | |
| Alphanumerical (plus hyphens or underscores) string to identify what the requirement is and why it | |
| was triggered. Can be seen as a class: requirements sharing the same type were created for a similar | |
| reason, and the data structure will follow one set of rules. | |
| |=========================== | |
| [[restore-input]] | |
| === RestoreInput | |
| The `RestoreInput` entity contains information for restoring a change. | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name ||Description | |
| |`message` |optional| | |
| Message to be added as review comment to the change when restoring the | |
| change. | |
| |=========================== | |
| [[revert-input]] | |
| === RevertInput | |
| The `RevertInput` entity contains information for reverting a change. | |
| [options="header",cols="1,^1,5"] | |
| |================================= | |
| |Field Name ||Description | |
| |`message` |optional| | |
| Commit message of the revert commit. If not specified, a default commit message is set. | |
| |`notify` |optional| | |
| Notify handling that defines to whom email notifications should be sent | |
| for reverting the change. + | |
| Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. + | |
| If not set, the default is `ALL`. | |
| |`notify_details` |optional| | |
| Additional information about whom to notify about the revert as a map | |
| of link:user-notify.html#recipient-types[recipient type] to | |
| link:#notify-info[NotifyInfo] entity. | |
| |`topic` |optional| | |
| Name of the topic for the revert change. If not set, the default for Revert | |
| endpoint is the topic of the change being reverted, and the default for the | |
| RevertSubmission endpoint is `revert-{submission_id}-{timestamp.now}`. | |
| Topic can't contain quotation marks. | |
| |`work_in_progress` |optional| | |
| When present, change is marked as Work In Progress. The `notify` input is | |
| used if it's present, otherwise it will be overridden to `NONE`. + | |
| Notifications for the reverted change will only sent once the result change is | |
| no longer WIP. + | |
| If not set, the default is false. | |
| |`validation_options`|optional| | |
| Map with key-value pairs that are forwarded as options to the commit validation | |
| listeners (e.g. can be used to skip certain validations). Which validation | |
| options are supported depends on the installed commit validation listeners. | |
| Gerrit core doesn't support any validation options, but commit validation | |
| listeners that are implemented in plugins may. Please refer to the | |
| documentation of the installed plugins to learn whether they support validation | |
| options. Unknown validation options are silently ignored. | |
| |================================= | |
| [[revert-submission-info]] | |
| === RevertSubmissionInfo | |
| The `RevertSubmissionInfo` entity describes the revert changes. | |
| [options="header",cols="1,6"] | |
| |============================== | |
| |Field Name | Description | |
| |`revert_changes` | | |
| A list of link:#change-info[ChangeInfo] that describes the revert changes. Each | |
| entity in that list is a revert change that was created in that revert | |
| submission. | |
| |============================== | |
| [[review-info]] | |
| === ReviewInfo | |
| The `ReviewInfo` entity contains information about a review. | |
| [options="header",cols="1,6"] | |
| |=========================== | |
| |Field Name |Description | |
| |`labels` | | |
| The labels of the review as a map that maps the label names to the | |
| voting values. | |
| |=========================== | |
| [[review-update-info]] | |
| === ReviewerUpdateInfo | |
| The `ReviewerUpdateInfo` entity contains information about updates to | |
| change's reviewers set. | |
| [options="header",cols="1,6"] | |
| |=========================== | |
| |Field Name |Description | |
| |`updated`| | |
| Timestamp of the update. | |
| |`updated_by`| | |
| The account which modified state of the reviewer in question as | |
| link:rest-api-accounts.html#account-info[AccountInfo] entity. | |
| |`real_updated_by`| | |
| The account which actually modified the state of the reviewer in question as | |
| link:rest-api-accounts.html#account-info[AccountInfo] entity. This will be | |
| different from `updated_by` in case of impersonation. For example, if Alice | |
| impersonates Bob and changes the state of a reviewer, `updated_by` will be | |
| Bob and `real_updated_by` will be Alice. | |
| |`reviewer`| | |
| The reviewer added or removed from the change as an | |
| link:rest-api-accounts.html#account-info[AccountInfo] entity. For | |
| reviewers by email the `AccountInfo` doesn't contain an account ID but | |
| only the email and optionally a name. | |
| |`state`| | |
| The reviewer state, one of `REVIEWER`, `CC` or `REMOVED`. | |
| |=========================== | |
| [[review-input]] | |
| === ReviewInput | |
| The `ReviewInput` entity contains information for adding a review to a | |
| revision. | |
| [options="header",cols="1,^1,5"] | |
| |============================ | |
| |Field Name ||Description | |
| |`message` |optional| | |
| The message to be added as review comment. | |
| |`tag` |optional| | |
| Apply this tag to the review comment message, votes, and inline | |
| comments. Tags with an 'autogenerated:' prefix may be used by CI or other | |
| automated systems to distinguish them from human reviews. If another | |
| message was posted on a newer patchset, but with the same tag, then the older | |
| message will be hidden in the UI. Suffixes starting with `~` are not considered, | |
| so `autogenerated:my-ci-system~trigger` and `autogenerated:my-ci-system~result` | |
| will be considered being the same tag with regards to the hiding rule. | |
| |`labels` |optional| | |
| The votes that should be added to the revision as a map that maps the | |
| label names to the voting values. | |
| |`comments` |optional| | |
| The comments that should be added as a map that maps a file path to a | |
| list of link:#comment-input[CommentInput] entities. | |
| |`drafts` |optional| | |
| Draft handling that defines how draft comments are handled that are | |
| already in the database but that were not also described in this | |
| input. + | |
| Allowed values are `PUBLISH`, `PUBLISH_ALL_REVISIONS` and `KEEP`. All values | |
| except `PUBLISH_ALL_REVISIONS` operate only on drafts for a single revision. + | |
| Only `KEEP` is allowed when used in conjunction with `on_behalf_of`. + | |
| If not set, the default is `KEEP`. If `on_behalf_of` is set, then no other value | |
| besides `KEEP` is allowed. | |
| |`draft_ids_to_publish` |optional| | |
| List of draft IDs to be published. The draft IDs should belong to the current | |
| user and be valid. If `drafts` is set to `PUBLISH`, then draft IDs should | |
| contain drafts for the same revision that is requested for review. If `drafts` | |
| is set to `KEEP`, then `draft_ids_to_publish` will be ignored and no draft | |
| comments will be published. + | |
| If not set, the default is to publish all drafts according to the `drafts` field. | |
| |`notify` |optional| | |
| Notify handling that defines to whom email notifications should be sent | |
| after the review is stored. + | |
| Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. + | |
| If not set, the default is `ALL`. | |
| |`notify_details` |optional| | |
| Additional information about whom to notify about the update as a map | |
| of link:user-notify.html#recipient-types[recipient type] to | |
| link:#notify-info[NotifyInfo] entity. | |
| |`omit_duplicate_comments` |optional| | |
| If `true`, comments with the same content at the same place will be omitted. | |
| |`on_behalf_of` |optional| | |
| link:rest-api-accounts.html#account-id[\{account-id\}] the review | |
| should be posted on behalf of. To use this option the caller must | |
| have been granted `labelAs-NAME` permission for all keys of labels. | |
| |`reviewers` |optional| | |
| A list of link:rest-api-changes.html#reviewer-input[ReviewerInput] | |
| representing reviewers that should be added/removed to/from the change. | |
| |`ready` |optional| | |
| If true, and if the change is work in progress, then start review. | |
| It is an error for both `ready` and `work_in_progress` to be true. | |
| |`work_in_progress` |optional| | |
| If true, mark the change as work in progress. It is an error for both | |
| `ready` and `work_in_progress` to be true. | |
| |`add_to_attention_set` |optional| | |
| list of link:#attention-set-input[AttentionSetInput] entities to add | |
| to the link:user-attention-set.html[attention set]. Users that are not reviewers, | |
| ccs, owner, or uploader are silently ignored. | |
| |`remove_from_attention_set` |optional| | |
| list of link:#attention-set-input[AttentionSetInput] entities to remove | |
| from the link:user-attention-set.html[attention set]. | |
| |`ignore_automatic_attention_set_rules`|optional| | |
| If set to true, ignore all automatic attention set rules described in the | |
| link:user-attention-set.html[attention set]. Updates in add_to_attention_set | |
| and remove_from_attention_set are not ignored. | |
| |`response_format_options` |optional| | |
| List of link:#query-options[query options] to format the response. | |
| |============================ | |
| [[review-result]] | |
| === ReviewResult | |
| The `ReviewResult` entity contains information regarding the updates | |
| that were made to a review. | |
| [options="header",cols="1,^1,5"] | |
| |============================ | |
| |Field Name ||Description | |
| |`labels` |optional| | |
| Map of labels to values after the review was posted. Null if any reviewer | |
| additions were rejected. | |
| |`reviewers` |optional| | |
| Map of account or group identifier to | |
| link:rest-api-changes.html#reviewer-result[ReviewerResult] | |
| representing the outcome of adding/removing a reviewer. | |
| Absent if no reviewer additions were requested. | |
| |`ready` |optional| | |
| If true, the change was moved from WIP to ready for review as a result of this | |
| action. Not set if false. | |
| |`error` |optional| | |
| Error message for non-200 responses. | |
| |`change_info` || | |
| Post-update change information. | |
| |============================ | |
| [[reviewer-info]] | |
| === ReviewerInfo | |
| The `ReviewerInfo` entity contains information about a reviewer and its | |
| votes on a change. | |
| `ReviewerInfo` has the same fields as | |
| link:rest-api-accounts.html#account-info[AccountInfo] and includes | |
| link:#detailed-accounts[detailed account information]. | |
| In addition `ReviewerInfo` has the following fields: | |
| [options="header",cols="1,6"] | |
| |========================== | |
| |Field Name |Description | |
| |`approvals` | | |
| The approvals of the reviewer as a map that maps the label names to the | |
| approval values ("`-2`", "`-1`", "`0`", "`+1`", "`+2`"). | |
| |`_account_id` | | |
| This field is inherited from `AccountInfo` but is optional here if an | |
| unregistered reviewer was added by email. See | |
| link:rest-api-changes.html#add-reviewer[add-reviewer] for details. | |
| |========================== | |
| [[reviewer-input]] | |
| === ReviewerInput | |
| The `ReviewerInput` entity contains information for adding or removing | |
| reviewers to/from the change. | |
| [options="header",cols="1,^1,5"] | |
| |============================= | |
| |Field Name ||Description | |
| |`reviewer` || | |
| The link:rest-api-accounts.html#account-id[ID] of one account that | |
| should be added/removed as reviewer or the link:rest-api-groups.html#group-id[ | |
| ID] of one internal group for which all members should be added as reviewers. + | |
| If an ID identifies both an account and a group, only the account is | |
| added as reviewer to the change. | |
| External groups, such as LDAP groups, will be silently omitted from a | |
| link:#set-review[set-review] or | |
| link:rest-api-changes.html#add-reviewer[add-reviewer] call. A group can only be | |
| specified for adding reviewers, not for removing them. | |
| |`state` |optional| | |
| Add reviewer in this state. Possible reviewer states are `REVIEWER`, | |
| `CC` and `REMOVED`. If not given, defaults to `REVIEWER`. | |
| |`confirmed` |optional| | |
| Whether adding the reviewer is confirmed. + | |
| The Gerrit server may be configured to | |
| link:config-gerrit.html#addreviewer.maxWithoutConfirmation[require a | |
| confirmation] when adding a group as reviewer that has many members. | |
| |`on_behalf_of` |optional| | |
| link:rest-api-accounts.html#account-id[\{account-id\}] the reviewer | |
| should be added on behalf of. To use this option the caller must | |
| have been granted `RUN_AS` permission. + | |
| If not set, the default is the caller. | |
| |`notify` |optional| | |
| Notify handling that defines to whom email notifications should be sent | |
| after the reviewer is added. + | |
| Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. + | |
| If not set, the default is `ALL`. | |
| |`notify_details`|optional| | |
| Additional information about whom to notify about the update as a map | |
| of link:user-notify.html#recipient-types[recipient type] to | |
| link:#notify-info[NotifyInfo] entity. | |
| |============================= | |
| [[reviewer-result]] | |
| === ReviewerResult | |
| The `ReviewerResult` entity describes the result of modifying reviewers of | |
| a change. | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name ||Description | |
| |`input` || | |
| Value of the `reviewer` field from link:#reviewer-input[ReviewerInput] | |
| set while adding the reviewer. | |
| |`reviewers` |optional| | |
| The newly added reviewers as a list of link:#reviewer-info[ | |
| ReviewerInfo] entities. | |
| |`ccs` |optional| | |
| The newly CCed accounts as a list of | |
| link:rest-api-accounts.html#account-info[AccountInfo] entities. This field will | |
| only appear if the requested `state` for the reviewer was `CC`. | |
| |`removed` |optional| | |
| The newly removed accounts as a list of | |
| link:rest-api-accounts.html#account-info[AccountInfo] entities. | |
| This field will only appear if the requested `state` for the reviewer was | |
| `REMOVED`. | |
| |`error` |optional| | |
| Error message explaining why the reviewer could not be added. + | |
| If a group was specified in the input and an error is returned, it | |
| means that none of the members were added as reviewer. | |
| |`confirm` |`false` if not set| | |
| Whether adding the reviewer requires confirmation. | |
| |=========================== | |
| [[revision-info]] | |
| === RevisionInfo | |
| The `RevisionInfo` entity contains information about a patch set. | |
| Not all fields are returned by default. Additional fields can | |
| be obtained by adding `o` parameters as described in | |
| link:#list-changes[Query Changes]. | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name ||Description | |
| |`kind` ||The change kind. Valid values are `REWORK`, `TRIVIAL_REBASE`, | |
| `TRIVIAL_REBASE_WITH_MESSAGE_UPDATE`, `MERGE_FIRST_PARENT_UPDATE`, | |
| `NO_CODE_CHANGE`, and `NO_CHANGE`. | |
| |`_number` ||The patch set number, or `edit` if the patch set is an edit. | |
| |`created` || | |
| The link:rest-api.html#timestamp[timestamp] of when the patch set was | |
| created. | |
| |`uploader` || | |
| The uploader of the patch set as an | |
| link:rest-api-accounts.html#account-info[AccountInfo] entity. | |
| |`real_uploader`|optional| | |
| The real uploader of the patch set as an | |
| link:rest-api-accounts.html#account-info[AccountInfo] entity. + | |
| Only set if the upload was done on behalf of another user. | |
| |`ref` ||The Git reference for the patch set. | |
| |`fetch` || | |
| Information about how to fetch this patch set. The fetch information is | |
| provided as a map that maps the protocol name ("`git`", "`http`", | |
| "`ssh`") to link:#fetch-info[FetchInfo] entities. This information is | |
| only included if a plugin implementing the | |
| link:intro-project-owner.html#download-commands[download commands] | |
| interface is installed. | |
| |`commit` |optional|The commit of the patch set as | |
| link:#commit-info[CommitInfo] entity. | |
| |`parents_data` |optional| | |
| The parent commits of this patch-set commit as a list of | |
| link:#parent-info[ParentInfo] entities. In each parent, we include the target | |
| branch name if the parent is a merged commit in the target branch. Otherwise, | |
| we include the change and patch-set numbers of the parent change. + | |
| Only set if the `PARENTS` option is set. | |
| |`branch` | optional|The name of the target branch that this revision is | |
| set to be merged into. + | |
| Note that if the change is moved with the link:#move-change[Move Change] | |
| endpoint, this field can be different for different patchsets. For example, | |
| if the change is moved and a new patchset is uploaded afterwards, the | |
| link:#revision-info[RevisionInfo] of the previous patchset will contain the old | |
| `branch`, but the newer patchset will contain the new `branch`. | |
| |`files` |optional| | |
| The files of the patch set as a map that maps the file names to | |
| link:#file-info[FileInfo] entities. Only set if | |
| link:#current-files[CURRENT_FILES] or link:#all-files[ALL_FILES] | |
| option is requested. | |
| |`actions` |optional| | |
| Actions the caller might be able to perform on this revision. The | |
| information is a map of view name to link:#action-info[ActionInfo] | |
| entities. | |
| |`reviewed` |optional| | |
| Indicates whether the caller is authenticated and has commented on the | |
| current revision. Only set if link:#reviewed[REVIEWED] option is requested. | |
| |`commit_with_footers` |optional| | |
| If the link:#commit-footers[COMMIT_FOOTERS] option is requested and | |
| this is the current patch set, contains the full commit message with | |
| Gerrit-specific commit footers, as if this revision were submitted | |
| using the link:project-configuration.html#cherry_pick[Cherry Pick] | |
| submit type. | |
| |`push_certificate` |optional| | |
| If the link:#push-certificates[PUSH_CERTIFICATES] option is requested, | |
| contains the push certificate provided by the user when uploading this | |
| patch set as a link:#push-certificate-info[PushCertificateInfo] entity. | |
| This field is always set if the option is requested; if no push | |
| certificate was provided, it is set to an empty object. | |
| |`description` |optional| | |
| The description of this patchset, as displayed in the patchset | |
| selector menu. May be null if no description is set. | |
| |`conflicts` |optional| | |
| Information about conflicts in this revision as a | |
| link:#conflicts-info[ConflictsInfo] entity. + | |
| Only set for revisions that were created by Gerrit as a result of | |
| performing a Git merge (merge commits that were created by the | |
| link:#create-change[Create Change] and the | |
| link:#create-merge-patch-set-for-change[Create Merge Patch Set For | |
| Change] REST endpoints and revisions created by the | |
| link:#cherry-pick[Cherry Pick Revision], | |
| link:rest-api-projects.html#cherry-pick-commit[Cherry Pick Commit], | |
| link:#rebase-change[Rebase Change] or link:#rebase-chain[Rebase Chain] | |
| REST endpoints). + | |
| Absence of this field, doesn't guarantee absence of conflicts. It can | |
| also be missing for revisions with conflicts that were created before | |
| the field was introduced or where the merge was performed locally (not | |
| by Gerrit operation). | |
| |=========================== | |
| [[rule-input]] | |
| === RuleInput | |
| The `RuleInput` entity contains information to test a Prolog rule. | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name ||Description | |
| |`rule`|| | |
| Prolog code to execute instead of the code in `refs/meta/config`. | |
| |`filters`|`RUN` if not set| | |
| When `RUN` filter rules in the parent projects are called to | |
| post-process the results of the project specific rule. This | |
| behavior matches how the rule will execute if installed. + | |
| If `SKIP` the parent filters are not called, allowing the test | |
| to return results from the input rule. | |
| |=========================== | |
| [[submit-input]] | |
| === SubmitInput | |
| The `SubmitInput` entity contains information for submitting a change. | |
| [options="header",cols="1,^1,5"] | |
| |============================= | |
| |Field Name ||Description | |
| |`on_behalf_of` |optional| | |
| If set, submit the change on behalf of the given user. The value may take any | |
| format link:rest-api-accounts.html#account-id[accepted by the accounts REST | |
| API]. Using this option requires | |
| link:access-control.html#category_submit_on_behalf_of[Submit (On Behalf Of)] | |
| permission on the branch. | |
| |`notify` |optional| | |
| Notify handling that defines to whom email notifications should be sent after | |
| the change is submitted. + | |
| Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. + | |
| If not set, the default is `ALL`. + | |
| Ignored if a post approval diff is present (i.e. if the change is submitted | |
| with copied approvals), because in this case everyone should be informed | |
| about the non-reviewed diff which has been applied after the change has been | |
| approved so that they can take action if the post approval diff looks | |
| unexpected. In other words if a post approval diff is present `ALL` is | |
| enforced. | |
| |`notify_details`|optional| | |
| Additional information about whom to notify about the update as a map | |
| of link:user-notify.html#recipient-types[recipient type] to | |
| link:#notify-info[NotifyInfo] entity. | |
| |============================= | |
| [[submit-record]] | |
| === SubmitRecord | |
| The `SubmitRecord` entity describes results from a submit_rule. | |
| Fields in this entity roughly correspond to the fields set by `LABELS` | |
| in link:#label-info[LabelInfo]. | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name ||Description | |
| |`status`|| | |
| `OK`, the change can be submitted. + | |
| `NOT_READY`, additional labels are required before submit. + | |
| `CLOSED`, closed changes cannot be submitted. + | |
| `RULE_ERROR`, rule code failed with an error. | |
| |`ok`|optional| | |
| Map of labels that are approved; an | |
| link:rest-api-accounts.html#account-info[AccountInfo] identifies the | |
| voter chosen by the rule. | |
| |`reject`|optional| | |
| Map of labels that are preventing submit; | |
| link:rest-api-accounts.html#account-info[AccountInfo] identifies voter. | |
| |`need`|optional| | |
| Map of labels that need to be given to submit. The value is | |
| currently an empty object. | |
| |`may`|optional| | |
| Map of labels that can be used, but do not affect submit. | |
| link:rest-api-accounts.html#account-info[AccountInfo] identifies voter, | |
| if the label has been applied. | |
| |`impossible`|optional| | |
| Map of labels that should have been in `need` but cannot be | |
| used by any user because of access restrictions. The value | |
| is currently an empty object. | |
| |`error_message`|optional| | |
| When status is RULE_ERROR this message provides some text describing | |
| the failure of the rule predicate. | |
| |=========================== | |
| [[submit-record-info]] | |
| === SubmitRecordInfo | |
| The `SubmitRecordInfo` entity describes results from a submit_rule. | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name ||Description | |
| |`rule_name`|| | |
| The name of the submit rule that created this submit record. The submit rule is | |
| specified in the form of "$plugin~$rule" where `$plugin` is the plugin name | |
| and `$rule` is the name of the class that implemented the submit rule. | |
| |`status`|| | |
| `OK`, the change can be submitted. + | |
| `NOT_READY`, additional labels are required before submit. + | |
| `CLOSED`, closed changes cannot be submitted. + | |
| `FORCED`, the change was submitted bypassing the submit rule. + | |
| `RULE_ERROR`, rule code failed with an error. | |
| |`labels`|optional| | |
| A list of labels, each containing the following fields. + | |
| * `label`: the label name. + | |
| * `status`: the label status: {`OK`, `REJECT`, `MAY`, `NEED`, `IMPOSSIBLE`}. + | |
| * `appliedBy`: the link:rest-api-accounts.html#account-info[AccountInfo] | |
| that applied the vote to the label. | |
| |`requirements`|optional| | |
| List of the link:rest-api-changes.html#requirement[requirements] to be met | |
| before this change can be submitted. | |
| |`error_message`|optional| | |
| When status is RULE_ERROR this message provides some text describing | |
| the failure of the rule predicate. | |
| |=========================== | |
| [[submit-requirement-expression-info]] | |
| === SubmitRequirementExpressionInfo | |
| The `SubmitRequirementExpressionInfo` describes the result of evaluating a | |
| single submit requirement expression, for example `label:code-review=+2`. | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name ||Description | |
| |`expression`|optional| | |
| The submit requirement expression as a string, for example | |
| `branch:refs/heads/foo and label:verified=+1`. | |
| |`fulfilled`|| | |
| True if the submit requirement is fulfilled for the change. | |
| |`status`|| | |
| A string containing the status of evaluating the expression which can be one | |
| of the following: + | |
| * `PASS` - expression was evaluated and result is true. + | |
| * `FAIL` - expression was evaluated and result is false. + | |
| * `ERROR` - an error occurred while evaluating the expression. + | |
| * `NOT_EVALUATED` - expression was not evaluated. + | |
| * `TIMEOUT` - expression was TIMEOUT while evaluating. | |
| |`passing_atoms`|optional| | |
| A list of passing atoms as strings. For the above expression, | |
| `passing_atoms` can contain ["branch:refs/heads/foo"] if the branch predicate is | |
| fulfilled for the change. | |
| |`failing_atoms`|optional| | |
| A list of failing atoms. This is similar to `passing_atoms` except that it | |
| contains the list of predicates that are not fulfilled for the change. | |
| |`atom_explanations`|optional| | |
| A map of atoms (as strings) to strings explaining the result. This | |
| field only contains atoms for which the explanation is available. | |
| |`error_message`|optional| | |
| If the submit requirement fails during evaluation, this string will contain | |
| an error message describing why it failed. | |
| |=========================== | |
| [[submit-requirement-input]] | |
| === SubmitRequirementInput | |
| The `SubmitRequirementInput` entity describes a submit requirement. | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name ||Description | |
| |`name`|| | |
| The submit requirement name. | |
| |`description`|optional| | |
| Description of the submit requirement. | |
| |`applicability_expression`|optional| | |
| Query expression that can be evaluated on any change. If evaluated to true on a | |
| change, the submit requirement is then applicable for this change. | |
| If not specified, the submit requirement is applicable for all changes. | |
| |`submittability_expression`|| | |
| Query expression that can be evaluated on any change. If evaluated to true on a | |
| change, the submit requirement is fulfilled and not blocking change submission. | |
| |`override_expression`|optional| | |
| Query expression that can be evaluated on any change. If evaluated to true on a | |
| change, the submit requirement is overridden and not blocking change submission. | |
| |`allow_override_in_child_projects`|optional| | |
| Whether this submit requirement can be overridden in child projects. Default is | |
| `true`. | |
| |=========================== | |
| [[submit-requirement-result-info]] | |
| === SubmitRequirementResultInfo | |
| The `SubmitRequirementResultInfo` describes the result of evaluating a | |
| submit requirement on a change. | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name ||Description | |
| |`name`|| | |
| The submit requirement name. | |
| |`description`|optional| | |
| Description of the submit requirement. | |
| |`status`|| | |
| Status describing the result of evaluating the submit requirement. The status | |
| is one of (`SATISFIED`, `UNSATISFIED`, `OVERRIDDEN`, `NOT_APPLICABLE`, `ERROR`, | |
| `FORCED`, `TIMEOUT`). | |
| |`is_legacy`|| | |
| If true, this submit requirement result was created from a legacy | |
| link:#submit-record[SubmitRecord]. Otherwise, it was created by evaluating a | |
| submit requirement. | |
| |`applicability_expression_result`|optional| | |
| A link:#submit-requirement-expression-info[SubmitRequirementExpressionInfo] | |
| containing the result of evaluating the applicability expression. Not set if the | |
| submit requirement did not define an applicability expression. | |
| Note that fields `expression`, `passing_atoms` and `failing_atoms` are always | |
| omitted for the `applicability_expression_result`. | |
| |`submittability_expression_result`|| | |
| A link:#submit-requirement-expression-info[SubmitRequirementExpressionInfo] | |
| containing the result of evaluating the submittability expression. + | |
| If the submit requirement does not apply, the `status` field of the result | |
| will be set to `NOT_EVALUATED`. | |
| |`override_expression_result`|optional| | |
| A link:#submit-requirement-expression-info[SubmitRequirementExpressionInfo] | |
| containing the result of evaluating the override expression. + | |
| Not set if the submit requirement did not define an override expression. If the | |
| submit requirement does not apply, the `status` field of the result will be set | |
| to `NOT_EVALUATED`. | |
| |=========================== | |
| [[submitted-together-info]] | |
| === SubmittedTogetherInfo | |
| The `SubmittedTogetherInfo` entity contains information about a | |
| collection of changes that would be submitted together. | |
| [options="header",cols="1,6"] | |
| |=========================== | |
| |Field Name |Description | |
| |`changes` | | |
| A list of ChangeInfo entities representing the changes to be submitted together. | |
| |`non_visible_changes`| | |
| The number of changes to be submitted together that the current user | |
| cannot see. (This count includes changes that are visible to the | |
| current user when their reason for being submitted together involves | |
| changes the user cannot see.) | |
| |=========================== | |
| [[suggested-reviewer-info]] | |
| === SuggestedReviewerInfo | |
| The `SuggestedReviewerInfo` entity contains information about a reviewer | |
| that can be added to a change (an account or a group). | |
| `SuggestedReviewerInfo` has either the `account` field that contains | |
| the link:rest-api-accounts.html#account-info[AccountInfo] entity, or | |
| the `group` field that contains the | |
| link:rest-api-changes.html#group-base-info[GroupBaseInfo] entity. | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name ||Description | |
| |`account` |optional| | |
| An link:rest-api-accounts.html#account-info[AccountInfo] entity, if the | |
| suggestion is an account. | |
| |`group` |optional| | |
| A link:rest-api-changes.html#group-base-info[GroupBaseInfo] entity, if the | |
| suggestion is a group. | |
| |`count` || | |
| The total number of accounts in the suggestion. This is `1` if `account` is | |
| present. If `group` is present, the total number of accounts that are | |
| members of the group is returned (this count includes members of nested | |
| groups). | |
| |`confirm` |optional| | |
| True if `group` is present and `count` is above the threshold where the | |
| `confirmed` flag must be passed to add the group as a reviewer. | |
| |=========================== | |
| [[topic-input]] | |
| === TopicInput | |
| The `TopicInput` entity contains information for setting a topic. | |
| [options="header",cols="1,^1,5"] | |
| |=========================== | |
| |Field Name ||Description | |
| |`topic` |optional|The topic. + | |
| The topic will be deleted if not set. | |
| Topic can't contain quotation marks. | |
| |=========================== | |
| [[tracking-id-info]] | |
| === TrackingIdInfo | |
| The `TrackingIdInfo` entity describes a reference to an external tracking system. | |
| [options="header",cols="1,6"] | |
| |====================== | |
| |Field Name|Description | |
| |`system` |The name of the external tracking system. | |
| |`id` |The tracking id. | |
| |====================== | |
| [[voting-range-info]] | |
| === VotingRangeInfo | |
| The `VotingRangeInfo` entity describes the continuous voting range from min | |
| to max values. | |
| [options="header",cols="1,6"] | |
| |====================== | |
| |Field Name|Description | |
| |`min` |The minimum voting value. | |
| |`max` |The maximum voting value. | |
| |====================== | |
| [[web-link-info]] | |
| === WebLinkInfo | |
| The `WebLinkInfo` entity describes a link to an external site. Depending on the | |
| context and the provided data the UI may decide to show the link as a text link, | |
| a linkified icon, or both. | |
| If the `tooltip` is not provided, then the UI may fall back to showing something | |
| like "Open in External Tool". | |
| Weblinks will always be opened in a new tab. | |
| [options="header",cols="1,^1,5"] | |
| |======================== | |
| |Field Name ||Description | |
| |`name` ||The text to be linkified. | |
| |`tooltip` |optional|Tooltip to show when hovering over the link. Using "Open | |
| in $NAME_OF_EXTERNAL_TOOL" is a good option here. | |
| |`url` ||The link URL. | |
| |`image_url`|optional|URL to the icon of the link. | |
| |======================== | |
| [[validation-option-info]] | |
| === ValidationOptionInfo | |
| The `ValidationOption` entity returns the validation option that is specified by the user on push. | |
| [options="header",cols="1,^2,4"] | |
| |======================= | |
| |Field Name ||Description | |
| |`name` ||The name of the validation option. | |
| |`description` ||The description of the validation option. | |
| |======================= | |
| [[validation-options-infos]] | |
| === ValidationOptionInfos | |
| The `ValidationOptionInfos` entity returns the list of all possible validation options. | |
| [options="header",cols="1,^2,4"] | |
| |======================= | |
| |Field Name ||Description | |
| |`validation_options` ||The list of all possible validation options. | |
| |======================= | |
| [[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 | |
| --------- |