| 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]. |
| |
| Endpoints |
| --------- |
| |
| [[list-changes]] |
| GET /changes/ (Query Changes) |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| Queries changes visible to the caller. The query string must be |
| provided by the `q` parameter. The `n` parameter can be used to limit |
| the returned results. |
| |
| As result a list of link:#change-info[ChangeInfo] entries is returned. |
| The change output is sorted by the last update time, most recently |
| updated to oldest updated. |
| |
| Query for open changes of watched projects: |
| |
| .Request |
| ---- |
| GET /changes/?q=status:open+is:watched&n=2 HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| { |
| "kind": "gerritcodereview#change", |
| "id": "demo~master~Idaf5e098d70898b7119f6f4af5a6c13343d64b57", |
| "project": "demo", |
| "branch": "master", |
| "change_id": "Idaf5e098d70898b7119f6f4af5a6c13343d64b57", |
| "subject": "One change", |
| "status": "NEW", |
| "created": "2012-07-17 07:18:30.854000000", |
| "updated": "2012-07-17 07:19:27.766000000", |
| "reviewed": true, |
| "mergeable": true, |
| "_sortkey": "001e7057000006dc", |
| "_number": 1756, |
| "owner": { |
| "name": "John Doe" |
| }, |
| }, |
| { |
| "kind": "gerritcodereview#change", |
| "id": "demo~master~I09c8041b5867d5b33170316e2abc34b79bbb8501", |
| "project": "demo", |
| "branch": "master", |
| "change_id": "I09c8041b5867d5b33170316e2abc34b79bbb8501", |
| "subject": "Another change", |
| "status": "NEW", |
| "created": "2012-07-17 07:18:30.884000000", |
| "updated": "2012-07-17 07:18:30.885000000", |
| "mergeable": true, |
| "_sortkey": "001e7056000006dd", |
| "_number": 1757, |
| "owner": { |
| "name": "John Doe" |
| }, |
| "_more_changes": true |
| } |
| ---- |
| |
| If the `n` query parameter is supplied and additional changes exist |
| that match the query beyond the end, the last change object has a |
| `_more_changes: true` JSON field set. Callers can resume a query with |
| the `N` query parameter, supplying the last change's `_sortkey` field |
| as the value. When going in the reverse direction with the `P` query |
| parameter a `_more_changes: true` is put in the first change object if |
| there are results *before* the first change returned. |
| |
| Clients are allowed to specify more than one query by setting the `q` |
| parameter multiple times. In this case the result is an array of |
| arrays, one per query in the same order the queries were given in. |
| |
| .Query for the 25 most recent open changes of the projects that you watch |
| **** |
| get::/changes/?q=status:open+is:watched&n=25 |
| **** |
| |
| Query that retrieves changes for a user's dashboard: |
| |
| .Request |
| ---- |
| GET /changes/?q=is:open+owner:self&q=is:open+reviewer:self+-owner:self&q=is:closed+owner:self+limit:5&o=LABELS HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| [ |
| [ |
| { |
| "kind": "gerritcodereview#change", |
| "id": "demo~master~Idaf5e098d70898b7119f6f4af5a6c13343d64b57", |
| "project": "demo", |
| "branch": "master", |
| "change_id": "Idaf5e098d70898b7119f6f4af5a6c13343d64b57", |
| "subject": "One change", |
| "status": "NEW", |
| "created": "2012-07-17 07:18:30.854000000", |
| "updated": "2012-07-17 07:19:27.766000000", |
| "reviewed": true, |
| "mergeable": true, |
| "_sortkey": "001e7057000006dc", |
| "_number": 1756, |
| "owner": { |
| "name": "John Doe" |
| }, |
| "labels": { |
| "Verified": {}, |
| "Code-Review": {} |
| } |
| } |
| ], |
| [], |
| [] |
| ] |
| ---- |
| |
| .Query the changes for your user dashboard |
| **** |
| get::/changes/?q=is:open+owner:self&q=is:open+reviewer:self+-owner:self&q=is:closed+owner:self+limit:5&o=LABELS |
| **** |
| |
| Additional fields can be obtained by adding `o` parameters, each |
| option requires more database lookups and slows down the query |
| response time to the client so they are generally disabled by |
| default. Optional fields are: |
| |
| [[labels]] |
| -- |
| * `LABELS`: a summary of each label required for submit, and |
| approvers that have granted (or rejected) with that label. |
| -- |
| |
| [[detailed-labels]] |
| -- |
| * `DETAILED_LABELS`: detailed label information, including numeric |
| values of all existing approvals, recognized label values, values |
| permitted to be set by the current user, and reviewers that may be |
| removed by the current user. |
| -- |
| |
| [[current-revision]] |
| -- |
| * `CURRENT_REVISION`: describe the current revision (patch set) |
| of the change, including the commit SHA-1 and URLs to fetch from. |
| -- |
| |
| [[all-revisions]] |
| -- |
| * `ALL_REVISIONS`: describe all revisions, not just current. |
| -- |
| |
| [[current-commit]] |
| -- |
| * `CURRENT_COMMIT`: parse and output all header fields from the |
| commit object, including message. Only valid when the current |
| revision or all revisions are selected. |
| -- |
| |
| [[all-commits]] |
| -- |
| * `ALL_COMMITS`: parse and output all header fields from the |
| output revisions. If only `CURRENT_REVISION` was requested |
| then only the current revision's commit data will be output. |
| -- |
| |
| [[current-files]] |
| -- |
| * `CURRENT_FILES`: list files modified by the commit, including |
| basic line counts inserted/deleted per file. Only valid when |
| the current revision or all revisions are selected. |
| -- |
| |
| [[all-files]] |
| -- |
| * `ALL_FILES`: list files modified by the commit, including |
| basic line counts inserted/deleted per file. If only the |
| `CURRENT_REVISION` was requested the only that commit's |
| modified files will be output. |
| -- |
| |
| [[detailed-accounts]] |
| -- |
| * `DETAILED_ACCOUNTS`: include `_account_id` and `email` fields when |
| referencing accounts. |
| -- |
| |
| .Request |
| ---- |
| GET /changes/?q=97&o=CURRENT_REVISION&o=CURRENT_COMMIT&o=CURRENT_FILES HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| [ |
| { |
| "kind": "gerritcodereview#change", |
| "id": "demo~master~I7ea46d2e2ee5c64c0d807677859cfb7d90b8966a", |
| "project": "gerrit", |
| "branch": "master", |
| "change_id": "I7ea46d2e2ee5c64c0d807677859cfb7d90b8966a", |
| "subject": "Use an EventBus to manage star icons", |
| "status": "NEW", |
| "created": "2012-04-25 00:52:25.580000000", |
| "updated": "2012-04-25 00:52:25.586000000", |
| "mergeable": true, |
| "_sortkey": "001c9bf400000061", |
| "_number": 97, |
| "owner": { |
| "name": "Shawn Pearce" |
| }, |
| "current_revision": "184ebe53805e102605d11f6b143486d15c23a09c", |
| "revisions": { |
| "184ebe53805e102605d11f6b143486d15c23a09c": { |
| "_number": 1, |
| "fetch": { |
| "git": { |
| "url": "git://localhost/gerrit", |
| "ref": "refs/changes/97/97/1" |
| }, |
| "http": { |
| "url": "http://127.0.0.1:8080/gerrit", |
| "ref": "refs/changes/97/97/1" |
| } |
| }, |
| "commit": { |
| "parents": [ |
| { |
| "commit": "1eee2c9d8f352483781e772f35dc586a69ff5646", |
| "subject": "Migrate contributor agreements to All-Projects." |
| } |
| ], |
| "author": { |
| "name": "Shawn O. Pearce", |
| "email": "sop@google.com", |
| "date": "2012-04-24 18:08:08.000000000", |
| "tz": -420 |
| }, |
| "committer": { |
| "name": "Shawn O. Pearce", |
| "email": "sop@google.com", |
| "date": "2012-04-24 18:08:08.000000000", |
| "tz": -420 |
| }, |
| "subject": "Use an EventBus to manage star icons", |
| "message": "Use an EventBus to manage star icons\n\nImage widgets that need to ..." |
| }, |
| "files": { |
| "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeCache.java": { |
| "lines_deleted": 8 |
| }, |
| "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeDetailCache.java": { |
| "lines_inserted": 1 |
| }, |
| "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeScreen.java": { |
| "lines_inserted": 11, |
| "lines_deleted": 19 |
| }, |
| "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeTable.java": { |
| "lines_inserted": 23, |
| "lines_deleted": 20 |
| }, |
| "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarCache.java": { |
| "status": "D", |
| "lines_deleted": 139 |
| }, |
| "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarredChanges.java": { |
| "status": "A", |
| "lines_inserted": 204 |
| }, |
| "gerrit-gwtui/src/main/java/com/google/gerrit/client/ui/Screen.java": { |
| "lines_deleted": 9 |
| } |
| } |
| } |
| } |
| } |
| ] |
| ---- |
| |
| [[get-change]] |
| GET /changes/\{change-id\} (Get Change) |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| Retrieves a change. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940 HTTP/1.0 |
| ---- |
| |
| As response a link:#change-info[ChangeInfo] entity is returned that |
| describes the change. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| { |
| "kind": "gerritcodereview#change", |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "project": "myProject", |
| "branch": "master", |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "subject": "Implementing Feature X", |
| "status": "NEW", |
| "created": "2013-02-01 09:59:32.126000000", |
| "updated": "2013-02-21 11:16:36.775000000", |
| "reviewed": true, |
| "mergeable": true, |
| "_sortkey": "0023412400000f7d", |
| "_number": 3965, |
| "owner": { |
| "name": "John Doe" |
| } |
| } |
| ---- |
| |
| [[get-change-detail]] |
| GET /changes/\{change-id\}/detail (Get Change Detail) |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| Retrieves a change with link:#labels[labels], link:#detailed-labels[ |
| detailed labels] and link:#detailed-accounts[detailed accounts]. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/detail HTTP/1.0 |
| ---- |
| |
| As response a link:#change-info[ChangeInfo] entity is returned that |
| describes the change. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| { |
| "kind": "gerritcodereview#change", |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "project": "myProject", |
| "branch": "master", |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "subject": "Implementing Feature X", |
| "status": "NEW", |
| "created": "2013-02-01 09:59:32.126000000", |
| "updated": "2013-02-21 11:16:36.775000000", |
| "reviewed": true, |
| "mergeable": true, |
| "_sortkey": "0023412400000f7d", |
| "_number": 3965, |
| "owner": { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com" |
| }, |
| "labels": { |
| "Verified": { |
| "all": [ |
| { |
| "value": 0, |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com" |
| }, |
| { |
| "value": 0, |
| "_account_id": 1000097, |
| "name": "Jane Roe", |
| "email": "jane.roe@example.com" |
| } |
| ], |
| "values": { |
| "-1": "Fails", |
| " 0": "No score", |
| "+1": "Verified" |
| } |
| }, |
| "Code-Review": { |
| "recommended": { |
| "_account_id": 1000097, |
| "name": "Jane Roe", |
| "email": "jane.roe@example.com" |
| }, |
| "disliked": { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com" |
| }, |
| "all": [ |
| { |
| "value": -1, |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com" |
| }, |
| { |
| "value": 1, |
| "_account_id": 1000097, |
| "name": "Jane Roe", |
| "email": "jane.roe@example.com" |
| } |
| ] |
| "values": { |
| "-2": "Do not submit", |
| "-1": "I would prefer that you didn\u0027t submit this", |
| " 0": "No score", |
| "+1": "Looks good to me, but someone else must approve", |
| "+2": "Looks good to me, approved" |
| } |
| } |
| }, |
| "permitted_labels": { |
| "Verified": [ |
| "-1", |
| " 0", |
| "+1" |
| ], |
| "Code-Review": [ |
| "-2", |
| "-1", |
| " 0", |
| "+1", |
| "+2" |
| ] |
| }, |
| "removable_reviewers": [ |
| { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com" |
| }, |
| { |
| "_account_id": 1000097, |
| "name": "Jane Roe", |
| "email": "jane.roe@example.com" |
| } |
| ] |
| } |
| ---- |
| |
| [[get-topic]] |
| GET /changes/\{change-id\}/topic (Get 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]] |
| PUT /changes/\{change-id\}/topic (Set Topic) |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| Sets the topic of a change. |
| |
| The new topic must be provided in the request body inside a |
| link:#topic-input[TopicInput] entity. |
| |
| .Request |
| ---- |
| PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic HTTP/1.0 |
| Content-Type: application/json;charset=UTF-8 |
| |
| { |
| "topic": "Documentation" |
| } |
| ---- |
| |
| As response the new topic is returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| "Documentation" |
| ---- |
| |
| If the topic was deleted the response is "`204 No Content`". |
| |
| [[delete-topic]] |
| DELETE /changes/\{change-id\}/topic (Delete Topic) |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| Deletes the topic of a change. |
| |
| The request body does not need to include a link:#topic-input[ |
| TopicInput] entity if no review comment is added. |
| |
| Please note that some proxies prohibit request bodies for DELETE |
| requests. In this case, if you want to specify a commit message, use |
| link:#set-topic[PUT] to delete the topic. |
| |
| .Request |
| ---- |
| DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| [[abandon-change]] |
| POST /changes/\{change-id\}/abandon (Abandon Change) |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| Abandons a change. |
| |
| The request body does not need to include a link:#abandon-input[ |
| AbandonInput] entity if no review comment is added. |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/abandon HTTP/1.0 |
| ---- |
| |
| As response a link:#change-info[ChangeInfo] entity is returned that |
| describes the abandoned change. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| { |
| "kind": "gerritcodereview#change", |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "project": "myProject", |
| "branch": "master", |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "subject": "Implementing Feature X", |
| "status": "ABANDONED", |
| "created": "2013-02-01 09:59:32.126000000", |
| "updated": "2013-02-21 11:16:36.775000000", |
| "reviewed": true, |
| "mergeable": true, |
| "_sortkey": "0023412400000f7d", |
| "_number": 3965, |
| "owner": { |
| "name": "John Doe" |
| } |
| } |
| ---- |
| |
| If the change cannot be abandoned because the change state doesn't |
| allow abandoning of the change, the response is "`409 Conflict`" and |
| the error message is contained in the response body. |
| |
| .Response |
| ---- |
| HTTP/1.1 409 Conflict |
| Content-Disposition: attachment |
| Content-Type: text/plain;charset=UTF-8 |
| |
| change is merged |
| ---- |
| |
| [[restore-change]] |
| POST /changes/\{change-id\}/restore (Restore Change) |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| Restores a change. |
| |
| The request body does not need to include a link:#restore-input[ |
| RestoreInput] entity if no review comment is added. |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/restore HTTP/1.0 |
| ---- |
| |
| As response a link:#change-info[ChangeInfo] entity is returned that |
| describes the restored change. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| { |
| "kind": "gerritcodereview#change", |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "project": "myProject", |
| "branch": "master", |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "subject": "Implementing Feature X", |
| "status": "NEW", |
| "created": "2013-02-01 09:59:32.126000000", |
| "updated": "2013-02-21 11:16:36.775000000", |
| "reviewed": true, |
| "mergeable": true, |
| "_sortkey": "0023412400000f7d", |
| "_number": 3965, |
| "owner": { |
| "name": "John Doe" |
| } |
| } |
| ---- |
| |
| If the change cannot be restored because the change state doesn't |
| allow restoring the change, the response is "`409 Conflict`" and |
| the error message is contained in the response body. |
| |
| .Response |
| ---- |
| HTTP/1.1 409 Conflict |
| Content-Disposition: attachment |
| Content-Type: text/plain;charset=UTF-8 |
| |
| change is new |
| ---- |
| |
| [[revert-change]] |
| POST /changes/\{change-id\}/revert (Revert Change) |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| Reverts a change. |
| |
| The request body does not need to include a link:#revert-input[ |
| RevertInput] entity if no review comment is added. |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revert HTTP/1.0 |
| ---- |
| |
| As response a link:#change-info[ChangeInfo] entity is returned that |
| describes the reverting change. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| { |
| "kind": "gerritcodereview#change", |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "project": "myProject", |
| "branch": "master", |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "subject": "Revert \"Implementing Feature X\"", |
| "status": "NEW", |
| "created": "2013-02-01 09:59:32.126000000", |
| "updated": "2013-02-21 11:16:36.775000000", |
| "reviewed": true, |
| "mergeable": true, |
| "_sortkey": "0023412400000f7d", |
| "_number": 3965, |
| "owner": { |
| "name": "John Doe" |
| } |
| } |
| ---- |
| |
| If the change cannot be reverted because the change state doesn't |
| allow reverting the change, the response is "`409 Conflict`" and |
| the error message is contained in the response body. |
| |
| .Response |
| ---- |
| HTTP/1.1 409 Conflict |
| Content-Disposition: attachment |
| Content-Type: text/plain;charset=UTF-8 |
| |
| change is new |
| ---- |
| |
| [[submit-change]] |
| POST /changes/\{change-id\}/submit (Submit Change) |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| Submits a change. |
| |
| The request body only needs to include a link:#submit-input[ |
| SubmitInput] entity if the request should wait for the merge to |
| complete. |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/submit HTTP/1.0 |
| Content-Type: application/json;charset=UTF-8 |
| |
| { |
| "wait_for_merge": true |
| } |
| ---- |
| |
| As response a link:#change-info[ChangeInfo] entity is returned that |
| describes the submitted/merged change. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| { |
| "kind": "gerritcodereview#change", |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "project": "myProject", |
| "branch": "master", |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "subject": "Implementing Feature X", |
| "status": "MERGED", |
| "created": "2013-02-01 09:59:32.126000000", |
| "updated": "2013-02-21 11:16:36.775000000", |
| "reviewed": true, |
| "mergeable": true, |
| "_sortkey": "0023412400000f7d", |
| "_number": 3965, |
| "owner": { |
| "name": "John Doe" |
| } |
| } |
| ---- |
| |
| If the change cannot be submitted because the submit rule doesn't allow |
| submitting the change, the response is "`409 Conflict`" and the error |
| message is contained in the response body. |
| |
| .Response |
| ---- |
| HTTP/1.1 409 Conflict |
| Content-Disposition: attachment |
| Content-Type: text/plain;charset=UTF-8 |
| |
| blocked by Verified |
| ---- |
| |
| |
| [[ids]] |
| IDs |
| --- |
| |
| [[change-id]] |
| \{change-id\} |
| ~~~~~~~~~~~~~ |
| Identifier that uniquely identifies one change. |
| |
| This can be: |
| |
| * an ID of the change in the format "'$$<project>~<branch>~<Change-Id>$$'", |
| where for the branch the `refs/heads/` prefix can be omitted |
| ("$$myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940$$") |
| * a Change-Id if it uniquely identifies one change |
| ("I8473b95934b5732ac55d26311a706c9c2bde9940") |
| * a legacy numeric change ID ("4247") |
| |
| |
| [[json-entities]] |
| JSON Entities |
| ------------- |
| |
| [[abandon-input]] |
| AbandonInput |
| ~~~~~~~~~~~~ |
| The `AbandonInput` entity contains information for abandoning a change. |
| |
| [options="header",width="50%",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`message` |optional| |
| Message to be added as review comment to the change when abandoning the |
| change. |
| |=========================== |
| |
| [[account-info]] |
| AccountInfo |
| ~~~~~~~~~~~ |
| The `AccountInfo` entity contains information about an account. |
| |
| [options="header",width="50%",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`_account_id` ||The numeric ID of the account. |
| |`name` |optional|The full name of the user. + |
| Only set if link:#detailed-accounts[detailed account information] is |
| requested. |
| |`email` |optional| |
| The email address the user prefers to be contacted through. + |
| Only set if link:#detailed-accounts[detailed account information] is |
| requested. |
| |=========================== |
| |
| [[approval-info]] |
| ApprovalInfo |
| ~~~~~~~~~~~~ |
| The `ApprovalInfo` entity contains information about an approval from a |
| user for a label on a change. |
| |
| `ApprovalInfo` has the same fields as link:#account-info[AccountInfo]. |
| In addition `ApprovalInfo` has the following fields: |
| |
| [options="header",width="50%",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`value` ||The vote that the user has given for the label. |
| |=========================== |
| |
| [[change-info]] |
| ChangeInfo |
| ~~~~~~~~~~ |
| The `ChangeInfo` entity contains information about a change. |
| |
| [options="header",width="50%",cols="1,^1,5"] |
| |================================== |
| |Field Name ||Description |
| |`kind` ||`gerritcodereview#change` |
| |`id` || |
| The ID of the change in the format "'<project>\~<branch>~<Change-Id>'", |
| where project, branch and Change-Id are URL encoded. For branch the |
| `refs/heads/` prefix is omitted. |
| |`project` ||The name of the project. |
| |`branch` || |
| The name of the target branch. + |
| The `refs/heads/` prefix is omitted. |
| |`topic` |optional|The topic to which this change belongs. |
| |`change_id` ||The Change-Id of the change. |
| |`subject` || |
| The subject of the change (header line of the commit message). |
| |`status` || |
| The status of the change (`NEW`, `SUBMITTED`, `MERGED`, `ABANDONED`, |
| `DRAFT`). |
| |`created` || |
| The link:rest-api.html#timestamp[timestamp] of when the change was |
| created. |
| |`updated` || |
| The link:rest-api.html#timestamp[timestamp] of when the change was last |
| updated. |
| |`starred` |not set if `false`| |
| Whether the calling user has starred this change. |
| |`reviewed` |not set if `false`| |
| Whether the change was reviewed by the calling user. |
| |`mergeable` ||Whether the change is mergeable. |
| |`_sortkey` ||The sortkey of the change. |
| |`_number` ||The legacy numeric ID of the change. |
| |`owner` || |
| The owner of the change as an link:#account-info[AccountInfo] entity. |
| |`labels` |optional| |
| The labels of the change as a map that maps the label names to |
| link:#label-info[LabelInfo] entries. + |
| Only set if link:#labels[labels] or link:#detailed-labels[detailed |
| labels] are requested. |
| |`permitted_labels` |optional| |
| A map of the permitted labels that maps a label name to the list of |
| values that are allowed for that label. + |
| Only set if link:#detailed-labels[detailed labels] are requested. |
| |`removable_reviewers`|optional| |
| The reviewers that can be removed by the calling user as a list of |
| link:#account-info[AccountInfo] entities. + |
| Only set if link:#detailed-labels[detailed labels] are requested. |
| |`current_revision` |optional| |
| The commit ID of the current patch set of this change. + |
| Only set if link:#current-revision[the current revision] is requested |
| or if link:#all-revisions[all revisions] are requested. |
| |`revisions` |optional| |
| All patch sets of this changes as a map that maps the commit ID of the |
| patch set to a link:#revision-info[RevisionInfo] entity. + |
| Only set if link:#all-revisions[all revisions] are requested. |
| |`_more_changes` |optional, not set if `false`| |
| Whether the query would deliver more results if not limited. + |
| Only set on either the last or the first change that is returned. |
| |================================== |
| |
| [[commit-info]] |
| CommitInfo |
| ~~~~~~~~~~ |
| The `CommitInfo` entity contains information about a commit. |
| |
| [options="header",width="50%",cols="1,6"] |
| |========================== |
| |Field Name |Description |
| |`commit` |The commit ID. |
| |`parent` | |
| The parent commits of this commit as a list of |
| link:#commit-info[CommitInfo] entities. |
| |`author` |The author of the commit as a |
| link:#git-person-info[GitPersonInfo] entity. |
| |`committer` |The committer of the commit as a |
| link:#git-person-info[GitPersonInfo] entity. |
| |`subject` | |
| The subject of the commit (header line of the commit message). |
| |`message` |The commit message. |
| |========================== |
| |
| [[fetch-info]] |
| FetchInfo |
| ~~~~~~~~~ |
| The `FetchInfo` entity contains information about how to fetch a patch |
| set via a certain protocol. |
| |
| [options="header",width="50%",cols="1,6"] |
| |========================== |
| |Field Name |Description |
| |`url` |The URL of the project. |
| |`ref` |The ref of the patch set. |
| |========================== |
| |
| [[file-info]] |
| FileInfo |
| ~~~~~~~~ |
| The `FileInfo` entity contains information about a file in a patch set. |
| |
| [options="header",width="50%",cols="1,^1,5"] |
| |============================= |
| |Field Name ||Description |
| |`status` |optional| |
| The status of the file ("`A`"=Added, "`D`"=Deleted, "`R`"=Renamed, |
| "`C`"=Copied, "`W`"=Rewritten). + |
| Not set if the file was Modified ("`M`"). |
| |`binary` |not set if `false`|Whether the file is binary. |
| |`old_path` |optional| |
| The old file path. + |
| Only set if file was renamed or copied. |
| |`lines_inserted`|optional| |
| Number of inserted lines. + |
| Not set for binary files or if no lines were inserted. |
| |`lines_deleted` |optional| |
| Number of deleted lines. + |
| Not set for binary files or if no lines were deleted. |
| |============================= |
| |
| [[git-person-info]] |
| GitPersonInfo |
| ~~~~~~~~~~~~~ |
| The `GitPersonInfo` entity contains information about the |
| author/committer of a commit. |
| |
| [options="header",width="50%",cols="1,6"] |
| |========================== |
| |Field Name |Description |
| |`name` |The name of the author/committer. |
| |`email` |The email address of the author/committer. |
| |`date` |The link:rest-api.html#timestamp[timestamp] of when |
| this identity was constructed. |
| |`tz` |The timezone offset from UTC of when this identity was |
| constructed. |
| |========================== |
| |
| [[label-info]] |
| LabelInfo |
| ~~~~~~~~~ |
| The `LabelInfo` entity contains information about a label on a change. |
| |
| [options="header",width="50%",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`approved` |optional|The user who approved this label on the change |
| as a link:#account-info[AccountInfo] entity. + |
| Only set if link:#labels[labels] are requested. |
| |`rejected` |optional|The user who rejected this label on the change |
| as a link:#account-info[AccountInfo] entity. + |
| Only set if link:#labels[labels] are requested. |
| |`recommended` |optional|The user who recommended this label on the |
| change as a link:#account-info[AccountInfo] entity. + |
| Only set if link:#labels[labels] are requested. |
| |`disliked` |optional|The user who disliked this label on the change |
| as a link:#account-info[AccountInfo] entity. + |
| Only set if link:#labels[labels] are requested. |
| |`value` |optional|The voting value of the user who |
| recommended/disliked this label on the change if it is not |
| "`+1`"/"`-1`". + |
| Only set if link:#labels[labels] are requested. |
| |`optional` |not set if `false`| |
| Whether the label is optional. Optional means the label may be set, but |
| it's neither necessary for submission nor does it block submission if |
| set. |
| |`all` |optional|List of all approvals for this label as a list |
| of link:#approval-info[ApprovalInfo] entities. + |
| Only set if link:#detailed-labels[detailed labels] are requested. |
| |`values` |optional|A map of all values that are allowed for this |
| label. The map maps the values ("`-2`", "`-1`", " `0`", "`+1`", "`+2`") |
| to the value descriptions. + |
| Only set if link:#detailed-labels[detailed labels] are requested. |
| |=========================== |
| |
| [[restore-input]] |
| RestoreInput |
| ~~~~~~~~~~~~ |
| The `RestoreInput` entity contains information for restoring a change. |
| |
| [options="header",width="50%",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`message` |optional| |
| Message to be added as review comment to the change when restoring the |
| change. |
| |=========================== |
| |
| [[revert-input]] |
| RevertInput |
| ~~~~~~~~~~~ |
| The `RevertInput` entity contains information for reverting a change. |
| |
| [options="header",width="50%",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`message` |optional| |
| Message to be added as review comment to the change when reverting the |
| change. |
| |=========================== |
| |
| [[revision-info]] |
| RevisionInfo |
| ~~~~~~~~~~~~ |
| The `RevisionInfo` entity contains information about a patch set. |
| |
| [options="header",width="50%",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`draft` |not set if `false`|Whether the patch set is a draft. |
| |`_number` ||The patch set number. |
| |`fetch` || |
| Information about how to fetch this patch set. The fetch information is |
| provided as a map that maps the protocol name ("`git`", "`http`", |
| "`ssh`") to link:#fetch-info[FetchInfo] entities. |
| |`commit` ||The commit of the patch set as |
| link:#commit-info[CommitInfo] entity. |
| |`files` || |
| The files of the patch set as a map that maps the file names to |
| link:#file-info[FileInfo] entities. |
| |=========================== |
| |
| [[submit-input]] |
| SubmitInput |
| ~~~~~~~~~~~ |
| The `SubmitInput` entity contains information for submitting a change. |
| |
| [options="header",width="50%",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`wait_for_merge`|`false` if not set| |
| Whether the request should wait for the merge to complete. + |
| If `false` the request returns immediately after the change has been |
| added to the merge queue and the caller can't know whether the change |
| could be merged successfully. |
| |=========================== |
| |
| [[topic-input]] |
| TopicInput |
| ~~~~~~~~~~ |
| The `TopicInput` entity contains information for setting a topic. |
| |
| [options="header",width="50%",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`topic` |optional|The topic. + |
| The topic will be deleted if not set. |
| |`message` |optional| |
| Message to be added as review comment to the change when setting the |
| topic. |
| |=========================== |
| |
| |
| GERRIT |
| ------ |
| Part of link:index.html[Gerrit Code Review] |
