| :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" |
| } |
| } |
| ---- |
| |
| [[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": [ |
| { |
| "account": { |
| "name": "John Doe" |
| }, |
| "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" |
| }, |
| }, |
| { |
| "id": "demo~master~I09c8041b5867d5b33170316e2abc34b79bbb8501", |
| "project": "demo", |
| "branch": "master", |
| "change_id": "I09c8041b5867d5b33170316e2abc34b79bbb8501", |
| "subject": "Another change", |
| "status": "NEW", |
| "created": "2012-07-17 07:18:30.884000000", |
| "updated": "2012-07-17 07:18:30.885000000", |
| "mergeable": true, |
| "insertions": 12, |
| "deletions": 18, |
| "_number": 1757, |
| "owner": { |
| "name": "John Doe" |
| }, |
| "_more_changes": true |
| } |
| ] |
| ---- |
| |
| If the number of changes matching the query exceeds either the internal |
| limit or a supplied `n` query parameter, the last change object has a |
| `_more_changes: true` JSON field set. |
| |
| The `S` or `start` query parameter can be supplied to skip a number |
| of changes from the list. |
| |
| Administrators can use the `skip-visibility` query parameter to skip visibility filtering. |
| This can be used to ensure that no changes are missed e.g. when querying for changes which |
| need to be reindexed. Without this parameter query results the user has no permission to read |
| are filtered out. REST requests with the skip-visibility option are rejected when the current |
| user doesn't have the ADMINISTRATE_SERVER capability. |
| |
| Clients are allowed to specify more than one query by setting the `q` |
| parameter multiple times. In this case the result is an array of |
| arrays, one per query in the same order the queries were given in. |
| |
| .Query for the 25 most recent open changes of the projects that you watch |
| **** |
| get::/changes/?q=status:open+is:watched&n=25 |
| **** |
| |
| Query that retrieves changes for a user's dashboard: |
| |
| .Request |
| ---- |
| GET /changes/?q=is:open+owner:self&q=is:open+reviewer:self+-owner:self&q=is:closed+owner:self+limit:5&o=LABELS HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| [ |
| [ |
| { |
| "id": "demo~master~Idaf5e098d70898b7119f6f4af5a6c13343d64b57", |
| "project": "demo", |
| "branch": "master", |
| "change_id": "Idaf5e098d70898b7119f6f4af5a6c13343d64b57", |
| "subject": "One change", |
| "status": "NEW", |
| "created": "2012-07-17 07:18:30.854000000", |
| "updated": "2012-07-17 07:19:27.766000000", |
| "mergeable": true, |
| "insertions": 4, |
| "deletions": 7, |
| "_number": 1756, |
| "owner": { |
| "name": "John Doe" |
| }, |
| "labels": { |
| "Verified": {}, |
| "Code-Review": {} |
| } |
| } |
| ], |
| [], |
| [] |
| ] |
| ---- |
| |
| .Query the changes for your user dashboard |
| **** |
| get::/changes/?q=is:open+owner:self&q=is:open+reviewer:self+-owner:self&q=is:closed+owner:self+limit:5&o=LABELS |
| **** |
| |
| [[query-options]] |
| Additional fields can be obtained by adding `o` parameters, each |
| option requires more database lookups and slows down the query |
| response time to the client so they are generally disabled by |
| default. Optional fields are: |
| |
| [[labels]] |
| -- |
| * `LABELS`: Includes the `labels` field which contains all information about |
| labels and approvers that have granted (or rejected) that label. Does not |
| include the `permitted_voting_range` attribute with the list of |
| link:#approval-info[ApprovalInfo] of the `all` attribute. |
| -- |
| |
| [[detailed-labels]] |
| -- |
| * `DETAILED_LABELS`: Includes the `labels` field which contains all information |
| about labels and approvers that have granted (or rejected) that label, including |
| the `permitted_voting_range` attribute with the list of |
| link:#approval-info[ApprovalInfo] of the `all` attribute. |
| -- |
| |
| [[submit-requirements]] |
| -- |
| * `SUBMIT_REQUIREMENTS`: detailed result of the evaluated submit requirements |
| for this change. |
| -- |
| |
| [[current-revision]] |
| -- |
| * `CURRENT_REVISION`: describe the current revision (patch set) |
| of the change, including the commit SHA-1 and URLs to fetch from. |
| -- |
| |
| [[all-revisions]] |
| -- |
| * `ALL_REVISIONS`: describe all revisions, not just current. |
| -- |
| |
| [[download-commands]] |
| -- |
| * `DOWNLOAD_COMMANDS`: include the `commands` field in the |
| link:#fetch-info[FetchInfo] for revisions. Only valid when the |
| `CURRENT_REVISION` or `ALL_REVISIONS` option is selected. |
| -- |
| |
| [[current-commit]] |
| -- |
| * `CURRENT_COMMIT`: parse and output all header fields from the |
| commit object, including message. Only valid when the |
| `CURRENT_REVISION` or `ALL_REVISIONS` option is selected. |
| -- |
| |
| [[all-commits]] |
| -- |
| * `ALL_COMMITS`: parse and output all header fields from the |
| output revisions. If only `CURRENT_REVISION` was requested |
| then only the current revision's commit data will be output. |
| -- |
| |
| [[current-files]] |
| -- |
| * `CURRENT_FILES`: list files modified by the commit and magic files, |
| including basic line counts inserted/deleted per file. Only valid |
| when the `CURRENT_REVISION` or `ALL_REVISIONS` option is selected. |
| -- |
| |
| [[all-files]] |
| -- |
| * `ALL_FILES`: list files modified by the commit and magic files, |
| including basic line counts inserted/deleted per file. If only the |
| `CURRENT_REVISION` was requested then only that commit's modified |
| files will be output. |
| -- |
| |
| [[detailed-accounts]] |
| -- |
| * `DETAILED_ACCOUNTS`: include `_account_id`, `email` and `username` |
| fields when referencing accounts. |
| -- |
| |
| [[reviewer-updates]] |
| -- |
| * `REVIEWER_UPDATES`: include updates to reviewers set as |
| link:#review-update-info[ReviewerUpdateInfo] entities. |
| -- |
| |
| [[messages]] |
| -- |
| * `MESSAGES`: include messages associated with the change. |
| -- |
| |
| [[actions]] |
| -- |
| * `CURRENT_ACTIONS`: include information on available actions |
| for the change and its current revision. Ignored if the caller |
| is not authenticated. |
| -- |
| |
| [[change-actions]] |
| -- |
| * `CHANGE_ACTIONS`: include information on available |
| change actions for the change. Ignored if the caller |
| is not authenticated. |
| -- |
| |
| [[reviewed]] |
| -- |
| * `REVIEWED`: include the `reviewed` field if all of the following are |
| true: |
| - the change is open |
| - the caller is authenticated |
| - the caller has commented on the change more recently than the last update |
| from the change owner, i.e. this change would show up in the results of |
| link:user-search.html#reviewedby[reviewedby:self]. |
| -- |
| [[skip_diffstat]] |
| -- |
| * `SKIP_DIFFSTAT`: skip the 'insertions' and 'deletions' field in link:#change-info[ChangeInfo]. |
| For large trees, their computation may be expensive. |
| -- |
| |
| [[submittable]] |
| -- |
| * `SUBMITTABLE`: include the `submittable` field in link:#change-info[ChangeInfo], |
| which can be used to tell if the change is reviewed and ready for submit. |
| -- |
| |
| [[web-links]] |
| -- |
| * `WEB_LINKS`: include the `web_links` field in link:#commit-info[CommitInfo], |
| therefore only valid in combination with `CURRENT_COMMIT` or |
| `ALL_COMMITS`. |
| -- |
| |
| [[check]] |
| -- |
| * `CHECK`: include potential problems with the change. |
| -- |
| |
| [[commit-footers]] |
| -- |
| * `COMMIT_FOOTERS`: include the full commit message with |
| Gerrit-specific commit footers in the |
| link:#revision-info[RevisionInfo]. |
| -- |
| |
| [[push-certificates]] |
| -- |
| * `PUSH_CERTIFICATES`: include push certificate information in the |
| link:#revision-info[RevisionInfo]. Ignored if signed push is not |
| link:config-gerrit.html#receive.enableSignedPush[enabled] on the |
| server. |
| -- |
| |
| [[tracking-ids]] |
| -- |
| * `TRACKING_IDS`: include references to external tracking systems |
| as link:#tracking-id-info[TrackingIdInfo]. |
| -- |
| |
| [[star]] |
| -- |
| * `STAR`: include the `starred` field in |
| link:#change-info[ChangeInfo], which indicates if the change is starred |
| by the current user or not. |
| -- |
| |
| .Request |
| ---- |
| GET /changes/?q=97&o=CURRENT_REVISION&o=CURRENT_COMMIT&o=CURRENT_FILES&o=DOWNLOAD_COMMANDS HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| [ |
| { |
| "id": "gerrit~master~I7ea46d2e2ee5c64c0d807677859cfb7d90b8966a", |
| "project": "gerrit", |
| "branch": "master", |
| "change_id": "I7ea46d2e2ee5c64c0d807677859cfb7d90b8966a", |
| "subject": "Use an EventBus to manage star icons", |
| "status": "NEW", |
| "created": "2012-04-25 00:52:25.580000000", |
| "updated": "2012-04-25 00:52:25.586000000", |
| "mergeable": true, |
| "insertions": 16, |
| "deletions": 7, |
| "_number": 97, |
| "owner": { |
| "name": "Shawn Pearce" |
| }, |
| "current_revision": "184ebe53805e102605d11f6b143486d15c23a09c", |
| "revisions": { |
| "184ebe53805e102605d11f6b143486d15c23a09c": { |
| "kind": "REWORK", |
| "_number": 1, |
| "ref": "refs/changes/97/97/1", |
| "fetch": { |
| "git": { |
| "url": "git://localhost/gerrit", |
| "ref": "refs/changes/97/97/1", |
| "commands": { |
| "Checkout": "git fetch git://localhost/gerrit refs/changes/97/97/1 \u0026\u0026 git checkout FETCH_HEAD", |
| "Cherry-Pick": "git fetch git://localhost/gerrit refs/changes/97/97/1 \u0026\u0026 git cherry-pick FETCH_HEAD", |
| "Format-Patch": "git fetch git://localhost/gerrit refs/changes/97/97/1 \u0026\u0026 git format-patch -1 --stdout FETCH_HEAD", |
| "Pull": "git pull git://localhost/gerrit refs/changes/97/97/1" |
| } |
| }, |
| "http": { |
| "url": "http://myuser@127.0.0.1:8080/gerrit", |
| "ref": "refs/changes/97/97/1", |
| "commands": { |
| "Checkout": "git fetch http://myuser@127.0.0.1:8080/gerrit refs/changes/97/97/1 \u0026\u0026 git checkout FETCH_HEAD", |
| "Cherry-Pick": "git fetch http://myuser@127.0.0.1:8080/gerrit refs/changes/97/97/1 \u0026\u0026 git cherry-pick FETCH_HEAD", |
| "Format-Patch": "git fetch http://myuser@127.0.0.1:8080/gerrit refs/changes/97/97/1 \u0026\u0026 git format-patch -1 --stdout FETCH_HEAD", |
| "Pull": "git pull http://myuser@127.0.0.1:8080/gerrit refs/changes/97/97/1" |
| } |
| }, |
| "ssh": { |
| "url": "ssh://myuser@*:29418/gerrit", |
| "ref": "refs/changes/97/97/1", |
| "commands": { |
| "Checkout": "git fetch ssh://myuser@*:29418/gerrit refs/changes/97/97/1 \u0026\u0026 git checkout FETCH_HEAD", |
| "Cherry-Pick": "git fetch ssh://myuser@*:29418/gerrit refs/changes/97/97/1 \u0026\u0026 git cherry-pick FETCH_HEAD", |
| "Format-Patch": "git fetch ssh://myuser@*:29418/gerrit refs/changes/97/97/1 \u0026\u0026 git format-patch -1 --stdout FETCH_HEAD", |
| "Pull": "git pull ssh://myuser@*:29418/gerrit refs/changes/97/97/1" |
| } |
| } |
| }, |
| "commit": { |
| "parents": [ |
| { |
| "commit": "1eee2c9d8f352483781e772f35dc586a69ff5646", |
| "subject": "Migrate contributor agreements to All-Projects." |
| } |
| ], |
| "author": { |
| "name": "Shawn O. Pearce", |
| "email": "sop@google.com", |
| "date": "2012-04-24 18:08:08.000000000", |
| "tz": -420 |
| }, |
| "committer": { |
| "name": "Shawn O. Pearce", |
| "email": "sop@google.com", |
| "date": "2012-04-24 18:08:08.000000000", |
| "tz": -420 |
| }, |
| "subject": "Use an EventBus to manage star icons", |
| "message": "Use an EventBus to manage star icons\n\nImage widgets that need to ..." |
| }, |
| "files": { |
| "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeCache.java": { |
| "lines_deleted": 8, |
| "size_delta": -412, |
| "size": 7782 |
| }, |
| "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeDetailCache.java": { |
| "lines_inserted": 1, |
| "size_delta": 23, |
| "size": 6762 |
| }, |
| "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeScreen.java": { |
| "lines_inserted": 11, |
| "lines_deleted": 19, |
| "size_delta": -298, |
| "size": 47023 |
| }, |
| "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeTable.java": { |
| "lines_inserted": 23, |
| "lines_deleted": 20, |
| "size_delta": 132, |
| "size": 17727 |
| }, |
| "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarCache.java": { |
| "status": "D", |
| "lines_deleted": 139, |
| "size_delta": -5512, |
| "size": 13098 |
| }, |
| "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarredChanges.java": { |
| "status": "A", |
| "lines_inserted": 204, |
| "size_delta": 8345, |
| "size": 8345 |
| }, |
| "gerrit-gwtui/src/main/java/com/google/gerrit/client/ui/Screen.java": { |
| "lines_deleted": 9, |
| "size_delta": -343, |
| "size": 5385 |
| } |
| } |
| } |
| } |
| } |
| ] |
| ---- |
| |
| [[get-change]] |
| === Get Change |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]' |
| -- |
| |
| Retrieves a change. |
| |
| Additional fields can be obtained by adding `o` parameters, each |
| option requires more database lookups and slows down the query |
| response time to the client so they are generally disabled by |
| default. Fields are described in link:#list-changes[Query Changes]. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940 HTTP/1.0 |
| ---- |
| |
| As response a link:#change-info[ChangeInfo] entity is returned that |
| describes the change. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "project": "myProject", |
| "branch": "master", |
| "attention_set": [ |
| { |
| "account": { |
| "name": "John Doe" |
| }, |
| "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" |
| } |
| } |
| ---- |
| |
| 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": [ |
| { |
| "account": { |
| "name": "John Doe" |
| }, |
| "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" |
| } |
| }, |
| "new_change_info": { |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "project": "myProject", |
| "branch": "master", |
| "attention_set": [ |
| { |
| "account": { |
| "name": "John Doe" |
| }, |
| "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" |
| } |
| }, |
| } |
| ---- |
| |
| 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": [ |
| { |
| "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_reviewers": [ |
| { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com", |
| "username": "jdoe" |
| }, |
| { |
| "_account_id": 1000097, |
| "name": "Jane Roe", |
| "email": "jane.roe@example.com", |
| "username": "jroe" |
| } |
| ], |
| "reviewers": { |
| "REVIEWER": [ |
| { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com", |
| "username": "jdoe" |
| }, |
| { |
| "_account_id": 1000097, |
| "name": "Jane Roe", |
| "email": "jane.roe@example.com", |
| "username": "jroe" |
| } |
| ] |
| }, |
| "reviewer_updates": [ |
| { |
| "state": "REVIEWER", |
| "reviewer": { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com", |
| "username": "jdoe" |
| }, |
| "updated_by": { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com", |
| "username": "jdoe" |
| }, |
| "updated": "2016-07-21 20:12:39.000000000" |
| }, |
| { |
| "state": "REMOVED", |
| "reviewer": { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com", |
| "username": "jdoe" |
| }, |
| "updated_by": { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com", |
| "username": "jdoe" |
| }, |
| "updated": "2016-07-21 20:12:33.000000000" |
| }, |
| { |
| "state": "CC", |
| "reviewer": { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com", |
| "username": "jdoe" |
| }, |
| "updated_by": { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com", |
| "username": "jdoe" |
| }, |
| "updated": "2016-03-23 21:34:02.419000000", |
| }, |
| ], |
| "messages": [ |
| { |
| "id": "YH-egE", |
| "author": { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com", |
| "username": "jdoe" |
| }, |
| "date": "2013-03-23 21:34:02.419000000", |
| "message": "Patch Set 1:\n\nThis is the first message.", |
| "_revision_number": 1 |
| }, |
| { |
| "id": "WEEdhU", |
| "author": { |
| "_account_id": 1000097, |
| "name": "Jane Roe", |
| "email": "jane.roe@example.com", |
| "username": "jroe" |
| }, |
| "date": "2013-03-23 21:36:52.332000000", |
| "message": "Patch Set 1:\n\nThis is the second message.\n\nWith a line break.", |
| "_revision_number": 1 |
| } |
| ] |
| } |
| ---- |
| |
| [[create-merge-patch-set-for-change]] |
| === Create Merge Patch Set For Change |
| -- |
| 'POST /changes/link:#change-id[\{change-id\}]/merge' |
| -- |
| |
| Update an existing change by using a |
| link:#merge-patch-set-input[MergePatchSetInput] entity. |
| |
| Gerrit will create a merge commit based on the information of |
| MergePatchSetInput and add a new patch set to the change corresponding |
| to the new merge commit. |
| |
| .Request |
| ---- |
| POST /changes/test~master~Ic5466d107c5294414710935a8ef3b0180fb848dc/merge HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "subject": "Merge dev_branch into master", |
| "merge": { |
| "source": "refs/changes/34/1234/1" |
| } |
| } |
| ---- |
| |
| As response a link:#change-info[ChangeInfo] entity with current revision is |
| returned that describes the resulting change. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "id": "test~master~Ic5466d107c5294414710935a8ef3b0180fb848dc", |
| "project": "test", |
| "branch": "master", |
| "hashtags": [], |
| "change_id": "Ic5466d107c5294414710935a8ef3b0180fb848dc", |
| "subject": "Merge dev_branch into master", |
| "status": "NEW", |
| "created": "2016-09-23 18:08:53.238000000", |
| "updated": "2016-09-23 18:09:25.934000000", |
| "submit_type": "MERGE_IF_NECESSARY", |
| "mergeable": true, |
| "insertions": 5, |
| "deletions": 0, |
| "_number": 72, |
| "owner": { |
| "_account_id": 1000000 |
| }, |
| "current_revision": "27cc4558b5a3d3387dd11ee2df7a117e7e581822" |
| } |
| ---- |
| |
| [[set-message]] |
| === Set Commit Message |
| -- |
| 'PUT /changes/link:#change-id[\{change-id\}]/message' |
| -- |
| |
| Creates a new patch set with a new commit message. |
| |
| The new commit message must be provided in the request body inside a |
| link:#commit-message-input[CommitMessageInput] entity. 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-assignee]] |
| === Get Assignee |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/assignee' |
| -- |
| |
| Retrieves the account of the user assigned to a change. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/assignee HTTP/1.0 |
| ---- |
| |
| As a response an link:rest-api-accounts.html#account-info[AccountInfo] entity |
| describing the assigned account is returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com", |
| "username": "jdoe" |
| } |
| ---- |
| |
| If the change has no assignee the response is "`204 No Content`". |
| |
| [[get-past-assignees]] |
| === Get Past Assignees |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/past_assignees' |
| -- |
| |
| Returns a list of every user ever assigned to a change, in the order in which |
| they were first assigned. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/past_assignees HTTP/1.0 |
| ---- |
| |
| As a response a list of link:rest-api-accounts.html#account-info[AccountInfo] |
| entities is returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| [ |
| { |
| "_account_id": 1000051, |
| "name": "Jane Doe", |
| "email": "jane.doe@example.com", |
| "username": "janed" |
| }, |
| { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com", |
| "username": "jdoe" |
| } |
| ] |
| |
| ---- |
| |
| |
| [[set-assignee]] |
| === Set Assignee |
| -- |
| 'PUT /changes/link:#change-id[\{change-id\}]/assignee' |
| -- |
| |
| Sets the assignee of a change. |
| |
| The new assignee must be provided in the request body inside a |
| link:#assignee-input[AssigneeInput] entity. |
| |
| .Request |
| ---- |
| PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/assignee HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "assignee": "jdoe" |
| } |
| ---- |
| |
| As a response an link:rest-api-accounts.html#account-info[AccountInfo] entity |
| describing the assigned account is returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com", |
| "username": "jdoe" |
| } |
| ---- |
| |
| [[delete-assignee]] |
| === Delete Assignee |
| -- |
| 'DELETE /changes/link:#change-id[\{change-id\}]/assignee' |
| -- |
| |
| Deletes the assignee of a change. |
| |
| |
| .Request |
| ---- |
| DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/assignee HTTP/1.0 |
| ---- |
| |
| As a response an link:rest-api-accounts.html#account-info[AccountInfo] entity |
| describing the account of the deleted assignee is returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com", |
| "username": "jdoe" |
| } |
| ---- |
| |
| If the change had no assignee the response is "`204 No Content`". |
| |
| [[get-pure-revert]] |
| === Get Pure Revert |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/pure_revert' |
| -- |
| |
| Check if the given change is a pure revert of the change it references in `revertOf`. |
| Optionally, the query parameter `o` can be passed in to specify a commit (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:#attention-set[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" |
| } |
| } |
| ---- |
| |
| If the change cannot be abandoned because the change state doesn't |
| allow abandoning of the change, the response is "`409 Conflict`" and |
| the error message is contained in the response body. |
| |
| .Response |
| ---- |
| HTTP/1.1 409 Conflict |
| Content-Disposition: attachment |
| Content-Type: text/plain; charset=UTF-8 |
| |
| change is merged |
| ---- |
| |
| .Notifications |
| |
| An email will be sent using the "abandon" template. The notify handling is ALL. |
| Notifications are suppressed on WIP changes that have never started review. |
| |
| [options="header",cols="1,2"] |
| |============================= |
| |WIP State |notify=ALL |
| |Ready for review|owner, reviewers, CCs, stars, ABANDONED_CHANGES watchers |
| |Work in progress|not sent |
| |Reviewable WIP |owner, reviewers, CCs, stars, ABANDONED_CHANGES watchers |
| |============================= |
| |
| [[restore-change]] |
| === Restore Change |
| -- |
| 'POST /changes/link:#change-id[\{change-id\}]/restore' |
| -- |
| |
| Restores a change. |
| |
| The request body does not need to include a link:#restore-input[ |
| RestoreInput] entity if no review comment is added. |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/restore HTTP/1.0 |
| ---- |
| |
| As response a link:#change-info[ChangeInfo] entity is returned that |
| describes the restored change. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "project": "myProject", |
| "branch": "master", |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "subject": "Implementing Feature X", |
| "status": "NEW", |
| "created": "2013-02-01 09:59:32.126000000", |
| "updated": "2013-02-21 11:16:36.775000000", |
| "mergeable": true, |
| "insertions": 2, |
| "deletions": 13, |
| "_number": 3965, |
| "owner": { |
| "name": "John Doe" |
| } |
| } |
| ---- |
| |
| If the change cannot be restored because the change state doesn't |
| allow restoring the change, the response is "`409 Conflict`" and |
| the error message is contained in the response body. |
| |
| .Response |
| ---- |
| HTTP/1.1 409 Conflict |
| Content-Disposition: attachment |
| Content-Type: text/plain; charset=UTF-8 |
| |
| change is new |
| ---- |
| |
| [[rebase-change]] |
| === Rebase Change |
| -- |
| 'POST /changes/link:#change-id[\{change-id\}]/rebase' |
| -- |
| |
| Rebases a change. |
| |
| Optionally, the parent revision can be changed to another patch set through the |
| link:#rebase-input[RebaseInput] entity. |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I3ea943139cb62e86071996f2480e58bf3eeb9dd2/rebase HTTP/1.0 |
| Content-Type: application/json;charset=UTF-8 |
| |
| { |
| "base" : "1234", |
| } |
| ---- |
| |
| As response a link:#change-info[ChangeInfo] entity is returned that |
| describes the rebased change. Information about the current patch set |
| is included. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "id": "myProject~master~I3ea943139cb62e86071996f2480e58bf3eeb9dd2", |
| "project": "myProject", |
| "branch": "master", |
| "change_id": "I3ea943139cb62e86071996f2480e58bf3eeb9dd2", |
| "subject": "Implement Feature X", |
| "status": "NEW", |
| "created": "2013-02-01 09:59:32.126000000", |
| "updated": "2013-02-21 11:16:36.775000000", |
| "mergeable": false, |
| "insertions": 33, |
| "deletions": 9, |
| "_number": 4799, |
| "owner": { |
| "name": "John Doe" |
| }, |
| "current_revision": "27cc4558b5a3d3387dd11ee2df7a117e7e581822", |
| "revisions": { |
| "27cc4558b5a3d3387dd11ee2df7a117e7e581822": { |
| "kind": "REWORK", |
| "_number": 2, |
| "ref": "refs/changes/99/4799/2", |
| "fetch": { |
| "http": { |
| "url": "http://gerrit:8080/myProject", |
| "ref": "refs/changes/99/4799/2" |
| } |
| }, |
| "commit": { |
| "parents": [ |
| { |
| "commit": "b4003890dadd406d80222bf1ad8aca09a4876b70", |
| "subject": "Implement Feature A" |
| } |
| ], |
| "author": { |
| "name": "John Doe", |
| "email": "john.doe@example.com", |
| "date": "2013-05-07 15:21:27.000000000", |
| "tz": 120 |
| }, |
| "committer": { |
| "name": "Gerrit Code Review", |
| "email": "gerrit-server@example.com", |
| "date": "2013-05-07 15:35:43.000000000", |
| "tz": 120 |
| }, |
| "subject": "Implement Feature X", |
| "message": "Implement Feature X\n\nAdded feature X." |
| } |
| } |
| } |
| ---- |
| |
| If the change cannot be rebased, e.g. due to conflicts, the response is |
| "`409 Conflict`" and the error message is contained in the response |
| body. |
| |
| .Response |
| ---- |
| HTTP/1.1 409 Conflict |
| Content-Disposition: attachment |
| Content-Type: text/plain; charset=UTF-8 |
| |
| The change could not be rebased due to a path conflict during merge. |
| ---- |
| |
| [[move-change]] |
| === Move Change |
| -- |
| 'POST /changes/link:#change-id[\{change-id\}]/move' |
| -- |
| |
| Move a change. |
| |
| The destination branch must be provided in the request body inside a |
| link:#move-input[MoveInput] entity. |
| 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" |
| } |
| } |
| ---- |
| |
| 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" |
| } |
| } |
| ---- |
| |
| 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" |
| } |
| }, |
| { |
| "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" |
| } |
| } |
| ] |
| ---- |
| |
| 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. |
| |
| 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:#attention-set[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" |
| } |
| } |
| ---- |
| |
| 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": "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": "1bd7c12a38854a2c6de426feec28800623f492c4", |
| "revisions": { |
| "1bd7c12a38854a2c6de426feec28800623f492c4": { |
| "kind": "REWORK", |
| "_number": 1, |
| "created": "2015-05-01 15:39:57.979000000", |
| "uploader": { |
| "_account_id": 1000000 |
| }, |
| "ref": "refs/changes/80/1780/1", |
| "fetch": {}, |
| } |
| } |
| } |
| ], |
| "non_visible_changes": 0 |
| } |
| ---- |
| |
| If the `o=NON_VISIBLE_CHANGES` query parameter is not passed, then |
| instead of a link:#submitted-together-info[SubmittedTogetherInfo] |
| entity, the response is a list of changes, or a 403 response with a |
| message if the set of changes to be submitted with this change |
| includes changes the caller cannot read. |
| |
| |
| [[delete-change]] |
| === Delete Change |
| -- |
| 'DELETE /changes/link:#change-id[\{change-id\}]' |
| -- |
| |
| Deletes a change. |
| |
| New or abandoned changes can be deleted by their owner if the user is granted |
| the link:access-control.html#category_delete_own_changes[Delete Own Changes] permission, |
| otherwise only by administrators. |
| |
| .Request |
| ---- |
| DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940 HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| [[get-included-in]] |
| === Get Included In |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/in' |
| -- |
| |
| Retrieves the branches and tags in which a change is included. As result |
| an link:#included-in-info[IncludedInInfo] entity is returned. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/in HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "branches": [ |
| "master" |
| ], |
| "tags": [] |
| } |
| ---- |
| |
| [[index-change]] |
| === Index Change |
| -- |
| 'POST /changes/link:#change-id[\{change-id\}]/index' |
| -- |
| |
| Adds or updates the change in the secondary index. |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/index HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| [[list-change-comments]] |
| === List Change Comments |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/comments' |
| -- |
| |
| Lists the published comments of all revisions of the change. |
| |
| Returns a map of file paths to lists of link:#comment-info[CommentInfo] |
| entries. The entries in the map are sorted by file path, and the |
| comments for each path are sorted by patch set number. Each comment has |
| the `patch_set` and `author` fields set. |
| |
| If the `enable-context` request parameter is set to true, the comment entries |
| will contain a list of link:#context-line[ContextLine] containing the lines of |
| the source file where the comment was written. |
| |
| The `context-padding` request parameter can be used to specify an extra number |
| of context lines to be added before and after the comment range. This parameter |
| only works if `enable-context` is set to true. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/comments HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": [ |
| { |
| "patch_set": 1, |
| "id": "TvcXrmjM", |
| "line": 23, |
| "message": "[nit] trailing whitespace", |
| "updated": "2013-02-26 15:40:43.986000000" |
| "author": { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com" |
| } |
| }, |
| { |
| "patch_set": 2, |
| "id": "TveXwFiA", |
| "line": 49, |
| "in_reply_to": "TfYX-Iuo", |
| "message": "Done", |
| "updated": "2013-02-26 15:40:45.328000000" |
| "author": { |
| "_account_id": 1000097, |
| "name": "Jane Roe", |
| "email": "jane.roe@example.com" |
| } |
| } |
| ] |
| } |
| ---- |
| |
| [[list-change-robot-comments]] |
| === List Change Robot Comments |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/robotcomments' |
| -- |
| |
| Lists the robot comments of all revisions of the change. |
| |
| Return a map that maps the file path to a list of |
| link:#robot-comment-info[RobotCommentInfo] entries. The entries in the |
| map are sorted by file path. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/robotcomments/ HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": [ |
| { |
| "id": "TvcXrmjM", |
| "line": 23, |
| "message": "unused import", |
| "updated": "2016-02-26 15:40:43.986000000", |
| "author": { |
| "_account_id": 1000110, |
| "name": "Code Analyzer", |
| "email": "code.analyzer@example.com" |
| }, |
| "robot_id": "importChecker", |
| "robot_run_id": "76b1375aa8626ea7149792831fe2ed85e80d9e04" |
| }, |
| { |
| "id": "TveXwFiA", |
| "line": 49, |
| "message": "wrong indention", |
| "updated": "2016-02-26 15:40:45.328000000", |
| "author": { |
| "_account_id": 1000110, |
| "name": "Code Analyzer", |
| "email": "code.analyzer@example.com" |
| }, |
| "robot_id": "styleChecker", |
| "robot_run_id": "5c606c425dd45184484f9d0a2ffd725a7607839b" |
| } |
| ] |
| } |
| ---- |
| |
| [[list-change-drafts]] |
| === List Change Drafts |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/drafts' |
| -- |
| |
| Lists the draft comments of all revisions of the change that belong to |
| the calling user. |
| |
| Returns a map of file paths to lists of link:#comment-info[CommentInfo] |
| entries. The entries in the map are sorted by file path, and the |
| comments for each path are sorted by patch set number. Each comment has |
| the `patch_set` field set, and no `author`. |
| |
| The `enable-context` and `context-padding` request parameters can be used to |
| request comment context. See link:#list-change-comments[List Change Comments] |
| for more details. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/drafts HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": [ |
| { |
| "patch_set": 1, |
| "id": "TvcXrmjM", |
| "line": 23, |
| "message": "[nit] trailing whitespace", |
| "updated": "2013-02-26 15:40:43.986000000" |
| }, |
| { |
| "patch_set": 2, |
| "id": "TveXwFiA", |
| "line": 49, |
| "in_reply_to": "TfYX-Iuo", |
| "message": "Done", |
| "updated": "2013-02-26 15:40:45.328000000" |
| } |
| ] |
| } |
| ---- |
| |
| [[check-change]] |
| === Check Change |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/check' |
| -- |
| |
| Performs consistency checks on the change, and returns a |
| link:#change-info[ChangeInfo] entity with the `problems` field set to a |
| list of link:#problem-info[ProblemInfo] entities. |
| |
| Depending on the type of problem, some fields not marked optional may be |
| missing from the result. At least `id`, `project`, `branch`, and |
| `_number` will be present. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/check HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "project": "myProject", |
| "branch": "master", |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "subject": "Implementing Feature X", |
| "status": "NEW", |
| "created": "2013-02-01 09:59:32.126000000", |
| "updated": "2013-02-21 11:16:36.775000000", |
| "mergeable": true, |
| "insertions": 34, |
| "deletions": 101, |
| "_number": 3965, |
| "owner": { |
| "name": "John Doe" |
| }, |
| "problems": [ |
| { |
| "message": "Current patch set 1 not found" |
| } |
| ] |
| } |
| ---- |
| |
| [[fix-change]] |
| === Fix Change |
| -- |
| 'POST /changes/link:#change-id[\{change-id\}]/check' |
| -- |
| |
| Performs consistency checks on the change as with link:#check-change[GET |
| /check], and additionally fixes any problems that can be fixed |
| automatically. The returned field values reflect any fixes. |
| |
| Some fixes have options controlling their behavior, which can be set in the |
| link:#fix-input[FixInput] entity body. |
| |
| Only the change owner, a project owner, or an administrator may fix changes. |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/check HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "project": "myProject", |
| "branch": "master", |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "subject": "Implementing Feature X", |
| "status": "MERGED", |
| "created": "2013-02-01 09:59:32.126000000", |
| "updated": "2013-02-21 11:16:36.775000000", |
| "submitted": "2013-02-21 11:16:36.615000000", |
| "mergeable": true, |
| "insertions": 34, |
| "deletions": 101, |
| "_number": 3965, |
| "owner": { |
| "name": "John Doe" |
| }, |
| "problems": [ |
| { |
| "message": "Current patch set 2 not found" |
| }, |
| { |
| "message": "Patch set 1 (1eee2c9d8f352483781e772f35dc586a69ff5646) is merged into destination ref master (1eee2c9d8f352483781e772f35dc586a69ff5646), but change status is NEW", |
| "status": FIXED, |
| "outcome": "Marked change as merged" |
| } |
| ] |
| } |
| ---- |
| |
| [[set-work-in-pogress]] |
| === Set Work-In-Progress |
| -- |
| 'POST /changes/link:#change-id[\{change-id\}]/wip' |
| -- |
| |
| Marks the change as not ready for review yet. Changes may only be marked not |
| ready by the owner, project owners or site administrators. |
| |
| The request body does not need to include a |
| link:#work-in-progress-input[WorkInProgressInput] entity if no review comment |
| is added. Actions that create a new patch set in a WIP change default to |
| notifying *OWNER* instead of *ALL*. |
| |
| Marking a change work in progress also removes all users from the |
| link:#attention-set[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:#attention-set[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" |
| ] |
| ---- |
| |
| [[list-change-messages]] |
| === List Change Messages |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/messages' |
| -- |
| |
| Lists all the messages of a change including link:#detailed-accounts[detailed account information]. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/messages |
| ---- |
| |
| As response a list of link:#change-message-info[ChangeMessageInfo] entities is returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| [ |
| { |
| "id": "YH-egE", |
| "author": { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com", |
| "username": "jdoe" |
| }, |
| "date": "2013-03-23 21:34:02.419000000", |
| "message": "Patch Set 1:\n\nThis is the first message.", |
| "_revision_number": 1 |
| }, |
| { |
| "id": "WEEdhU", |
| "author": { |
| "_account_id": 1000097, |
| "name": "Jane Roe", |
| "email": "jane.roe@example.com", |
| "username": "jroe" |
| }, |
| "date": "2013-03-23 21:36:52.332000000", |
| "message": "Patch Set 1:\n\nThis is the second message.\n\nWith a line break.", |
| "_revision_number": 1 |
| } |
| ] |
| ---- |
| |
| [[get-change-message]] |
| === Get Change Message |
| |
| Retrieves a change message including link:#detailed-accounts[detailed account information]. |
| |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/messages/link:#change-message-id[\{change-message-id\}]' |
| -- |
| |
| As response a link:#change-message-info[ChangeMessageInfo] entity is returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "id": "aaee04dcb46bafc8be24d8aa70b3b1beb7df5780", |
| "author": { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com", |
| "username": "jdoe" |
| }, |
| "date": "2013-03-23 21:34:02.419000000", |
| "message": "a change message", |
| "_revision_number": 1 |
| } |
| ---- |
| |
| [[delete-change-message]] |
| === Delete Change Message |
| -- |
| 'DELETE /changes/link:#change-id[\{change-id\}]/messages/link:#change-message-id[\{change-message-id\}]' + |
| 'POST /changes/link:#change-id[\{change-id\}]/messages/link:#change-message-id[\{change-message-id\}]/delete' |
| -- |
| |
| Deletes a change message by replacing the change message with a new message, |
| which contains the name of the user who deleted the change message and the |
| reason why it was deleted. The reason can be provided in the request body as a |
| link:#delete-change-message-input[DeleteChangeMessageInput] entity. |
| |
| Note that only users with the |
| link:access-control.html#capability_administrateServer[Administrate Server] |
| global capability are permitted to delete a change message. |
| |
| To delete a change message, send a DELETE request: |
| |
| .Request |
| ---- |
| DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/messages/aaee04dcb46bafc8be24d8aa70b3b1beb7df5780 HTTP/1.0 |
| ---- |
| |
| To provide a reason for the deletion, use a POST request: |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/messages/aaee04dcb46bafc8be24d8aa70b3b1beb7df5780/delete HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "reason": "spam" |
| } |
| ---- |
| |
| As response a link:#change-message-info[ChangeMessageInfo] entity is returned that |
| describes the updated change message. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "id": "aaee04dcb46bafc8be24d8aa70b3b1beb7df5780", |
| "author": { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com", |
| "username": "jdoe" |
| }, |
| "date": "2013-03-23 21:34:02.419000000", |
| "message": "Change message removed by: Administrator\nReason: spam", |
| "_revision_number": 1 |
| } |
| ---- |
| |
| [[check-submit-requirement]] |
| === Check Submit Requirement |
| -- |
| 'POST /changes/link:#change-id[\{change-id\}]/check.submit_requirement' |
| -- |
| |
| Tests a submit requirement and returns the result as a |
| link:#submit-requirement-result-info[SubmitRequirementResultInfo]. |
| |
| The submit requirement can be specified in one of the following ways: |
| |
| * In the request body as a link:#submit-requirement-input[SubmitRequirementInput]. |
| * By passing the two request parameters `sr-name` and |
| `refs-config-change-id`. The submit requirement will then be loaded from |
| the project config pointed to by the latest patchset of this change ID. |
| The `sr-name` should point to an existing submit-requirement and the |
| `refs-config-change-id` must be a valid change identifier for a change in the |
| refs/meta/config branch, otherwise the request would fail with |
| `400 Bad Request`. |
| |
| Note that this endpoint does not modify the change resource. |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/check.submit_requirement HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "name": "Code-Review", |
| "submittability_expression": "label:Code-Review=+2" |
| } |
| ---- |
| |
| As response a link:#submit-requirement-result-info[SubmitRequirementResultInfo] |
| entity is returned that describes the submit requirement result. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "name": "Code-Review", |
| "status": "SATISFIED", |
| "submittability_expression_result": { |
| "expression": "label:Code-Review=+2", |
| "fulfilled": true, |
| "passingAtoms": [ |
| "label:Code-Review=+2" |
| ] |
| }, |
| "is_legacy": false |
| } |
| ---- |
| |
| [[edit-endpoints]] |
| == Change Edit Endpoints |
| |
| [[get-edit-detail]] |
| === Get Change Edit Details |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/edit |
| -- |
| |
| Retrieves a change edit details. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit HTTP/1.0 |
| ---- |
| |
| As response an link:#edit-info[EditInfo] entity is returned that |
| describes the change edit, or "`204 No Content`" when change edit doesn't |
| exist for this change. Change edits are stored on special branches and there |
| can be max one edit per user per change. Edits aren't tracked in the database. |
| When request parameter `list` is provided the response also includes the file |
| list. When `base` request parameter is provided the file list is computed |
| against this base revision. When request parameter `download-commands` is |
| provided fetch info map is also included. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "commit": { |
| "parents": [ |
| { |
| "commit": "1eee2c9d8f352483781e772f35dc586a69ff5646", |
| } |
| ], |
| "author": { |
| "name": "Shawn O. Pearce", |
| "email": "sop@google.com", |
| "date": "2012-04-24 18:08:08.000000000", |
| "tz": -420 |
| }, |
| "committer": { |
| "name": "Shawn O. Pearce", |
| "email": "sop@google.com", |
| "date": "2012-04-24 18:08:08.000000000", |
| "tz": -420 |
| }, |
| "subject": "Use an EventBus to manage star icons", |
| "message": "Use an EventBus to manage star icons\n\nImage widgets that need to ..." |
| }, |
| "base_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. |
| |
| .Request |
| ---- |
| PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit/foo HTTP/1.0 |
| ---- |
| |
| To upload a file as binary data in the request body: |
| |
| .Request |
| ---- |
| PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit/foo HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "binary_content": "data:text/plain;base64,SGVsbG8sIFdvcmxkIQ==" |
| } |
| ---- |
| |
| Note that it must be base-64 encoded data uri. |
| |
| When change edit doesn't exist for this change yet it is created. When file |
| content isn't provided, it is wiped out for that file. As response |
| "`204 No Content`" is returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| When the change edit is a no-op, for example when providing the same file |
| content that the file already has, '409 no changes were made' is returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 409 no changes were made |
| ---- |
| |
| [[post-edit]] |
| === Restore file content or rename files in Change Edit |
| -- |
| 'POST /changes/link:#change-id[\{change-id\}]/edit |
| -- |
| |
| Creates empty change edit, restores file content or renames files in change |
| edit. The request body needs to include a |
| link:#change-edit-input[ChangeEditInput] entity when a file within change |
| edit should be restored or old and new file names to rename a file. |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "restore_path": "foo" |
| } |
| ---- |
| |
| or for rename: |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "old_path": "foo", |
| "new_path": "bar" |
| } |
| ---- |
| |
| When change edit doesn't exist for this change yet it is created. When path |
| and restore flag are provided in request body, this file is restored. When |
| old and new file names are provided, the file is renamed. As response |
| "`204 No Content`" is returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| [[put-change-edit-message]] |
| === Change commit message in Change Edit |
| -- |
| 'PUT /changes/link:#change-id[\{change-id\}]/edit:message |
| -- |
| |
| Modify commit message. The request body needs to include a |
| link:#change-edit-message-input[ChangeEditMessageInput] |
| entity. |
| |
| .Request |
| ---- |
| PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit:message HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "message": "New commit message\n\nChange-Id: I10394472cbd17dd12454f229e4f6de00b143a444" |
| } |
| ---- |
| |
| If a change edit doesn't exist for this change yet, it is created. As |
| response "`204 No Content`" is returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| [[delete-edit-file]] |
| === Delete file in Change Edit |
| -- |
| 'DELETE /changes/link:#change-id[\{change-id\}]/edit/path%2fto%2ffile' |
| -- |
| |
| Deletes a file from a change edit. This deletes the file from the repository |
| completely. This is not the same as reverting or restoring a file to its |
| previous contents. |
| |
| .Request |
| ---- |
| DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit/foo HTTP/1.0 |
| ---- |
| |
| When change edit doesn't exist for this change yet it is created. |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| [[get-edit-file]] |
| === Retrieve file content from Change Edit |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/edit/path%2fto%2ffile |
| -- |
| |
| Retrieves content of a file from a change edit. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit/foo HTTP/1.0 |
| ---- |
| |
| The content of the file is returned as text encoded inside base64. |
| The Content-Type header will always be `text/plain` reflecting the |
| outer base64 encoding. A Gerrit-specific `X-FYI-Content-Type` header |
| can be examined to find the server detected content type of the file. |
| |
| When the specified file was deleted in the change edit |
| "`204 No Content`" is returned. |
| |
| If only the content type is required, callers should use HEAD to |
| avoid downloading the encoded file contents. |
| |
| If the `base` parameter is set to true, the returned content is from the |
| revision that the edit is based on. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: text/plain; charset=ISO-8859-1 |
| X-FYI-Content-Encoding: base64 |
| X-FYI-Content-Type: text/xml |
| |
| RnJvbSA3ZGFkY2MxNTNmZGVhMTdhYTg0ZmYzMmE2ZTI0NWRiYjY... |
| ---- |
| |
| Alternatively, if the only value of the Accept request header is |
| `application/json` the content is returned as JSON string and |
| `X-FYI-Content-Encoding` is set to `json`. |
| |
| [[get-edit-meta-data]] |
| === Retrieve meta data of a file from Change Edit |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/edit/path%2fto%2ffile/meta |
| -- |
| |
| Retrieves meta data of a file from a change edit. Currently only |
| web links are returned. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit/foo/meta HTTP/1.0 |
| ---- |
| |
| This REST endpoint retrieves additional information for a file in a |
| change edit. As result an link:#edit-file-info[EditFileInfo] entity is |
| returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "web_links": [ |
| { |
| "show_on_side_by_side_diff_view": true, |
| "name": "side-by-side preview diff", |
| "image_url": "plugins/xdocs/static/sideBySideDiffPreview.png", |
| "url": "#/x/xdocs/c/42/1..0/README.md", |
| "target": "_self" |
| }, |
| { |
| "show_on_unified_diff_view": true, |
| "name": "unified preview diff", |
| "image_url": "plugins/xdocs/static/unifiedDiffPreview.png", |
| "url": "#/x/xdocs/c/42/1..0/README.md,unified", |
| "target": "_self" |
| } |
| ]} |
| ---- |
| |
| [[get-edit-message]] |
| === Retrieve commit message from Change Edit or current patch set of the change |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/edit:message |
| -- |
| |
| Retrieves commit message from change edit. |
| |
| If the `base` parameter is set to true, the returned message is from the |
| revision that the edit is based on. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit:message HTTP/1.0 |
| ---- |
| |
| The commit message is returned as base64 encoded string. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| |
| VGhpcyBpcyBhIGNvbW1pdCBtZXNzYWdlCgpDaGFuZ2UtSWQ6IElhYzhmZGM1MGRlZjFiYWUzYjAz |
| M2JhNjcxZTk0OTBmNzUxNDU5ZGUzCg== |
| ---- |
| |
| Alternatively, if the only value of the Accept request header is |
| `application/json` the commit message is returned as JSON string: |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| |
| )]}' |
| "Subject of the commit message\n\nThis is the body of the commit message.\n\nChange-Id: Iaf1ba916bf843c175673d675bf7f52862f452db9\n" |
| ---- |
| |
| |
| [[publish-edit]] |
| === Publish Change Edit |
| -- |
| 'POST /changes/link:#change-id[\{change-id\}]/edit:publish |
| -- |
| |
| Promotes change edit to a regular patch set. |
| |
| Options can be provided in the request body as a |
| link:#publish-change-edit-input[PublishChangeEditInput] entity. |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit:publish HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "notify": "NONE" |
| } |
| ---- |
| |
| As response "`204 No Content`" is returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| [[rebase-edit]] |
| === Rebase Change Edit |
| -- |
| 'POST /changes/link:#change-id[\{change-id\}]/edit:rebase |
| -- |
| |
| Rebases change edit on top of latest patch set. |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit:rebase HTTP/1.0 |
| ---- |
| |
| When change was rebased on top of latest patch set, response |
| "`204 No Content`" is returned. When change edit is already |
| based on top of the latest patch set, the response |
| "`409 Conflict`" is returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| [[delete-edit]] |
| === Delete Change Edit |
| -- |
| 'DELETE /changes/link:#change-id[\{change-id\}]/edit' |
| -- |
| |
| Deletes change edit. |
| |
| .Request |
| ---- |
| DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit HTTP/1.0 |
| ---- |
| |
| As response "`204 No Content`" is returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| |
| [[reviewer-endpoints]] |
| == Reviewer Endpoints |
| |
| [[list-reviewers]] |
| === List Reviewers |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/reviewers/' |
| -- |
| |
| Lists the reviewers of a change. |
| |
| As result a list of link:#reviewer-info[ReviewerInfo] entries is returned. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/ HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| [ |
| { |
| "approvals": { |
| "Verified": "+1", |
| "Code-Review": "+2" |
| }, |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com" |
| }, |
| { |
| "approvals": { |
| "Verified": " 0", |
| "Code-Review": "-1" |
| }, |
| "_account_id": 1000097, |
| "name": "Jane Roe", |
| "email": "jane.roe@example.com" |
| } |
| ] |
| ---- |
| |
| [[suggest-reviewers]] |
| === Suggest Reviewers |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/suggest_reviewers?q=J&n=5' |
| -- |
| |
| Suggest the reviewers for a given query `q` and result limit `n`. If result |
| limit is not passed, then the default 10 is used. |
| |
| This REST endpoint only suggests accounts that |
| |
| * are active |
| * can see the change |
| * are visible to the calling user |
| * 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. |
| |
| 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. |
| |
| .Request |
| ---- |
| DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe/votes/Code-Review HTTP/1.0 |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe/votes/Code-Review/delete HTTP/1.0 |
| ---- |
| |
| Options can be provided in the request body as a |
| link:#delete-vote-input[DeleteVoteInput] entity. |
| Historically, this method allowed a body in the DELETE, but that behavior is |
| link:https://www.gerritcodereview.com/releases/2.16.md[deprecated,role=external,window=_blank]. |
| In this case, use a POST request instead: |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe/votes/Code-Review/delete HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "notify": "NONE" |
| } |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| |
| [[revision-endpoints]] |
| == Revision Endpoints |
| |
| [[get-commit]] |
| === Get Commit |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/commit' |
| -- |
| |
| Retrieves a parsed commit of a revision. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/commit HTTP/1.0 |
| ---- |
| |
| As response a link:#commit-info[CommitInfo] entity is returned that |
| describes the revision. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "commit": "674ac754f91e64a0efb8087e59a176484bd534d1", |
| "parents": [ |
| { |
| "commit": "1eee2c9d8f352483781e772f35dc586a69ff5646", |
| "subject": "Migrate contributor agreements to All-Projects." |
| } |
| ], |
| "author": { |
| "name": "Shawn O. Pearce", |
| "email": "sop@google.com", |
| "date": "2012-04-24 18:08:08.000000000", |
| "tz": -420 |
| }, |
| "committer": { |
| "name": "Shawn O. Pearce", |
| "email": "sop@google.com", |
| "date": "2012-04-24 18:08:08.000000000", |
| "tz": -420 |
| }, |
| "subject": "Use an EventBus to manage star icons", |
| "message": "Use an EventBus to manage star icons\n\nImage widgets that need to ..." |
| } |
| ---- |
| |
| Adding query parameter `links` (for example `/changes/.../commit?links`) |
| returns a link:#commit-info[CommitInfo] with the additional field `web_links`. |
| |
| [[get-description]] |
| === Get Description |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/description' |
| -- |
| |
| Retrieves the description of a patch set. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/description HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| "Added Documentation" |
| ---- |
| |
| If the patch set does not have a description an empty string is returned. |
| |
| [[set-description]] |
| === Set Description |
| -- |
| 'PUT /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/description' |
| -- |
| |
| Sets the description of a patch set. |
| |
| The new description must be provided in the request body inside a |
| link:#description-input[DescriptionInput] entity. |
| |
| .Request |
| ---- |
| PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/description HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "description": "Added Documentation" |
| } |
| ---- |
| |
| As response the new description is returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| "Added Documentation" |
| ---- |
| |
| [[get-merge-list]] |
| === Get Merge List |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/mergelist' |
| -- |
| |
| Returns the list of commits that are being integrated into a target |
| branch by a merge commit. By default the first parent is assumed to be |
| uninteresting. By using the `parent` option another parent can be set |
| as uninteresting (parents are 1-based). |
| |
| The list of commits is returned as a list of |
| link:#commit-info[CommitInfo] entities. Web links are only included if |
| the `links` option was set. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/7e30d802b890ec8d0be45b1cc2a8ef092bcfc858/mergelist HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| [ |
| { |
| "commit": "674ac754f91e64a0efb8087e59a176484bd534d1", |
| "parents": [ |
| { |
| "commit": "1eee2c9d8f352483781e772f35dc586a69ff5646", |
| "subject": "Migrate contributor agreements to All-Projects." |
| } |
| ], |
| "author": { |
| "name": "Shawn O. Pearce", |
| "email": "sop@google.com", |
| "date": "2012-04-24 18:08:08.000000000", |
| "tz": -420 |
| }, |
| "committer": { |
| "name": "Shawn O. Pearce", |
| "email": "sop@google.com", |
| "date": "2012-04-24 18:08:08.000000000", |
| "tz": -420 |
| }, |
| "subject": "Use an EventBus to manage star icons", |
| "message": "Use an EventBus to manage star icons\n\nImage widgets that need to ..." |
| } |
| ] |
| ---- |
| |
| [[get-revision-actions]] |
| === Get Revision Actions |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/actions' |
| -- |
| |
| Retrieves revision link:#action-info[actions] of the revision of a change. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/actions' HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| |
| { |
| "submit": { |
| "method": "POST", |
| "label": "Submit", |
| "title": "Submit patch set 1 into master", |
| "enabled": true |
| }, |
| "cherrypick": { |
| "method": "POST", |
| "label": "Cherry Pick", |
| "title": "Cherry pick change to a different branch", |
| "enabled": true |
| } |
| } |
| ---- |
| |
| The response is a flat map of possible revision REST endpoint names |
| mapped to their link:#action-info[ActionInfo]. |
| |
| [[get-review]] |
| === Get Review |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/review' |
| -- |
| |
| Retrieves a review of a revision. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/review HTTP/1.0 |
| ---- |
| |
| As response a link:#change-info[ChangeInfo] entity with |
| link:#detailed-labels[detailed labels] and link:#detailed-accounts[ |
| detailed accounts] is returned that describes the review of the |
| revision. The revision for which the review is retrieved is contained |
| in the `revisions` field. In addition the `current_revision` field is |
| set if the revision for which the review is retrieved is the current |
| revision of the change. Please note that the returned labels are always |
| for the current patch set. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "project": "myProject", |
| "branch": "master", |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "subject": "Implementing Feature X", |
| "status": "NEW", |
| "created": "2013-02-01 09:59:32.126000000", |
| "updated": "2013-02-21 11:16:36.775000000", |
| "mergeable": true, |
| "insertions": 34, |
| "deletions": 45, |
| "_number": 3965, |
| "owner": { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com" |
| }, |
| "labels": { |
| "Verified": { |
| "all": [ |
| { |
| "value": 0, |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com" |
| }, |
| { |
| "value": 0, |
| "_account_id": 1000097, |
| "name": "Jane Roe", |
| "email": "jane.roe@example.com" |
| } |
| ], |
| "values": { |
| "-1": "Fails", |
| " 0": "No score", |
| "+1": "Verified" |
| } |
| }, |
| "Code-Review": { |
| "all": [ |
| { |
| "value": -1, |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com" |
| }, |
| { |
| "value": 1, |
| "_account_id": 1000097, |
| "name": "Jane Roe", |
| "email": "jane.roe@example.com" |
| } |
| ] |
| "values": { |
| "-2": "This shall not be submitted", |
| "-1": "I would prefer this is not submitted as is", |
| " 0": "No score", |
| "+1": "Looks good to me, but someone else must approve", |
| "+2": "Looks good to me, approved" |
| } |
| } |
| }, |
| "permitted_labels": { |
| "Verified": [ |
| "-1", |
| " 0", |
| "+1" |
| ], |
| "Code-Review": [ |
| "-2", |
| "-1", |
| " 0", |
| "+1", |
| "+2" |
| ] |
| }, |
| "removable_reviewers": [ |
| { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com" |
| }, |
| { |
| "_account_id": 1000097, |
| "name": "Jane Roe", |
| "email": "jane.roe@example.com" |
| } |
| ], |
| "reviewers": { |
| "REVIEWER": [ |
| { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com" |
| }, |
| { |
| "_account_id": 1000097, |
| "name": "Jane Roe", |
| "email": "jane.roe@example.com" |
| } |
| ] |
| }, |
| "current_revision": "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. |
| |
| Some updates to the attention set occur here. If more than one update should |
| occur, only the first update in the order of the below documentation occurs: |
| |
| If a user is part of remove_from_attention_set, the user will be explicitly |
| removed from the attention set. |
| |
| If a user is part of add_to_attention_set, the user will be explicitly |
| added to the attention set. |
| |
| If the boolean ignore_default_attention_set_rules is set to true, all |
| other rules below will be ignored: |
| |
| The user who created the review is removed from the attention set. |
| |
| If the change is ready for review, the following also apply: |
| |
| When the uploader replies, the owner is added to the attention set. |
| |
| When the owner or uploader replies, all the reviewers are added to |
| the attention set. |
| |
| When neither the owner nor the uploader replies, add the owner and the |
| uploader to the attention set. |
| |
| Then, new reviewers are added to the attention set, and removed reviewers |
| (by becoming CC) are removed from the 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. |
| |
<
|