| = 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 info link:#change-info[ChangeInfo] entity must be provided in the |
| request body. Only the following attributes are honored: `project`, |
| `branch`, `subject`, `status` and `topic`. The first three attributes are |
| mandatory. Valid values for status are: `DRAFT` and `NEW`. |
| |
| .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" : "DRAFT" |
| } |
| ---- |
| |
| As response a link:#change-info[ChangeInfo] entity is returned that describes |
| the resulting change. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 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": "DRAFT", |
| "created": "2014-05-05 07:15:44.639000000", |
| "updated": "2014-05-05 07:15:44.639000000", |
| "mergeable": true, |
| "insertions": 0, |
| "deletions": 0, |
| "_number": 4711, |
| "owner": { |
| "name": "John Doe" |
| } |
| } |
| ---- |
| |
| [[list-changes]] |
| === Query Changes |
| -- |
| 'GET /changes/' |
| -- |
| |
| Queries changes visible to the caller. The |
| link:user-search.html#_search_operators[query string] must be provided |
| by the `q` parameter. The `n` parameter can be used to limit the |
| returned results. |
| |
| As result a list of link:#change-info[ChangeInfo] entries is returned. |
| The change output is sorted by the last update time, most recently |
| updated to oldest updated. |
| |
| Query for open changes of watched projects: |
| |
| .Request |
| ---- |
| GET /changes/?q=status:open+is:watched&n=2 HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| [ |
| { |
| "id": "demo~master~Idaf5e098d70898b7119f6f4af5a6c13343d64b57", |
| "project": "demo", |
| "branch": "master", |
| "change_id": "Idaf5e098d70898b7119f6f4af5a6c13343d64b57", |
| "subject": "One change", |
| "status": "NEW", |
| "created": "2012-07-17 07:18:30.854000000", |
| "updated": "2012-07-17 07:19:27.766000000", |
| "mergeable": true, |
| "insertions": 26, |
| "deletions": 10, |
| "_number": 1756, |
| "owner": { |
| "name": "John Doe" |
| }, |
| }, |
| { |
| "id": "demo~master~I09c8041b5867d5b33170316e2abc34b79bbb8501", |
| "project": "demo", |
| "branch": "master", |
| "change_id": "I09c8041b5867d5b33170316e2abc34b79bbb8501", |
| "subject": "Another change", |
| "status": "NEW", |
| "created": "2012-07-17 07:18:30.884000000", |
| "updated": "2012-07-17 07:18:30.885000000", |
| "mergeable": true, |
| "insertions": 12, |
| "deletions": 18, |
| "_number": 1757, |
| "owner": { |
| "name": "John Doe" |
| }, |
| "_more_changes": true |
| } |
| ] |
| ---- |
| |
| If the `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. |
| |
| The `S` or `start` query parameter can be supplied to skip a number |
| of changes from the list. |
| |
| Clients are allowed to specify more than one query by setting the `q` |
| parameter multiple times. In this case the result is an array of |
| arrays, one per query in the same order the queries were given in. |
| |
| .Query for the 25 most recent open changes of the projects that you watch |
| **** |
| get::/changes/?q=status:open+is:watched&n=25 |
| **** |
| |
| Query that retrieves changes for a user's dashboard: |
| |
| .Request |
| ---- |
| GET /changes/?q=is:open+owner:self&q=is:open+reviewer:self+-owner:self&q=is:closed+owner:self+limit:5&o=LABELS HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| [ |
| [ |
| { |
| "id": "demo~master~Idaf5e098d70898b7119f6f4af5a6c13343d64b57", |
| "project": "demo", |
| "branch": "master", |
| "change_id": "Idaf5e098d70898b7119f6f4af5a6c13343d64b57", |
| "subject": "One change", |
| "status": "NEW", |
| "created": "2012-07-17 07:18:30.854000000", |
| "updated": "2012-07-17 07:19:27.766000000", |
| "mergeable": true, |
| "insertions": 4, |
| "deletions": 7, |
| "_number": 1756, |
| "owner": { |
| "name": "John Doe" |
| }, |
| "labels": { |
| "Verified": {}, |
| "Code-Review": {} |
| } |
| } |
| ], |
| [], |
| [] |
| ] |
| ---- |
| |
| .Query the changes for your user dashboard |
| **** |
| get::/changes/?q=is:open+owner:self&q=is:open+reviewer:self+-owner:self&q=is:closed+owner:self+limit:5&o=LABELS |
| **** |
| |
| 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. |
| -- |
| |
| [[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. |
| -- |
| |
| [[draft_comments]] |
| -- |
| * `DRAFT_COMMENTS`: include the `has_draft_comments` field 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, 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, 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. |
| -- |
| |
| [[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 the caller is |
| authenticated and has commented on the current revision. |
| -- |
| |
| [[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. |
| -- |
| |
| .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": { |
| "_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 |
| }, |
| "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeDetailCache.java": { |
| "lines_inserted": 1 |
| }, |
| "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeScreen.java": { |
| "lines_inserted": 11, |
| "lines_deleted": 19 |
| }, |
| "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeTable.java": { |
| "lines_inserted": 23, |
| "lines_deleted": 20 |
| }, |
| "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarCache.java": { |
| "status": "D", |
| "lines_deleted": 139 |
| }, |
| "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarredChanges.java": { |
| "status": "A", |
| "lines_inserted": 204 |
| }, |
| "gerrit-gwtui/src/main/java/com/google/gerrit/client/ui/Screen.java": { |
| "lines_deleted": 9 |
| } |
| } |
| } |
| } |
| } |
| ] |
| ---- |
| |
| [[get-change]] |
| === Get Change |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]' |
| -- |
| |
| Retrieves a change. |
| |
| Additional fields can be obtained by adding `o` parameters, each |
| option requires more database lookups and slows down the query |
| response time to the client so they are generally disabled by |
| default. Fields are described in link:#list-changes[Query Changes]. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940 HTTP/1.0 |
| ---- |
| |
| As response a link:#change-info[ChangeInfo] entity is returned that |
| describes the change. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "project": "myProject", |
| "branch": "master", |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "subject": "Implementing Feature X", |
| "status": "NEW", |
| "created": "2013-02-01 09:59:32.126000000", |
| "updated": "2013-02-21 11:16:36.775000000", |
| "mergeable": true, |
| "insertions": 34, |
| "deletions": 101, |
| "_number": 3965, |
| "owner": { |
| "name": "John Doe" |
| } |
| } |
| ---- |
| |
| [[get-change-detail]] |
| === Get Change Detail |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/detail' |
| -- |
| |
| Retrieves a change with link:#labels[labels], link:#detailed-labels[ |
| detailed labels], link:#detailed-accounts[detailed accounts], and |
| link:#messages[messages]. |
| |
| Additional fields can be obtained by adding `o` parameters, each |
| option requires more database lookups and slows down the query |
| response time to the client so they are generally disabled by |
| default. Fields are described in link:#list-changes[Query Changes]. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/detail HTTP/1.0 |
| ---- |
| |
| As response a link:#change-info[ChangeInfo] entity is returned that |
| describes the change. This response will contain all votes for each |
| label and include one combined vote. The combined label vote is |
| calculated in the following order (from highest to lowest): |
| REJECTED > APPROVED > DISLIKED > RECOMMENDED. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "project": "myProject", |
| "branch": "master", |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "subject": "Implementing Feature X", |
| "status": "NEW", |
| "created": "2013-02-01 09:59:32.126000000", |
| "updated": "2013-02-21 11:16:36.775000000", |
| "mergeable": true, |
| "insertions": 126, |
| "deletions": 11, |
| "_number": 3965, |
| "owner": { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com", |
| "username": "jdoe" |
| }, |
| "labels": { |
| "Verified": { |
| "all": [ |
| { |
| "value": 0, |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com", |
| "username": "jdoe" |
| }, |
| { |
| "value": 0, |
| "_account_id": 1000097, |
| "name": "Jane Roe", |
| "email": "jane.roe@example.com", |
| "username": "jroe" |
| } |
| ], |
| "values": { |
| "-1": "Fails", |
| " 0": "No score", |
| "+1": "Verified" |
| } |
| }, |
| "Code-Review": { |
| "disliked": { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com", |
| "username": "jdoe" |
| }, |
| "all": [ |
| { |
| "value": -1, |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com", |
| "username": "jdoe" |
| }, |
| { |
| "value": 1, |
| "_account_id": 1000097, |
| "name": "Jane Roe", |
| "email": "jane.roe@example.com", |
| "username": "jroe" |
| } |
| ] |
| "values": { |
| "-2": "This shall not be merged", |
| "-1": "I would prefer this is not merged as is", |
| " 0": "No score", |
| "+1": "Looks good to me, but someone else must approve", |
| "+2": "Looks good to me, approved" |
| } |
| } |
| }, |
| "permitted_labels": { |
| "Verified": [ |
| "-1", |
| " 0", |
| "+1" |
| ], |
| "Code-Review": [ |
| "-2", |
| "-1", |
| " 0", |
| "+1", |
| "+2" |
| ] |
| }, |
| "removable_reviewers": [ |
| { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com", |
| "username": "jdoe" |
| }, |
| { |
| "_account_id": 1000097, |
| "name": "Jane Roe", |
| "email": "jane.roe@example.com", |
| "username": "jroe" |
| } |
| ], |
| "messages": [ |
| { |
| "id": "YH-egE", |
| "author": { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com", |
| "username": "jdoe" |
| }, |
| "updated": "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" |
| }, |
| "updated": "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-topic]] |
| === Get Topic |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/topic' |
| -- |
| |
| Retrieves the topic of a change. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| "Documentation" |
| ---- |
| |
| If the change does not have a topic an empty string is returned. |
| |
| [[set-topic]] |
| === Set Topic |
| -- |
| 'PUT /changes/link:#change-id[\{change-id\}]/topic' |
| -- |
| |
| Sets the topic of a change. |
| |
| The new topic must be provided in the request body inside a |
| link:#topic-input[TopicInput] entity. |
| |
| .Request |
| ---- |
| PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "topic": "Documentation" |
| } |
| ---- |
| |
| As response the new topic is returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| "Documentation" |
| ---- |
| |
| If the topic was deleted the response is "`204 No Content`". |
| |
| [[delete-topic]] |
| === Delete Topic |
| -- |
| 'DELETE /changes/link:#change-id[\{change-id\}]/topic' |
| -- |
| |
| Deletes the topic of a change. |
| |
| The request body does not need to include a link:#topic-input[ |
| TopicInput] entity if no review comment is added. |
| |
| Please note that some proxies prohibit request bodies for DELETE |
| requests. In this case, if you want to specify a commit message, use |
| link:#set-topic[PUT] to delete the topic. |
| |
| .Request |
| ---- |
| DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| [[abandon-change]] |
| === Abandon Change |
| -- |
| 'POST /changes/link:#change-id[\{change-id\}]/abandon' |
| -- |
| |
| Abandons a change. |
| |
| The request body does not need to include a link:#abandon-input[ |
| AbandonInput] entity if no review comment is added. |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/abandon HTTP/1.0 |
| ---- |
| |
| As response a link:#change-info[ChangeInfo] entity is returned that |
| describes the abandoned change. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "project": "myProject", |
| "branch": "master", |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "subject": "Implementing Feature X", |
| "status": "ABANDONED", |
| "created": "2013-02-01 09:59:32.126000000", |
| "updated": "2013-02-21 11:16:36.775000000", |
| "mergeable": true, |
| "insertions": 3, |
| "deletions": 310, |
| "_number": 3965, |
| "owner": { |
| "name": "John Doe" |
| } |
| } |
| ---- |
| |
| If the change cannot be abandoned because the change state doesn't |
| allow abandoning of the change, the response is "`409 Conflict`" and |
| the error message is contained in the response body. |
| |
| .Response |
| ---- |
| HTTP/1.1 409 Conflict |
| Content-Disposition: attachment |
| Content-Type: text/plain; charset=UTF-8 |
| |
| change is merged |
| ---- |
| |
| [[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": { |
| "_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. |
| ---- |
| |
| [[revert-change]] |
| === Revert Change |
| -- |
| 'POST /changes/link:#change-id[\{change-id\}]/revert' |
| -- |
| |
| Reverts a change. |
| |
| The request body does not need to include a link:#revert-input[ |
| RevertInput] entity if no review comment is added. |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~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 |
| |
| )]}' |
| { |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "project": "myProject", |
| "branch": "master", |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "subject": "Revert \"Implementing Feature X\"", |
| "status": "NEW", |
| "created": "2013-02-01 09:59:32.126000000", |
| "updated": "2013-02-21 11:16:36.775000000", |
| "mergeable": true, |
| "insertions": 6, |
| "deletions": 4, |
| "_number": 3965, |
| "owner": { |
| "name": "John Doe" |
| } |
| } |
| ---- |
| |
| If the change cannot be reverted because the change state doesn't |
| allow reverting the change, the response is "`409 Conflict`" and |
| the error message is contained in the response body. |
| |
| .Response |
| ---- |
| HTTP/1.1 409 Conflict |
| Content-Disposition: attachment |
| Content-Type: text/plain; charset=UTF-8 |
| |
| change is new |
| ---- |
| |
| [[submit-change]] |
| === Submit Change |
| -- |
| 'POST /changes/link:#change-id[\{change-id\}]/submit' |
| -- |
| |
| Submits a change. |
| |
| The request body only needs to include a link:#submit-input[ |
| SubmitInput] entity if 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 |
| |
| )]}' |
| { |
| "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", |
| "_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 |
| ---- |
| |
| [[publish-draft-change]] |
| === Publish Draft Change |
| -- |
| 'POST /changes/link:#change-id[\{change-id\}]/publish' |
| -- |
| |
| Publishes a draft change. |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/publish HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| [[delete-draft-change]] |
| === Delete Draft Change |
| -- |
| 'DELETE /changes/link:#change-id[\{change-id\}]' |
| -- |
| |
| Deletes a draft change. |
| |
| .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 |
| ---- |
| |
| [[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. |
| |
| 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", |
| "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" |
| } |
| ] |
| } |
| ---- |
| |
| [[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 ..." |
| }, |
| } |
| ---- |
| |
| [[put-edit-file]] |
| === Change file content in Change Edit |
| -- |
| 'PUT /changes/link:#change-id[\{change-id\}]/edit/path%2fto%2ffile |
| -- |
| |
| Put content of a file to a change edit. |
| |
| .Request |
| ---- |
| PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit/foo HTTP/1.0 |
| ---- |
| |
| When change edit doesn't exist for this change yet it is created. When file |
| content isn't provided, it is wiped out for that file. As response |
| "`204 No Content`" is returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| [[post-edit]] |
| === Restore file content or rename files in Change Edit |
| -- |
| 'POST /changes/link:#change-id[\{change-id\}]/edit |
| -- |
| |
| Creates empty change edit, restores file content or renames files in change |
| edit. The request body needs to include a |
| link:#change-edit-input[ChangeEditInput] entity when a file within change |
| edit should be restored or old and new file names to rename a file. |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "restore_path": "foo" |
| } |
| ---- |
| |
| or for rename: |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "old_path": "foo", |
| "new_path": "bar" |
| } |
| ---- |
| |
| When change edit doesn't exist for this change yet it is created. When path |
| and restore flag are provided in request body, this file is restored. When |
| old and new file names are provided, the file is renamed. As response |
| "`204 No Content`" is returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| [[put-change-edit-message]] |
| === Change commit message in Change Edit |
| -- |
| 'PUT /changes/link:#change-id[\{change-id\}]/edit:message |
| -- |
| |
| Modify commit message. The request body needs to include a |
| link:#change-edit-message-input[ChangeEditMessageInput] |
| entity. |
| |
| .Request |
| ---- |
| PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit:message HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "message": "New commit message\n\nChange-Id: I10394472cbd17dd12454f229e4f6de00b143a444" |
| } |
| ---- |
| |
| If a change edit doesn't exist for this change yet, it is created. As |
| response "`204 No Content`" is returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| [[delete-edit-file]] |
| === Delete file in Change Edit |
| -- |
| 'DELETE /changes/link:#change-id[\{change-id\}]/edit/path%2fto%2ffile' |
| -- |
| |
| Deletes a file from a change edit. This deletes the file from the repository |
| completely. This is not the same as reverting or restoring a file to its |
| previous contents. |
| |
| .Request |
| ---- |
| DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit/foo HTTP/1.0 |
| ---- |
| |
| When change edit doesn't exist for this change yet it is created. |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| [[get-edit-file]] |
| === Retrieve file content from Change Edit |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/edit/path%2fto%2ffile |
| -- |
| |
| Retrieves content of a file from a change edit. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit/foo HTTP/1.0 |
| ---- |
| |
| The content of the file is returned as text encoded inside base64. |
| The Content-Type header will always be `text/plain` reflecting the |
| outer base64 encoding. A Gerrit-specific `X-FYI-Content-Type` header |
| can be examined to find the server detected content type of the file. |
| |
| When the specified file was deleted in the change edit |
| "`204 No Content`" is returned. |
| |
| If only the content type is required, callers should use HEAD to |
| avoid downloading the encoded file contents. |
| |
| .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. |
| |
| .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. |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit:publish HTTP/1.0 |
| ---- |
| |
| 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. |
| |
| 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" |
| } |
| }, |
| { |
| "group": { |
| "id": "4fd581c0657268f2bdcc26699fbf9ddb76e3a279", |
| "name": "Joiner" |
| } |
| } |
| ] |
| ---- |
| |
| [[get-reviewer]] |
| === Get Reviewer |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/reviewers/link:rest-api-accounts.html#account-id[\{account-id\}]' |
| -- |
| |
| Retrieves a reviewer of a change. |
| |
| As response a link:#reviewer-info[ReviewerInfo] entity is returned that |
| describes the reviewer. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/john.doe@example.com HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "approvals": { |
| "Verified": "+1", |
| "Code-Review": "+2" |
| }, |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com" |
| } |
| ---- |
| |
| [[add-reviewer]] |
| === Add Reviewer |
| -- |
| 'POST /changes/link:#change-id[\{change-id\}]/reviewers' |
| -- |
| |
| Adds one user or all members of one group as reviewer to the change. |
| |
| The reviewer to be added to the change must be provided in the request |
| body as a link:#reviewer-input[ReviewerInput] entity. |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "reviewer": "john.doe@example.com" |
| } |
| ---- |
| |
| As response an link:#add-reviewer-result[AddReviewerResult] entity is |
| returned that describes the newly added reviewers. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "reviewers": [ |
| { |
| "approvals": { |
| "Verified": " 0", |
| "Code-Review": " 0" |
| }, |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com" |
| } |
| ] |
| } |
| ---- |
| |
| If a group is specified, adding the group members as reviewers is an |
| atomic operation. This means if an error is returned, none of the |
| members are added as reviewer. |
| |
| If a group with many members is added as reviewer a confirmation may be |
| required. |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "reviewer": "MyProjectVerifiers" |
| } |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "error": "The group My Group has 15 members. Do you want to add them all as reviewers?", |
| "confirm": true |
| } |
| ---- |
| |
| To confirm the addition of the reviewers, resend the request with the |
| `confirmed` flag being set. |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "reviewer": "MyProjectVerifiers", |
| "confirmed": true |
| } |
| ---- |
| |
| [[delete-reviewer]] |
| === Delete Reviewer |
| -- |
| 'DELETE /changes/link:#change-id[\{change-id\}]/reviewers/link:rest-api-accounts.html#account-id[\{account-id\}]' |
| -- |
| |
| Deletes a reviewer from a change. |
| |
| .Request |
| ---- |
| DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| [[revision-endpoints]] |
| == Revision Endpoints |
| |
| [[get-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 |
| |
| )]}' |
| { |
| "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-revision-actions]] |
| === Get Revision Actions |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/actions' |
| -- |
| |
| Retrieves revision link:#action-info[actions] of the revision of a change. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/actions' HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| |
| { |
| "submit": { |
| "method": "POST", |
| "label": "Submit", |
| "title": "Submit patch set 1 into master", |
| "enabled": true |
| }, |
| "cherrypick": { |
| "method": "POST", |
| "label": "Cherry Pick", |
| "title": "Cherry pick change to a different branch", |
| "enabled": true |
| } |
| } |
| ---- |
| |
| The response is a flat map of possible revision actions mapped to their |
| link:#action-info[ActionInfo]. |
| |
| [[get-review]] |
| === Get Review |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/review' |
| -- |
| |
| Retrieves a review of a revision. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/review HTTP/1.0 |
| ---- |
| |
| As response a link:#change-info[ChangeInfo] entity with |
| link:#detailed-labels[detailed labels] and link:#detailed-accounts[ |
| detailed accounts] is returned that describes the review of the |
| revision. The revision for which the review is retrieved is contained |
| in the `revisions` field. In addition the `current_revision` field is |
| set if the revision for which the review is retrieved is the current |
| revision of the change. Please note that the returned labels are always |
| for the current patch set. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "project": "myProject", |
| "branch": "master", |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940", |
| "subject": "Implementing Feature X", |
| "status": "NEW", |
| "created": "2013-02-01 09:59:32.126000000", |
| "updated": "2013-02-21 11:16:36.775000000", |
| "mergeable": true, |
| "insertions": 34, |
| "deletions": 45, |
| "_number": 3965, |
| "owner": { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com" |
| }, |
| "labels": { |
| "Verified": { |
| "all": [ |
| { |
| "value": 0, |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com" |
| }, |
| { |
| "value": 0, |
| "_account_id": 1000097, |
| "name": "Jane Roe", |
| "email": "jane.roe@example.com" |
| } |
| ], |
| "values": { |
| "-1": "Fails", |
| " 0": "No score", |
| "+1": "Verified" |
| } |
| }, |
| "Code-Review": { |
| "all": [ |
| { |
| "value": -1, |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com" |
| }, |
| { |
| "value": 1, |
| "_account_id": 1000097, |
| "name": "Jane Roe", |
| "email": "jane.roe@example.com" |
| } |
| ] |
| "values": { |
| "-2": "This shall not be merged", |
| "-1": "I would prefer this is not merged as is", |
| " 0": "No score", |
| "+1": "Looks good to me, but someone else must approve", |
| "+2": "Looks good to me, approved" |
| } |
| } |
| }, |
| "permitted_labels": { |
| "Verified": [ |
| "-1", |
| " 0", |
| "+1" |
| ], |
| "Code-Review": [ |
| "-2", |
| "-1", |
| " 0", |
| "+1", |
| "+2" |
| ] |
| }, |
| "removable_reviewers": [ |
| { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com" |
| }, |
| { |
| "_account_id": 1000097, |
| "name": "Jane Roe", |
| "email": "jane.roe@example.com" |
| } |
| ], |
| "current_revision": "674ac754f91e64a0efb8087e59a176484bd534d1", |
| "revisions": { |
| "674ac754f91e64a0efb8087e59a176484bd534d1": { |
| "_number": 2, |
| "ref": "refs/changes/65/3965/2", |
| "fetch": { |
| "http": { |
| "url": "http://gerrit/myProject", |
| "ref": "refs/changes/65/3965/2" |
| } |
| } |
| } |
| } |
| ---- |
| |
| [[get-related-changes]] |
| === Get Related Changes |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/related' |
| -- |
| |
| Retrieves related changes of a revision. Related changes are changes that either |
| depend on, or are dependencies of the revision. |
| |
| .Request |
| ---- |
| GET /changes/gerrit~master~I5e4fc08ce34d33c090c9e0bf320de1b17309f774/revisions/b1cb4caa6be46d12b94c25aa68aebabcbb3f53fe/related HTTP/1.0 |
| ---- |
| |
| As result a link:#related-changes-info[RelatedChangesInfo] entity is returned |
| describing the related changes. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "changes": [ |
| { |
| "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 |
| }, |
| { |
| "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 |
| } |
| ] |
| } |
| ---- |
| |
| |
| [[set-review]] |
| === Set Review |
| -- |
| 'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/review' |
| -- |
| |
| Sets a review on a revision. |
| |
| The review must be provided in the request body as a |
| link:#review-input[ReviewInput] entity. |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/review HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "message": "Some nits need to be fixed.", |
| "labels": { |
| "Code-Review": -1 |
| }, |
| "comments": { |
| "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": [ |
| { |
| "line": 23, |
| "message": "[nit] trailing whitespace" |
| }, |
| { |
| "line": 49, |
| "message": "[nit] s/conrtol/control" |
| }, |
| { |
| "range": { |
| "start_line": 50, |
| "start_character": 0, |
| "end_line": 55, |
| "end_character": 20 |
| }, |
| "message": "Incorrect indentation" |
| } |
| ] |
| } |
| } |
| ---- |
| |
| As response a link:#review-info[ReviewInfo] entity is returned that |
| describes the applied labels. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "labels": { |
| "Code-Review": -1 |
| } |
| } |
| ---- |
| |
| A review cannot be set on a change edit. Trying to post a review for a |
| change edit fails with `409 Conflict`. |
| |
| [[rebase-revision]] |
| === Rebase Revision |
| -- |
| 'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/rebase' |
| -- |
| |
| Rebases a revision. |
| |
| Optionally, the parent revision can be changed to another patch set through the |
| link:#rebase-input[RebaseInput] entity. |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I3ea943139cb62e86071996f2480e58bf3eeb9dd2/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/rebase HTTP/1.0 |
| Content-Type: application/json;charset=UTF-8 |
| |
| { |
| "base" : "1234", |
| } |
| ---- |
| |
| As response a link:#change-info[ChangeInfo] entity is returned that |
| describes the rebased change. Information about the current patch set |
| is included. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "id": "myProject~master~I3ea943139cb62e86071996f2480e58bf3eeb9dd2", |
| "project": "myProject", |
| "branch": "master", |
| "change_id": "I3ea943139cb62e86071996f2480e58bf3eeb9dd2", |
| "subject": "Implement Feature X", |
| "status": "NEW", |
| "created": "2013-02-01 09:59:32.126000000", |
| "updated": "2013-02-21 11:16:36.775000000", |
| "mergeable": false, |
| "insertions": 21, |
| "deletions": 21, |
| "_number": 4799, |
| "owner": { |
| "name": "John Doe" |
| }, |
| "current_revision": "27cc4558b5a3d3387dd11ee2df7a117e7e581822", |
| "revisions": { |
| "27cc4558b5a3d3387dd11ee2df7a117e7e581822": { |
| "_number": 2, |
| "ref": "refs/changes/99/4799/2", |
| "fetch": { |
| "http": { |
| "url": "http://gerrit:8080/myProject", |
| "ref": "refs/changes/99/4799/2" |
| } |
| }, |
| "commit": { |
| "parents": [ |
| { |
| "commit": "b4003890dadd406d80222bf1ad8aca09a4876b70", |
| "subject": "Implement Feature A" |
| } |
| ], |
| "author": { |
| "name": "John Doe", |
| "email": "john.doe@example.com", |
| "date": "2013-05-07 15:21:27.000000000", |
| "tz": 120 |
| }, |
| "committer": { |
| "name": "Gerrit Code Review", |
| "email": "gerrit-server@example.com", |
| "date": "2013-05-07 15:35:43.000000000", |
| "tz": 120 |
| }, |
| "subject": "Implement Feature X", |
| "message": "Implement Feature X\n\nAdded feature X." |
| } |
| } |
| } |
| ---- |
| |
| If the revision cannot be rebased, e.g. due to conflicts, the response is |
| "`409 Conflict`" and the error message is contained in the response |
| body. |
| |
| .Response |
| ---- |
| HTTP/1.1 409 Conflict |
| Content-Disposition: attachment |
| Content-Type: text/plain; charset=UTF-8 |
| |
| The change could not be rebased due to a path conflict during merge. |
| ---- |
| |
| [[submit-revision]] |
| === Submit Revision |
| -- |
| 'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/submit' |
| -- |
| |
| Submits a revision. |
| |
| The request body only needs to include a link:#submit-input[ |
| SubmitInput] entity if the request should wait for the merge to |
| complete. |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/submit HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "wait_for_merge": true |
| } |
| ---- |
| |
| As response a link:#submit-info[SubmitInfo] entity is returned that |
| describes the status of the submitted change. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "status": "MERGED" |
| } |
| ---- |
| |
| If the revision cannot be submitted, e.g. because the submit rule |
| doesn't allow submitting the revision or the revision is not the |
| current revision, the response is "`409 Conflict`" and the error |
| message is contained in the response body. |
| |
| .Response |
| ---- |
| HTTP/1.1 409 Conflict |
| Content-Type: text/plain; charset=UTF-8 |
| |
| "revision 674ac754f91e64a0efb8087e59a176484bd534d1 is not current revision" |
| ---- |
| |
| [[publish-draft-revision]] |
| === Publish Draft Revision |
| -- |
| 'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/publish' |
| -- |
| |
| Publishes a draft revision. |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/publish HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| [[delete-draft-revision]] |
| === Delete Draft Revision |
| -- |
| 'DELETE /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]' |
| -- |
| |
| Deletes a draft revision. |
| |
| .Request |
| ---- |
| DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1 HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| [[get-patch]] |
| === Get Patch |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/patch' |
| -- |
| |
| Gets the formatted patch for one revision. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/patch HTTP/1.0 |
| ---- |
| |
| The formatted patch is returned as text encoded inside base64: |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: text/plain; charset=ISO-8859-1 |
| X-FYI-Content-Encoding: base64 |
| X-FYI-Content-Type: application/mbox |
| |
| RnJvbSA3ZGFkY2MxNTNmZGVhMTdhYTg0ZmYzMmE2ZTI0NWRiYjY... |
| ---- |
| |
| Adding query parameter `zip` (for example `/changes/.../patch?zip`) |
| returns the patch as a single file inside of a ZIP archive. Clients |
| can expand the ZIP to obtain the plain text patch, avoiding the |
| need for a base64 decoding step. This option implies `download`. |
| |
| Query parameter `download` (e.g. `/changes/.../patch?download`) |
| will suggest the browser save the patch as `commitsha1.diff.base64`, |
| for later processing by command line tools. |
| |
| [[get-mergeable]] |
| === Get Mergeable |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/mergeable' |
| -- |
| |
| Gets the method the server will use to submit (merge) the change and |
| an indicator if the change is currently mergeable. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/mergeable HTTP/1.0 |
| ---- |
| |
| As response a link:#mergeable-info[MergeableInfo] entity is returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| submit_type: "MERGE_IF_NECESSARY", |
| mergeable: true, |
| } |
| ---- |
| |
| If the `other-branches` parameter is specified, the mergeability will also be |
| checked for all other branches. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/mergeable?other-branches HTTP/1.0 |
| ---- |
| |
| The response will then contain a list of all other branches where this changes |
| could merge cleanly. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| submit_type: "MERGE_IF_NECESSARY", |
| mergeable: true, |
| mergeable_into: [ |
| "refs/heads/stable-2.7", |
| "refs/heads/stable-2.8", |
| ] |
| } |
| ---- |
| |
| [[get-submit-type]] |
| === Get Submit Type |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/submit_type' |
| -- |
| |
| Gets the method the server will use to submit (merge) the change. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/submit_type HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| "MERGE_IF_NECESSARY" |
| ---- |
| |
| [[test-submit-type]] |
| === Test Submit Type |
| -- |
| 'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/test.submit_type' |
| -- |
| |
| Tests the submit_type Prolog rule in the project, or the one given. |
| |
| Request body may be either the Prolog code as `text/plain` or a |
| link:#rule-input[RuleInput] object. The query parameter `filters` |
| may be set to `SKIP` to bypass parent project filters while testing |
| a project-specific rule. |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/test.submit_type HTTP/1.0 |
| Content-Type: text/plain; charset-UTF-8 |
| |
| submit_type(cherry_pick). |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| "CHERRY_PICK" |
| ---- |
| |
| [[test-submit-rule]] |
| === Test Submit Rule |
| -- |
| 'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/test.submit_rule' |
| -- |
| |
| Tests the submit_rule Prolog rule in the project, or the one given. |
| |
| Request body may be either the Prolog code as `text/plain` or a |
| link:#rule-input[RuleInput] object. The query parameter `filters` |
| may be set to `SKIP` to bypass parent project filters while testing |
| a project-specific rule. |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/test.submit_rule?filters=SKIP HTTP/1.0 |
| Content-Type: text/plain; charset-UTF-8 |
| |
| submit_rule(submit(R)) :- |
| R = label('Any-Label-Name', reject(_)). |
| ---- |
| |
| The response is a list of link:#submit-record[SubmitRecord] entries |
| describing the permutations that satisfy the tested submit rule. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| [ |
| { |
| "status": "NOT_READY", |
| "reject": { |
| "Any-Label-Name": {} |
| } |
| } |
| ] |
| ---- |
| |
| When testing with the `curl` command line client the |
| `--data-binary @rules.pl` flag should be used to ensure |
| all LFs are included in the Prolog code: |
| |
| ---- |
| curl -X POST \ |
| -H 'Content-Type: text/plain; charset=UTF-8' \ |
| --data-binary @rules.pl \ |
| http://.../test.submit_rule |
| ---- |
| |
| [[list-drafts]] |
| === List Drafts |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/drafts/' |
| -- |
| |
| Lists the draft comments of a revision that belong to the calling |
| user. |
| |
| As result a map is returned that maps the file path to a list of |
| link:#comment-info[CommentInfo] entries. The entries in the map are |
| sorted by file path. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/drafts/ HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": [ |
| { |
| "id": "TvcXrmjM", |
| "line": 23, |
| "message": "[nit] trailing whitespace", |
| "updated": "2013-02-26 15:40:43.986000000" |
| }, |
| { |
| "id": "TveXwFiA", |
| "line": 49, |
| "in_reply_to": "TfYX-Iuo", |
| "message": "Done", |
| "updated": "2013-02-26 15:40:45.328000000" |
| } |
| ] |
| } |
| ---- |
| |
| [[create-draft]] |
| === Create Draft |
| -- |
| 'PUT /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/drafts' |
| -- |
| |
| Creates a draft comment on a revision. |
| |
| The new draft comment must be provided in the request body inside a |
| link:#comment-input[CommentInput] entity. |
| |
| .Request |
| ---- |
| PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/drafts HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", |
| "line": 23, |
| "message": "[nit] trailing whitespace" |
| } |
| ---- |
| |
| As response a link:#comment-info[CommentInfo] entity is returned that |
| describes the draft comment. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "id": "TvcXrmjM", |
| "path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", |
| "line": 23, |
| "message": "[nit] trailing whitespace", |
| "updated": "2013-02-26 15:40:43.986000000" |
| } |
| ---- |
| |
| [[get-draft]] |
| === Get Draft |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/drafts/link:#draft-id[\{draft-id\}]' |
| -- |
| |
| Retrieves a draft comment of a revision that belongs to the calling |
| user. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/drafts/TvcXrmjM HTTP/1.0 |
| ---- |
| |
| As response a link:#comment-info[CommentInfo] entity is returned that |
| describes the draft comment. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "id": "TvcXrmjM", |
| "path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", |
| "line": 23, |
| "message": "[nit] trailing whitespace", |
| "updated": "2013-02-26 15:40:43.986000000" |
| } |
| ---- |
| |
| [[update-draft]] |
| === Update Draft |
| -- |
| 'PUT /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/drafts/link:#draft-id[\{draft-id\}]' |
| -- |
| |
| Updates a draft comment on a revision. |
| |
| The new draft comment must be provided in the request body inside a |
| link:#comment-input[CommentInput] entity. |
| |
| .Request |
| ---- |
| PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/drafts/TvcXrmjM HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", |
| "line": 23, |
| "message": "[nit] trailing whitespace" |
| } |
| ---- |
| |
| As response a link:#comment-info[CommentInfo] entity is returned that |
| describes the draft comment. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "id": "TvcXrmjM", |
| "path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", |
| "line": 23, |
| "message": "[nit] trailing whitespace", |
| "updated": "2013-02-26 15:40:43.986000000" |
| } |
| ---- |
| |
| [[delete-draft]] |
| === Delete Draft |
| -- |
| 'DELETE /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/drafts/link:#draft-id[\{draft-id\}]' |
| -- |
| |
| Deletes a draft comment from a revision. |
| |
| .Request |
| ---- |
| DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/drafts/TvcXrmjM HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| [[list-comments]] |
| === List Comments |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/comments/' |
| -- |
| |
| Lists the published comments of a revision. |
| |
| As result a map is returned that maps the file path to a list of |
| link:#comment-info[CommentInfo] entries. The entries in the map are |
| sorted by file path and only include file (or inline) comments. Use |
| the link:#get-change-detail[Get Change Detail] endpoint to retrieve |
| the general change message (or comment). |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/comments/ HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": [ |
| { |
| "id": "TvcXrmjM", |
| "line": 23, |
| "message": "[nit] trailing whitespace", |
| "updated": "2013-02-26 15:40:43.986000000", |
| "author": { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com" |
| } |
| }, |
| { |
| "id": "TveXwFiA", |
| "line": 49, |
| "in_reply_to": "TfYX-Iuo", |
| "message": "Done", |
| "updated": "2013-02-26 15:40:45.328000000", |
| "author": { |
| "_account_id": 1000097, |
| "name": "Jane Roe", |
| "email": "jane.roe@example.com" |
| } |
| } |
| ] |
| } |
| ---- |
| |
| [[get-comment]] |
| === Get Comment |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/comments/link:#comment-id[\{comment-id\}]' |
| -- |
| |
| Retrieves a published comment of a revision. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/comments/TvcXrmjM HTTP/1.0 |
| ---- |
| |
| As response a link:#comment-info[CommentInfo] entity is returned that |
| describes the published comment. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "id": "TvcXrmjM", |
| "path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", |
| "line": 23, |
| "message": "[nit] trailing whitespace", |
| "updated": "2013-02-26 15:40:43.986000000", |
| "author": { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com" |
| } |
| } |
| ---- |
| |
| [[list-files]] |
| === List Files |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/files/' |
| -- |
| |
| Lists the files that were modified, added or deleted in a revision. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/ HTTP/1.0 |
| ---- |
| |
| As result a map is returned that maps the file path to a list of |
| link:#file-info[FileInfo] entries. The entries in the map are |
| sorted by file path. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "/COMMIT_MSG": { |
| "status": "A", |
| "lines_inserted": 7 |
| }, |
| "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": { |
| "lines_inserted": 5, |
| "lines_deleted": 3 |
| } |
| } |
| ---- |
| |
| The request parameter `reviewed` changes the response to return a list |
| of the paths the caller has marked as reviewed. Clients that also |
| need the FileInfo should make two requests. |
| |
| The request parameter `q` changes the response to return a list |
| of all files (modified or unmodified) that contain that substring |
| in the path name. This is useful to implement suggestion services |
| finding a file by partial name. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/?reviewed HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| [ |
| "/COMMIT_MSG", |
| "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", |
| ] |
| ---- |
| |
| [[get-content]] |
| === Get Content |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/files/link:#file-id[\{file-id\}]/content' |
| -- |
| |
| Gets the content of a file from a certain revision. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/content HTTP/1.0 |
| ---- |
| |
| The content is returned as base64 encoded string. The HTTP response |
| Content-Type is always `text/plain`, reflecting the base64 wrapping. |
| A Gerrit-specific `X-FYI-Content-Type` header is returned describing |
| the server detected content type of the file. |
| |
| If only the content type is required, callers should use HEAD to |
| avoid downloading the encoded file contents. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: text/plain; charset=ISO-8859-1 |
| X-FYI-Content-Encoding: base64 |
| X-FYI-Content-Type: text/xml |
| |
| Ly8gQ29weXJpZ2h0IChDKSAyMDEwIFRoZSBBbmRyb2lkIE9wZW4gU291cmNlIFByb2plY... |
| ---- |
| |
| Alternatively, if the only value of the Accept request header is |
| `application/json` the content is returned as JSON string and |
| `X-FYI-Content-Encoding` is set to `json`. |
| |
| [[get-diff]] |
| === Get Diff |
| -- |
| 'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/files/link:#file-id[\{file-id\}]/diff' |
| -- |
| |
| Gets the diff of a file from a certain revision. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/diff HTTP/1.0 |
| ---- |
| |
| As response a link:#diff-info[DiffInfo] entity is returned that describes the diff. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )] |
| { |
| "meta_a": { |
| "name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", |
| "content_type": "text/x-java-source", |
| "lines": 372 |
| }, |
| "meta_b": { |
| "name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", |
| "content_type": "text/x-java-source", |
| "lines": 578 |
| }, |
| "change_type": "MODIFIED", |
| "diff_header": [ |
| "diff --git a/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java b/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", |
| "index 59b7670..9faf81c 100644", |
| "--- a/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", |
| "+++ b/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java" |
| ], |
| "content": [ |
| { |
| "ab": [ |
| "// Copyright (C) 2010 The Android Open Source Project", |
| "//", |
| "// Licensed under the Apache License, Version 2.0 (the \"License\");", |
| "// you may not use this file except in compliance with the License.", |
| "// You may obtain a copy of the License at", |
| "//", |
| "// http://www.apache.org/licenses/LICENSE-2.0", |
| "//", |
| "// Unless required by applicable law or agreed to in writing, software", |
| "// distributed under the License is distributed on an \"AS IS\" BASIS,", |
| "// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.", |
| "// See the License for the specific language governing permissions and", |
| "// limitations under the License." |
| ] |
| }, |
| { |
| "b": [ |
| "//", |
| "// Add some more lines in the header." |
| ] |
| }, |
| { |
| "ab": [ |
| "", |
| "package com.google.gerrit.server.project;", |
| "", |
| "import com.google.common.collect.Maps;", |
| ... |
| ] |
| } |
| ... |
| ] |
| } |
| ---- |
| |
| If the `intraline` parameter is specified, intraline differences are included in the diff. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/b6b9c10649b9041884046119ab794374470a1b45/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/diff?intraline HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )] |
| { |
| "meta_a": { |
| "name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", |
| "content_type": "text/x-java-source", |
| "lines": 372 |
| }, |
| "meta_b": { |
| "name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", |
| "content_type": "text/x-java-source", |
| "lines": 578 |
| }, |
| "change_type": "MODIFIED", |
| "diff_header": [ |
| "diff --git a/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java b/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", |
| "index 59b7670..9faf81c 100644", |
| "--- a/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", |
| "+++ b/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java" |
| ], |
| "content": [ |
| ... |
| { |
| "a": [ |
| "/** Manages access control for Git references (aka branches, tags). */" |
| ], |
| "b": [ |
| "/** Manages access control for the Git references (aka branches, tags). */" |
| ], |
| "edit_a": [], |
| "edit_b": [ |
| [ |
| 31, |
| 4 |
| ] |
| ] |
| } |
| ] |
| } |
| ---- |
| |
| The `base` parameter can be specified to control the base patch set from which the diff should |
| be generated. |
| |
| [[weblinks-only]] |
| If the `weblinks-only` parameter is specified, only the diff web links are returned. |
| |
| .Request |
| ---- |
| GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/b6b9c10649b9041884046119ab794374470a1b45/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/diff?base=2 HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )] |
| { |
| "meta_a": { |
| "name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", |
| "content_type": "text/x-java-source", |
| "lines": 578 |
| }, |
| "meta_b": { |
| "name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java", |
| "content_type": "text/x-java-source", |
| "lines": 578 |
| }, |
| "change_type": "MODIFIED", |
| "content": [ |
| { |
| "skip": 578 |
| } |
| ] |
| } |
| ---- |
| |
| The `ignore-whitespace` parameter can be specified to control how whitespace differences are |
| reported in the result. Valid values are `NONE`, `TRAILING`, `CHANGED` or `ALL`. |
| |
| The `context` parameter can be specified to control the number of lines of surrounding context |
| in the diff. Valid values are `ALL` or number of lines. |
| |
| [[set-reviewed]] |
| === Set Reviewed |
| -- |
| 'PUT /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/files/link:#file-id[\{file-id\}]/reviewed' |
| -- |
| |
| Marks a file of a revision as reviewed by the calling user. |
| |
| .Request |
| ---- |
| PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/reviewed HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 201 Created |
| ---- |
| |
| If the file was already marked as reviewed by the calling user the |
| response is "`200 OK`". |
| |
| [[delete-reviewed]] |
| === Delete Reviewed |
| -- |
| 'DELETE /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/files/link:#file-id[\{file-id\}]/reviewed' |
| -- |
| |
| Deletes the reviewed flag of the calling user from a file of a revision. |
| |
| .Request |
| ---- |
| DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/reviewed HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| [[cherry-pick]] |
| === Cherry Pick Revision |
| -- |
| 'POST /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/cherrypick' |
| -- |
| |
| Cherry picks a revision to a destination branch. |
| |
| The commit message and destination branch must be provided in the request body inside a |
| link:#cherrypick-input[CherryPickInput] entity. |
| |
| .Request |
| ---- |
| POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/cherrypick HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "message" : "Implementing Feature X", |
| "destination" : "release-branch" |
| } |
| ---- |
| |
| As response a link:#change-info[ChangeInfo] entity is returned that |
| describes the resulting cherry picked change. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9941", |
| "project": "myProject", |
| "branch": "release-branch", |
| "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9941", |
| "subject": "Implementing Feature X", |
| "status": "NEW", |
| "created": "2013-02-01 09:59:32.126000000", |
| "updated": "2013-02-21 11:16:36.775000000", |
| "mergeable": true, |
| "insertions": 12, |
| "deletions": 11, |
| "_number": 3965, |
| "owner": { |
| "name": "John Doe" |
| } |
| } |
| ---- |
| |
| [[ids]] |
| == IDs |
| |
| [[account-id]] |
| === link:rest-api-accounts.html#account-id[\{account-id\}] |
| -- |
| -- |
| |
| [[change-id]] |
| === \{change-id\} |
| Identifier that uniquely identifies one change. |
| |
| This can be: |
| |
| * an ID of the change in the format "'$$<project>~<branch>~<Change-Id>$$'", |
| where for the branch the `refs/heads/` prefix can be omitted |
| ("$$myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940$$") |
| * a Change-Id if it uniquely identifies one change |
| ("I8473b95934b5732ac55d26311a706c9c2bde9940") |
| * a legacy numeric change ID ("4247") |
| |
| [[comment-id]] |
| === \{comment-id\} |
| UUID of a published comment. |
| |
| [[draft-id]] |
| === \{draft-id\} |
| UUID of a draft comment. |
| |
| [[file-id]] |
| \{file-id\} |
| ~~~~~~~~~~~~ |
| The path of the file. |
| |
| [[revision-id]] |
| === \{revision-id\} |
| Identifier that uniquely identifies one revision of a change. |
| |
| This can be: |
| |
| * the literal `current` to name the current patch set/revision |
| * a commit ID ("674ac754f91e64a0efb8087e59a176484bd534d1") |
| * an abbreviated commit ID that uniquely identifies one revision of the |
| change ("674ac754"), at least 4 digits are required |
| * a legacy numeric patch number ("1" for first patch set of the change) |
| |
| [[json-entities]] |
| == JSON Entities |
| |
| [[abandon-input]] |
| === AbandonInput |
| The `AbandonInput` entity contains information for abandoning a change. |
| |
| [options="header",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`message` |optional| |
| Message to be added as review comment to the change when abandoning the |
| change. |
| |=========================== |
| |
| [[action-info]] |
| === ActionInfo |
| The `ActionInfo` entity describes a REST API call the client can |
| make to manipulate a resource. These are frequently implemented by |
| plugins and may be discovered at runtime. |
| |
| [options="header",cols="1,^1,5"] |
| |==================================== |
| |Field Name ||Description |
| |`method` |optional| |
| HTTP method to use with the action. Most actions use `POST`, `PUT` |
| or `DELETE` to cause state changes. |
| |`label` |optional| |
| Short title to display to a user describing the action. In the |
| Gerrit web interface the label is used as the text on the button |
| presented in the UI. |
| |`title` |optional| |
| Longer text to display describing the action. In a web UI this |
| should be the title attribute of the element, displaying when |
| the user hovers the mouse. |
| |`enabled` |optional| |
| If true the action is permitted at this time and the caller is |
| likely allowed to execute it. This may change if state is updated |
| at the server or permissions are modified. Not present if false. |
| |==================================== |
| |
| [[add-reviewer-result]] |
| === AddReviewerResult |
| The `AddReviewerResult` entity describes the result of adding a |
| reviewer to a change. |
| |
| [options="header",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`reviewers` |optional| |
| The newly added reviewers as a list of link:#reviewer-info[ |
| ReviewerInfo] entities. |
| |`error` |optional| |
| Error message explaining why the reviewer could not be added. + |
| If a group was specified in the input and an error is returned, it |
| means that none of the members were added as reviewer. |
| |`confirm` |`false` if not set| |
| Whether adding the reviewer requires confirmation. |
| |=========================== |
| |
| [[approval-info]] |
| === ApprovalInfo |
| The `ApprovalInfo` entity contains information about an approval from a |
| user for a label on a change. |
| |
| `ApprovalInfo` has the same fields as |
| link:rest-api-accounts.html#account-info[AccountInfo]. |
| In addition `ApprovalInfo` has the following fields: |
| |
| [options="header",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`value` |optional| |
| The vote that the user has given for the label. If present and zero, the |
| user is permitted to vote on the label. If absent, the user is not |
| permitted to vote on that label. |
| |`date` |optional| |
| The time and date describing when the approval was made. |
| |=========================== |
| |
| [[change-edit-input]] |
| === ChangeEditInput |
| The `ChangeEditInput` entity contains information for restoring a |
| path within change edit. |
| |
| [options="header",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`restore_path`|optional|Path to file to restore. |
| |`old_path` |optional|Old path to file to rename. |
| |`new_path` |optional|New path to file to rename. |
| |=========================== |
| |
| [[change-edit-message-input]] |
| === ChangeEditMessageInput |
| The `ChangeEditMessageInput` entity contains information for changing |
| the commit message within a change edit. |
| |
| [options="header",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`message` ||New commit message. |
| |=========================== |
| |
| [[change-info]] |
| === ChangeInfo |
| The `ChangeInfo` entity contains information about a change. |
| |
| [options="header",cols="1,^1,5"] |
| |================================== |
| |Field Name ||Description |
| |`id` || |
| The ID of the change in the format "'<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. |
| Only set if link:#reviewed[reviewed] is requested. |
| |`mergeable` |optional| |
| Whether the change is mergeable. + |
| Not set for merged changes, or if the change has not yet been tested. |
| |`insertions` || |
| Number of inserted lines. |
| |`deletions` || |
| Number of deleted lines. |
| |`_number` ||The legacy numeric ID of the change. |
| |`owner` || |
| The owner of the change as an link:rest-api-accounts.html#account-info[ |
| AccountInfo] entity. |
| |`actions` |optional| |
| Actions the caller might be able to perform on this revision. The |
| information is a map of view name to link:#action-info[ActionInfo] |
| entities. |
| |`labels` |optional| |
| The labels of the change as a map that maps the label names to |
| link:#label-info[LabelInfo] entries. + |
| Only set if link:#labels[labels] or link:#detailed-labels[detailed |
| labels] are requested. |
| |`permitted_labels` |optional| |
| A map of the permitted labels that maps a label name to the list of |
| values that are allowed for that label. + |
| Only set if link:#detailed-labels[detailed labels] are requested. |
| |`removable_reviewers`|optional| |
| The reviewers that can be removed by the calling user as a list of |
| link:rest-api-accounts.html#account-info[AccountInfo] entities. + |
| Only set if link:#detailed-labels[detailed labels] are requested. |
| |`messages`|optional| |
| Messages associated with the change as a list of |
| link:#change-message-info[ChangeMessageInfo] entities. + |
| Only set if link:#messages[messages] are requested. |
| |`current_revision` |optional| |
| The commit ID of the current patch set of this change. + |
| Only set if link:#current-revision[the current revision] is requested |
| or if link:#all-revisions[all revisions] are requested. |
| |`revisions` |optional| |
| All patch sets of this change as a map that maps the commit ID of the |
| patch set to a link:#revision-info[RevisionInfo] entity. + |
| Only set if link:#current-revision[the current revision] is requested |
| (in which case it will only contain a key for the current revision) or |
| if link:#all-revisions[all revisions] are requested. |
| |`_more_changes` |optional, not set if `false`| |
| Whether the query would deliver more results if not limited. + |
| Only set on the last change that is returned. |
| |`problems` |optional| |
| A list of link:#problem-info[ProblemInfo] entities describing potential |
| problems with this change. Only set if link:#check[CHECK] is set. |
| |`base_change` |optional| |
| A link:#change-id[\{change-id\}] that identifies the base change for a create |
| change operation. Only used for the link:#create-change[CreateChange] endpoint. |
| |================================== |
| |
| [[change-message-info]] |
| === ChangeMessageInfo |
| The `ChangeMessageInfo` entity contains information about a message |
| attached to a change. |
| |
| [options="header",cols="1,^1,5"] |
| |================================== |
| |Field Name ||Description |
| |`id` ||The ID of the message. |
| |`author` |optional| |
| Author of the message as an |
| link:rest-api-accounts.html#account-info[AccountInfo] entity. + |
| Unset if written by the Gerrit system. |
| |`date` || |
| The link:rest-api.html#timestamp[timestamp] this message was posted. |
| |`message` ||The text left by the user. |
| |`_revision_number` |optional| |
| Which patchset (if any) generated this message. |
| |================================== |
| |
| [[cherrypick-input]] |
| === CherryPickInput |
| The `CherryPickInput` entity contains information for cherry-picking a change to a new branch. |
| |
| [options="header",cols="1,6"] |
| |=========================== |
| |Field Name |Description |
| |`message` |Commit message for the cherry-picked change |
| |`destination` |Destination branch |
| |=========================== |
| |
| [[comment-info]] |
| === CommentInfo |
| The `CommentInfo` entity contains information about an inline comment. |
| |
| [options="header",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`id` ||The URL encoded UUID of the comment. |
| |`path` |optional| |
| The path of the file for which the inline comment was done. + |
| Not set if returned in a map where the key is the file path. |
| |`side` |optional| |
| The side on which the comment was added. + |
| Allowed values are `REVISION` and `PARENT`. + |
| If not set, the default is `REVISION`. |
| |`line` |optional| |
| The number of the line for which the comment was done. + |
| If range is set, this equals the end line of the range. + |
| If neither line nor range is set, it's a file comment. |
| |`range` |optional| |
| The range of the comment as a link:#comment-range[CommentRange] |
| entity. |
| |`in_reply_to` |optional| |
| The URL encoded UUID of the comment to which this comment is a reply. |
| |`message` |optional|The comment message. |
| |`updated` || |
| The link:rest-api.html#timestamp[timestamp] of when this comment was |
| written. |
| |`author` |optional| |
| The author of the message as an |
| link:rest-api-accounts.html#account-info[AccountInfo] entity. + |
| Unset for draft comments, assumed to be the calling user. |
| |=========================== |
| |
| [[comment-input]] |
| === CommentInput |
| The `CommentInput` entity contains information for creating an inline |
| comment. |
| |
| [options="header",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`id` |optional| |
| The URL encoded UUID of the comment if an existing draft comment should |
| be updated. |
| |`path` |optional| |
| The path of the file for which the inline comment should be added. + |
| Doesn't need to be set if contained in a map where the key is the file |
| path. |
| |`side` |optional| |
| The side on which the comment should be added. + |
| Allowed values are `REVISION` and `PARENT`. + |
| If not set, the default is `REVISION`. |
| |`line` |optional| |
| The number of the line for which the comment should be added. + |
| `0` if it is a file comment. + |
| If neither line nor range is set, a file comment is added. + |
| If range is set, this value is ignored in favor of the `end_line` of the range. |
| |`range` |optional| |
| The range of the comment as a link:#comment-range[CommentRange] |
| entity. |
| |`in_reply_to` |optional| |
| The URL encoded UUID of the comment to which this comment is a reply. |
| |`updated` |optional| |
| The link:rest-api.html#timestamp[timestamp] of this comment. + |
| Accepted but ignored. |
| |`message` |optional| |
| The comment message. + |
| If not set and an existing draft comment is updated, the existing draft |
| comment is deleted. |
| |=========================== |
| |
| [[comment-range]] |
| === CommentRange |
| The `CommentRange` entity describes the range of an inline comment. |
| |
| [options="header",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`start_line` ||The start line number of the range. |
| |`start_character` ||The character position in the start line. |
| |`end_line` ||The end line number of the range. |
| |`end_character` ||The character position in the end line. |
| |=========================== |
| |
| [[commit-info]] |
| === CommitInfo |
| The `CommitInfo` entity contains information about a commit. |
| |
| [options="header",cols="1,6"] |
| |========================== |
| |Field Name |Description |
| |`commit` |The commit ID. |
| |`parents` | |
| The parent commits of this commit as a list of |
| link:#commit-info[CommitInfo] entities. In each parent |
| only the `commit` and `subject` fields are populated. |
| |`author` |The author of the commit as a |
| link:#git-person-info[GitPersonInfo] entity. |
| |`committer` |The committer of the commit as a |
| link:#git-person-info[GitPersonInfo] entity. |
| |`subject` | |
| The subject of the commit (header line of the commit message). |
| |`message` |The commit message. |
| |`web_links` |optional| |
| Links to the commit in external sites as a list of |
| link:#web-link-info[WebLinkInfo] entities. |
| |========================== |
| |
| [[diff-content]] |
| === DiffContent |
| The `DiffContent` entity contains information about the content differences |
| in a file. |
| |
| [options="header",cols="1,^1,5"] |
| |========================== |
| |Field Name ||Description |
| |`a` |optional|Content only in the file on side A (deleted in B). |
| |`b` |optional|Content only in the file on side B (added in B). |
| |`ab` |optional|Content in the file on both sides (unchanged). |
| |`edit_a` |only present during a replace, i.e. both `a` and `b` are present| |
| Text sections deleted from side A as a |
| link:#diff-intraline-info[DiffIntralineInfo] entity. |
| |`edit_b` |only present during a replace, i.e. both `a` and `b` are present| |
| Text sections inserted in side B as a |
| link:#diff-intraline-info[DiffIntralineInfo] entity. |
| |`skip` |optional|count of lines skipped on both sides when the file is |
| too large to include all common lines. |
| |`common` |optional|Set to `true` if the region is common according |
| to the requested ignore-whitespace parameter, but a and b contain |
| differing amounts of whitespace. When present and true a and b are |
| used instead of ab. |
| |========================== |
| |
| [[diff-file-meta-info]] |
| === DiffFileMetaInfo |
| The `DiffFileMetaInfo` entity contains meta information about a file diff. |
| |
| [options="header",cols="1,^1,5"] |
| |========================== |
| |Field Name ||Description |
| |`name` ||The name of the file. |
| |`content_type`||The content type of the file. |
| |`lines` ||The total number of lines in the file. |
| |`web_links` |optional| |
| Links to the file in external sites as a list of |
| link:rest-api-changes.html#web-link-info[WebLinkInfo] entries. |
| |========================== |
| |
| [[diff-info]] |
| === DiffInfo |
| The `DiffInfo` entity contains information about the diff of a file |
| in a revision. |
| |
| If the link:#weblinks-only[weblinks-only] parameter is specified, only |
| the `web_links` field is set. |
| |
| [options="header",cols="1,^1,5"] |
| |========================== |
| |Field Name ||Description |
| |`meta_a` |not present when the file is added| |
| Meta information about the file on side A as a |
| link:#diff-file-meta-info[DiffFileMetaInfo] entity. |
| |`meta_b` |not present when the file is deleted| |
| Meta information about the file on side B as a |
| link:#diff-file-meta-info[DiffFileMetaInfo] entity. |
| |`change_type` ||The type of change (`ADDED`, `MODIFIED`, `DELETED`, `RENAMED` |
| `COPIED`, `REWRITE`). |
| |`intraline_status`|only set when the `intraline` parameter was specified in the request| |
| Intraline status (`OK`, `ERROR`, `TIMEOUT`). |
| |`diff_header` ||A list of strings representing the patch set diff header. |
| |`content` ||The content differences in the file as a list of |
| link:#diff-content[DiffContent] entities. |
| |`web_links` |optional| |
| Links to the file diff in external sites as a list of |
| link:rest-api-changes.html#diff-web-link-info[DiffWebLinkInfo] entries. |
| |`binary` |not set if `false`|Whether the file is binary. |
| |========================== |
| |
| [[diff-intraline-info]] |
| === DiffIntralineInfo |
| The `DiffIntralineInfo` entity contains information about intraline edits in a |
| file. |
| |
| The information consists of a list of `<skip length, mark length>` pairs, where |
| the skip length is the number of characters between the end of the previous edit |
| and the start of this edit, and the mark length is the number of edited characters |
| following the skip. The start of the edits is from the beginning of the related |
| diff content lines. |
| |
| Note that the implied newline character at the end of each line is included in |
| the length calculation, and thus it is possible for the edits to span newlines. |
| |
| [[diff-web-link-info]] |
| === DiffWebLinkInfo |
| The `DiffWebLinkInfo` entity describes a link on a diff screen to an |
| external site. |
| |
| [options="header",cols="1,6"] |
| |======================= |
| |Field Name|Description |
| |`name` |The link name. |
| |`url` |The link URL. |
| |`image_url`|URL to the icon of the link. |
| |show_on_side_by_side_diff_view| |
| Whether the web link should be shown on the side-by-side diff screen. |
| |show_on_unified_diff_view| |
| Whether the web link should be shown on the unified diff screen. |
| |======================= |
| |
| [[edit-file-info]] |
| === EditFileInfo |
| The `EditFileInfo` entity contains additional information |
| of a file within a change edit. |
| |
| [options="header",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`web_links` |optional| |
| Links to the diff info in external sites as a list of |
| link:#web-link-info[WebLinkInfo] entities. |
| |=========================== |
| |
| [[edit-info]] |
| === EditInfo |
| The `EditInfo` entity contains information about a change edit. |
| |
| [options="header",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`commit` ||The commit of change edit as |
| link:#commit-info[CommitInfo] entity. |
| |`baseRevision`||The revision of the patch set change edit is based on. |
| |`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. |
| |`files` |optional| |
| The files of the change edit as a map that maps the file names to |
| link:#file-info[FileInfo] entities. |
| |=========================== |
| |
| [[fetch-info]] |
| === FetchInfo |
| The `FetchInfo` entity contains information about how to fetch a patch |
| set via a certain protocol. |
| |
| [options="header",cols="1,^1,5"] |
| |========================== |
| |Field Name ||Description |
| |`url` ||The URL of the project. |
| |`ref` ||The ref of the patch set. |
| |`commands` |optional| |
| The download commands for this patch set as a map that maps the command |
| names to the commands. + |
| Only set if link:#download_commands[download commands] are requested. |
| |========================== |
| |
| [[file-info]] |
| === FileInfo |
| The `FileInfo` entity contains information about a file in a patch set. |
| |
| [options="header",cols="1,^1,5"] |
| |============================= |
| |Field Name ||Description |
| |`status` |optional| |
| The status of the file ("`A`"=Added, "`D`"=Deleted, "`R`"=Renamed, |
| "`C`"=Copied, "`W`"=Rewritten). + |
| Not set if the file was Modified ("`M`"). |
| |`binary` |not set if `false`|Whether the file is binary. |
| |`old_path` |optional| |
| The old file path. + |
| Only set if the file was renamed or copied. |
| |`lines_inserted`|optional| |
| Number of inserted lines. + |
| Not set for binary files or if no lines were inserted. |
| |`lines_deleted` |optional| |
| Number of deleted lines. + |
| Not set for binary files or if no lines were deleted. |
| |============================= |
| |
| [[git-person-info]] |
| === GitPersonInfo |
| The `GitPersonInfo` entity contains information about the |
| author/committer of a commit. |
| |
| [options="header",cols="1,6"] |
| |========================== |
| |Field Name |Description |
| |`name` |The name of the author/committer. |
| |`email` |The email address of the author/committer. |
| |`date` |The link:rest-api.html#timestamp[timestamp] of when |
| this identity was constructed. |
| |`tz` |The timezone offset from UTC of when this identity was |
| constructed. |
| |========================== |
| |
| [[group-base-info]] |
| === GroupBaseInfo |
| The `GroupBaseInfo` entity contains base information about the group. |
| |
| [options="header",cols="1,6"] |
| |========================== |
| |Field Name |Description |
| |`id` |The id of the group. |
| |`name` |The name of the group. |
| |========================== |
| |
| [[included-in-info]] |
| === IncludedInInfo |
| The `IncludedInInfo` entity contains information about the branches a |
| change was merged into and tags it was tagged with. |
| |
| [options="header",cols="1,6"] |
| |========================== |
| |Field Name |Description |
| |`branches` | The list of branches this change was merged into. |
| Each branch is listed without the 'refs/head/' prefix. |
| |`tags` | The list of tags this change was tagged with. |
| Each tag is listed without the 'refs/tags/' prefix. |
| |========================== |
| |
| [[label-info]] |
| === LabelInfo |
| The `LabelInfo` entity contains information about a label on a change, always |
| corresponding to the current patch set. |
| |
| There are two options that control the contents of `LabelInfo`: |
| link:#labels[`LABELS`] and link:#detailed-labels[`DETAILED_LABELS`]. |
| |
| * For a quick summary of the state of labels, use `LABELS`. |
| * For detailed information about labels, including exact numeric votes for all |
| users and the allowed range of votes for the current user, use `DETAILED_LABELS`. |
| |
| ==== Common fields |
| [options="header",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`optional` |not set if `false`| |
| Whether the label is optional. Optional means the label may be set, but |
| it's neither necessary for submission nor does it block submission if |
| set. |
| |=========================== |
| |
| ==== Fields set by `LABELS` |
| [options="header",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`approved` |optional|One user who approved this label on the change |
| (voted the maximum value) as an |
| link:rest-api-accounts.html#account-info[AccountInfo] entity. |
| |`rejected` |optional|One user who rejected this label on the change |
| (voted the minimum value) as an |
| link:rest-api-accounts.html#account-info[AccountInfo] entity. |
| |`recommended` |optional|One user who recommended this label on the |
| change (voted positively, but not the maximum value) as an |
| link:rest-api-accounts.html#account-info[AccountInfo] entity. |
| |`disliked` |optional|One user who disliked this label on the change |
| (voted negatively, but not the minimum value) as an |
| link:rest-api-accounts.html#account-info[AccountInfo] entity. |
| |`blocking` |optional|If `true`, the label blocks submit operation. |
| If not set, the default is false. |
| |`value` |optional|The voting value of the user who |
| recommended/disliked this label on the change if it is not |
| "`+1`"/"`-1`". |
| |`default_value`|optional|The default voting value for the label. |
| This value may be outside the range specified in permitted_labels. |
| |=========================== |
| |
| ==== Fields set by `DETAILED_LABELS` |
| [options="header",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`all` |optional|List of all approvals for this label as a list |
| of link:#approval-info[ApprovalInfo] entities. |
| |`values` |optional|A map of all values that are allowed for this |
| label. The map maps the values ("`-2`", "`-1`", " `0`", "`+1`", "`+2`") |
| to the value descriptions. |
| |=========================== |
| |
| [[mergeable-info]] |
| === MergeableInfo |
| The `MergeableInfo` entity contains information about the mergeability of a |
| change. |
| |
| [options="header",cols="1,^1,5"] |
| |============================ |
| |Field Name ||Description |
| |`submit_type` || |
| Submit type used for this change, can be `MERGE_IF_NECESSARY`, |
| `FAST_FORWARD_ONLY`, `REBASE_IF_NECESSARY`, `MERGE_ALWAYS` or |
| `CHERRY_PICK`. |
| |`mergeable` || |
| `true` if this change is cleanly mergeable, `false` otherwise |
| |`mergeable_into`|optional| |
| A list of other branch names where this change could merge cleanly |
| |============================ |
| |
| [[problem-info]] |
| === ProblemInfo |
| The `ProblemInfo` entity contains a description of a potential consistency problem |
| with a change. These are not related to the code review process, but rather |
| indicate some inconsistency in Gerrit's database or repository metadata related |
| to the enclosing change. |
| |
| [options="header",cols="1,^1,5"] |
| |=========================== |
| |Field Name||Description |
| |`message` ||Plaintext message describing the problem with the change. |
| |`status` |optional| |
| The status of fixing the problem (`FIXED`, `FIX_FAILED`). Only set if a |
| fix was attempted. |
| |`outcome` |optional| |
| If `status` is set, an additional plaintext message describing the |
| outcome of the fix. |
| |=========================== |
| |
| [[rebase-input]] |
| === RebaseInput |
| The `RebaseInput` entity contains information for changing parent when rebasing. |
| |
| [options="header",width="50%",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`base` |optional| |
| The new parent revision. This can be a ref or a SHA1 to a concrete patchset. + |
| Alternatively, a change number can be specified, in which case the current |
| patch set is inferred. + |
| Empty string is used for rebasing directly on top of the target branch, |
| which effectively breaks dependency towards a parent change. |
| |=========================== |
| |
| [[related-change-and-commit-info]] |
| === RelatedChangeAndCommitInfo |
| |
| The `RelatedChangeAndCommitInfo` entity contains information about |
| a related change and commit. |
| |
| [options="header",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`change_id` |optional|The Change-Id of the change. |
| |`commit` ||The commit as a |
| link:#commit-info[CommitInfo] entity. |
| |`_change_number` |optional|The change number. |
| |`_revision_number` |optional|The revision number. |
| |`_current_revision_number`|optional|The current revision number. |
| |=========================== |
| |
| [[related-changes-info]] |
| === RelatedChangesInfo |
| The `RelatedChangesInfo` entity contains information about related |
| changes. |
| |
| [options="header",cols="1,6"] |
| |=========================== |
| |Field Name |Description |
| |`changes` |A list of |
| link:#related-change-and-commit-info[RelatedChangeAndCommitInfo] entities |
| describing the related changes. Sorted by git commit order, newest to |
| oldest. Empty if there are no related changes. |
| |=========================== |
| |
| [[restore-input]] |
| === RestoreInput |
| The `RestoreInput` entity contains information for restoring a change. |
| |
| [options="header",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`message` |optional| |
| Message to be added as review comment to the change when restoring the |
| change. |
| |=========================== |
| |
| [[revert-input]] |
| === RevertInput |
| The `RevertInput` entity contains information for reverting a change. |
| |
| [options="header",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`message` |optional| |
| Message to be added as review comment to the change when reverting the |
| change. |
| |=========================== |
| |
| [[review-info]] |
| === ReviewInfo |
| The `ReviewInfo` entity contains information about a review. |
| |
| [options="header",cols="1,6"] |
| |=========================== |
| |Field Name |Description |
| |`labels` | |
| The labels of the review as a map that maps the label names to the |
| voting values. |
| |=========================== |
| |
| [[review-input]] |
| === ReviewInput |
| The `ReviewInput` entity contains information for adding a review to a |
| revision. |
| |
| [options="header",cols="1,^1,5"] |
| |============================ |
| |Field Name ||Description |
| |`message` |optional| |
| The message to be added as review comment. |
| |`labels` |optional| |
| The votes that should be added to the revision as a map that maps the |
| label names to the voting values. |
| |`comments` |optional| |
| The comments that should be added as a map that maps a file path to a |
| list of link:#comment-input[CommentInput] entities. |
| |`strict_labels`|`true` if not set| |
| Whether all labels are required to be within the user's permitted ranges |
| based on access controls. + |
| If `true`, attempting to use a label not granted to the user will fail |
| the entire modify operation early. + |
| If `false`, the operation will execute anyway, but the proposed labels |
| will be modified to be the "best" value allowed by the access controls. |
| |`drafts` |optional| |
| Draft handling that defines how draft comments are handled that are |
| already in the database but that were not also described in this |
| input. + |
| Allowed values are `DELETE`, `PUBLISH` and `KEEP`. + |
| If not set, the default is `DELETE`. |
| |`notify` |optional| |
| Notify handling that defines to whom email notifications should be sent |
| after the review is stored. + |
| Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. + |
| If not set, the default is `ALL`. |
| |`on_behalf_of`|optional| |
| link:rest-api-accounts.html#account-id[\{account-id\}] the review |
| should be posted on behalf of. To use this option the caller must |
| have been granted `labelAs-NAME` permission for all keys of labels. |
| |============================ |
| |
| [[reviewer-info]] |
| === ReviewerInfo |
| The `ReviewerInfo` entity contains information about a reviewer and its |
| votes on a change. |
| |
| `ReviewerInfo` has the same fields as |
| link:rest-api-accounts.html#account-info[AccountInfo] and includes |
| link:#detailed-accounts[detailed account information]. |
| In addition `ReviewerInfo` has the following fields: |
| |
| [options="header",cols="1,6"] |
| |========================== |
| |Field Name |Description |
| |`approvals` | |
| The approvals of the reviewer as a map that maps the label names to the |
| approval values ("`-2`", "`-1`", "`0`", "`+1`", "`+2`"). |
| |========================== |
| |
| [[reviewer-input]] |
| === ReviewerInput |
| The `ReviewerInput` entity contains information for adding a reviewer |
| to a change. |
| |
| [options="header",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`reviewer` || |
| The link:rest-api-accounts.html#account-id[ID] of one account that |
| should be added as reviewer or the link:rest-api-groups.html#group-id[ |
| ID] of one group for which all members should be added as reviewers. + |
| If an ID identifies both an account and a group, only the account is |
| added as reviewer to the change. |
| |`confirmed` |optional| |
| Whether adding the reviewer is confirmed. + |
| The Gerrit server may be configured to |
| link:config-gerrit.html#addreviewer.maxWithoutConfirmation[require a |
| confirmation] when adding a group as reviewer that has many members. |
| |=========================== |
| |
| [[revision-info]] |
| === RevisionInfo |
| The `RevisionInfo` entity contains information about a patch set. |
| Not all fields are returned by default. Additional fields can |
| be obtained by adding `o` parameters as described in |
| link:#list-changes[Query Changes]. |
| |
| [options="header",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`draft` |not set if `false`|Whether the patch set is a draft. |
| |`has_draft_comments` |not set if `false`|Whether the patch |
| set has one or more draft comments by the calling user. Only set if |
| link:#draft_comments[DRAFT_COMMENTS] option is requested. |
| |`_number` ||The patch set number. |
| |`created` || |
| The link:rest-api.html#timestamp[timestamp] of when the patch set was |
| created. |
| |`uploader` || |
| The uploader of the patch set as an |
| link:rest-api-accounts.html#account-info[AccountInfo] entity. |
| |`ref` ||The Git reference for the patch set. |
| |`fetch` || |
| Information about how to fetch this patch set. The fetch information is |
| provided as a map that maps the protocol name ("`git`", "`http`", |
| "`ssh`") to link:#fetch-info[FetchInfo] entities. This information is |
| only included if a plugin implementing the |
| link:intro-project-owner.html#download-commands[download commands] |
| interface is installed. |
| |`commit` |optional|The commit of the patch set as |
| link:#commit-info[CommitInfo] entity. |
| |`files` |optional| |
| The files of the patch set as a map that maps the file names to |
| link:#file-info[FileInfo] entities. Only set if |
| link:#current-files[CURRENT_FILES] or link:#all-files[ALL_FILES] |
| option is requested. |
| |`actions` |optional| |
| Actions the caller might be able to perform on this revision. The |
| information is a map of view name to link:#action-info[ActionInfo] |
| entities. |
| |`reviewed` |optional| |
| Indicates whether the caller is authenticated and has commented on the |
| current revision. Only set if link:#reviewed[REVIEWED] option is requested. |
| |=========================== |
| |
| [[rule-input]] |
| === RuleInput |
| The `RuleInput` entity contains information to test a Prolog rule. |
| |
| [options="header",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`rule`|| |
| Prolog code to execute instead of the code in `refs/meta/config`. |
| |`filters`|`RUN` if not set| |
| When `RUN` filter rules in the parent projects are called to |
| post-process the results of the project specific rule. This |
| behavior matches how the rule will execute if installed. + |
| If `SKIP` the parent filters are not called, allowing the test |
| to return results from the input rule. |
| |=========================== |
| |
| [[submit-info]] |
| === SubmitInfo |
| The `SubmitInfo` entity contains information about the change status |
| after submitting. |
| |
| [options="header",cols="1,6"] |
| |========================== |
| |Field Name |Description |
| |`status` | |
| The status of the change after submitting, can be `MERGED` or |
| `SUBMITTED`. + |
| If `wait_for_merge` in the link:#submit-input[SubmitInput] was set to |
| `false` the returned status is `SUBMITTED` and the caller can't know |
| whether the change could be merged successfully. |
| |`on_behalf_of`|optional| |
| The link:rest-api-accounts.html#account-id[\{account-id\}] of the user on |
| whose behalf the action should be done. To use this option the caller must |
| have been granted both `Submit` and `Submit (On Behalf Of)` permissions. |
| The user named by `on_behalf_of` does not need to be granted the `Submit` |
| permission. This feature is aimed for CI solutions: the CI account can be |
| granted both permssions, so individual users don't need `Submit` permission |
| themselves. Still the changes can be submited on behalf of real users and |
| not with the identity of the CI account. |
| |========================== |
| |
| [[submit-input]] |
| === SubmitInput |
| The `SubmitInput` entity contains information for submitting a change. |
| |
| [options="header",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`wait_for_merge`|`false` if not set| |
| Whether the request should wait for the merge to complete. + |
| If `false` the request returns immediately after the change has been |
| added to the merge queue and the caller can't know whether the change |
| could be merged successfully. |
| |=========================== |
| |
| [[submit-record]] |
| === SubmitRecord |
| The `SubmitRecord` entity describes results from a submit_rule. |
| |
| [options="header",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`status`|| |
| `OK`, the change can be submitted. + |
| `NOT_READY`, additional labels are required before submit. + |
| `CLOSED`, closed changes cannot be submitted. + |
| `RULE_ERROR`, rule code failed with an error. |
| |`ok`|optional| |
| Map of labels that are approved; an |
| link:rest-api-accounts.html#account-info[AccountInfo] identifies the |
| voter chosen by the rule. |
| |`reject`|optional| |
| Map of labels that are preventing submit; |
| link:rest-api-accounts.html#account-info[AccountInfo] identifies voter. |
| |`need`|optional| |
| Map of labels that need to be given to submit. The value is |
| currently an empty object. |
| |`may`|optional| |
| Map of labels that can be used, but do not affect submit. |
| link:rest-api-accounts.html#account-info[AccountInfo] identifies voter, |
| if the label has been applied. |
| |`impossible`|optional| |
| Map of labels that should have been in `need` but cannot be |
| used by any user because of access restrictions. The value |
| is currently an empty object. |
| |`error_message`|optional| |
| When status is RULE_ERROR this message provides some text describing |
| the failure of the rule predicate. |
| |=========================== |
| |
| [[suggested-reviewer-info]] |
| === SuggestedReviewerInfo |
| The `SuggestedReviewerInfo` entity contains information about a reviewer |
| that can be added to a change (an account or a group). |
| |
| `SuggestedReviewerInfo` has either the `account` field that contains |
| the link:rest-api-accounts.html#account-info[AccountInfo] entity, or |
| the `group` field that contains the |
| link:rest-api-changes.html#group-base-info[GroupBaseInfo] entity. |
| |
| [[topic-input]] |
| === TopicInput |
| The `TopicInput` entity contains information for setting a topic. |
| |
| [options="header",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`topic` |optional|The topic. + |
| The topic will be deleted if not set. |
| |=========================== |
| |
| [[web-link-info]] |
| === WebLinkInfo |
| The `WebLinkInfo` entity describes a link to an external site. |
| |
| [options="header",cols="1,6"] |
| |====================== |
| |Field Name|Description |
| |`name` |The link name. |
| |`url` |The link URL. |
| |`image_url`|URL to the icon of the link. |
| |====================== |
| |
| GERRIT |
| ------ |
| Part of link:index.html[Gerrit Code Review] |
| |
| SEARCHBOX |
| --------- |