File Diff Resource¶
Provides information on per-file diffs.
Each of these contains a single, self-contained diff file that applies to exactly one file on a repository.
Details¶
| Name | file |
| URI | /api/review-requests/{review_request_id}/diffs/{diff_revision}/files/{filediff_id}/ |
| Token Policy ID | file_diff |
| HTTP Methods | |
| Parent Resource | File Diff List Resource |
| Child Resources |
Fields¶
| binaryBoolean | Whether this represents a binary file. Added in 4.0.6 |
| dest_attachmentDiff File Attachment Resource | The file attachment for the contents of the patched file for this file diff, if representing a binary file. Added in 2.0 |
| dest_detailString | Additional information of the destination file. This is parsed from the diff, but is usually not used for anything. |
| dest_fileString | The new name of the patched file. This may be the same as the existing file. |
| extra_dataDictionary | Extra data as part of the diff. This can be set by the API or extensions. Added in 2.0 |
| idInteger | The numeric ID of the file diff. |
| source_attachmentDiff File Attachment Resource | The file attachment for the contents of the original file for this file diff, if representing a binary file. Added in 2.0 |
| source_fileString | The original name of the modified file in the diff. |
| source_revisionString | The revision of the file being modified. This is a valid revision in the repository. |
| statusString | The status of the file. This is one of copied, deleted, modified, moved, or unknown. Added in 2.5.11 |
Links¶
| Name | Method | Resource |
|---|---|---|
| diff_comments | GET | File Diff Comment List Resource |
| patched_file | GET | Patched File Resource |
| self | GET | File Diff Resource |
| update | PUT | File Diff Resource |
HTTP GET¶
Returns the information or contents on a per-file diff.
The output varies by mimetype.
If application/json or application/xml is used, then the fields for the diff are returned, like with any other resource.
If text/x-patch is used, then the actual diff file itself is returned. This diff should be as it was when uploaded originally, for this file only, with potentially some extra SCM-specific headers stripped.
If application/vnd.reviewboard.org.diff.data+json or application/vnd.reviewboard.org.diff.data+xml is used, then the raw diff data (lists of inserts, deletes, replaces, moves, header information, etc.) is returned in either JSON or XML. This contains nearly all of the information used to render the diff in the diff viewer, and can be useful for building a diff viewer that interfaces with Review Board.
If ?syntax-highlighting=1 is passed, the rendered diff content
for each line will contain HTML markup showing syntax highlighting.
Otherwise, the content will be in plain text.
The format of the diff data is a bit complex. The data is stored
under a top-level diff_data element and contains the following
information:
| binaryBoolean | Whether or not the file is a binary file. Binary files won’t have any diff content to display. |
| changed_chunk_indexesList of Integer | The list of chunks in the diff that have actual changes (inserts, deletes, or replaces). |
| chunksList of Dictionary | A list of chunks. These are used to render the diff. See below. |
| new_fileBoolean | Whether or not this is a newly added file, rather than an existing file in the repository. |
| num_changesInteger | The number of changes made in this file (chunks of adds, removes, or deletes). |
Each chunk contains the following fields:
changeOne of equal, delete, insert, replace |
The type of change on this chunk. The type influences what sort of information is available for the chunk. |
| collapsableBoolean | Whether or not this chunk is collapseable. A collapseable
chunk is one that is hidden by default in the diff viewer,
but can be expanded. These will always be equal chunks,
but not every equal chunk is necessarily collapseable (as
they may be there to provide surrounding context for the
changes). |
| indexInteger | The index of the chunk. This is 0-based. |
| linesList of List | The list of rendered lines for a side-by-side diff. Each entry in the list is itself a list with 8 items:
|
| metaDictionary | Additional information about the chunk. See below for more information. |
| numlinesInteger | The number of lines in the chunk. |
A chunk’s meta information contains:
| headersList of [String, String] | Class definitions, function definitions, or other useful headers that should be displayed before this chunk. This helps users to identify where in a file they are and what the current chunk may be a part of. |
| whitespace_chunkBoolean | Whether or not the entire chunk consists only of whitespace changes. |
| whitespace_linesList of [Integer, Integer] | A list of (start, end) row indexes in the lins that contain
whitespace-only changes. These are 1-based. |
Other meta information may be available, but most is intended for internal use and shouldn’t be relied upon.
Errors¶
| 100 - Does Not ExistHTTP 404 - Not Found | Object does not exist |
| 101 - Permission DeniedHTTP 403 - Forbidden | You don’t have permission for this |
| 103 - Not Logged InHTTP 401 - Unauthorized | You are not logged in |
| 112 - OAuth2 Missing Scope ErrorHTTP 403 - Forbidden | Your OAuth2 token lacks the necessary scopes for this request. |
| 113 - OAuth2 Access Denied ErrorHTTP 403 - Forbidden | OAuth2 token access for this resource is prohibited. |
HTTP PUT¶
Updates a per-file diff.
This is used solely for updating extra data on a file’s diff. The contents of a diff cannot be modified.
Extra data can be stored later lookup. See Storing/Accessing Extra Data for more information.
Errors¶
| 100 - Does Not ExistHTTP 404 - Not Found | Object does not exist |
| 101 - Permission DeniedHTTP 403 - Forbidden | You don’t have permission for this |
| 103 - Not Logged InHTTP 401 - Unauthorized | You are not logged in |
| 105 - Invalid Form DataHTTP 400 - Bad Request | One or more fields had errors |
| 112 - OAuth2 Missing Scope ErrorHTTP 403 - Forbidden | Your OAuth2 token lacks the necessary scopes for this request. |
| 113 - OAuth2 Access Denied ErrorHTTP 403 - Forbidden | OAuth2 token access for this resource is prohibited. |
Examples¶
text/x-patch¶
$ curl https://reviews.example.com/api/review-requests/10/diffs/1/files/44/ -H "Accept: text/x-patch"
HTTP 200 OK
Content-Disposition: inline; filename=tests.py.patch
Content-Length: 433
Content-Type: text/x-patch
ETag: 788bf6bb7f022533f9f86d11b4d99f54f8e912c5
Last-Modified: Fri, 10 Aug 2018 22:16:22 GMT
Vary: Accept, Cookie
diff --git a/tests.py b/tests.py
new file mode 100644
index 0000000000000000000000000000000000000000..0dd5ce553d79b5b09b2d979cda92f321e1757e26
--- /dev/null
+++ b/tests.py
@@ -0,0 +1,11 @@
+from unittest import TestCase
+
+from myproject import initialize, frobnicate
+
+
+class MyTests(TestCase):
+ def setUp(self):
+ initialize()
+
+ def test_frobnicate(self):
+ self.assertEqual(frobnicate(1), 'frobnication')
application/vnd.reviewboard.org.diff.data+json¶
$ curl https://reviews.example.com/api/review-requests/10/diffs/1/files/44/ -H "Accept: application/json"
HTTP 200 OK
Content-Length: 1028
Content-Type: application/json
ETag: f0c5c8b5c8840b595482822c8eb15a2136e92c67
Last-Modified: Fri, 10 Aug 2018 22:16:22 GMT
Vary: Accept, Cookie
X-Content-Type-Options: nosniff
{
"diff_data": {
"binary": false,
"changed_chunk_indexes": [
0
],
"chunks": [
{
"change": "insert",
"collapsable": false,
"index": 0,
"lines": [
[
1,
"",
"",
[],
1,
"from unittest import TestCase",
[],
false
],
[
2,
"",
"",
[],
2,
"",
[],
false
],
[
3,
"",
"",
[],
3,
"from myproject import initialize, frobnicate",
[],
false
],
[
4,
"",
"",
[],
4,
"",
[],
false
],
[
5,
"",
"",
[],
5,
"",
[],
false
],
[
6,
"",
"",
[],
6,
"class MyTests(TestCase):",
[],
false
],
[
7,
"",
"",
[],
7,
" def setUp(self):",
[],
false
],
[
8,
"",
"",
[],
8,
" initialize()",
[],
false
],
[
9,
"",
"",
[],
9,
"",
[],
false
],
[
10,
"",
"",
[],
10,
" def test_frobnicate(self):",
[],
false
],
[
11,
"",
"",
[],
11,
" self.assertEqual(frobnicate(1), 'frobnication')",
[],
false
]
],
"meta": {
"left_headers": [],
"right_headers": [
[
6,
"class MyTests(TestCase):"
],
[
7,
" def setUp(self):"
],
[
10,
" def test_frobnicate(self):"
]
],
"whitespace_chunk": false,
"whitespace_lines": []
},
"numlines": 11
}
],
"new_file": true,
"num_changes": 1
},
"stat": "ok"
}
application/vnd.reviewboard.org.file+json¶
$ curl https://reviews.example.com/api/review-requests/10/diffs/1/files/44/ -H "Accept: application/json"
HTTP 200 OK
Content-Length: 1359
Content-Type: application/vnd.reviewboard.org.file+json
ETag: 4a264ddca566f525646f5bb690bb6732c3529442
Last-Modified: Fri, 10 Aug 2018 22:16:22 GMT
Vary: Accept, Cookie
X-Content-Type-Options: nosniff
{
"file": {
"binary": false,
"dest_attachment": null,
"dest_detail": "0dd5ce553d79b5b09b2d979cda92f321e1757e26",
"dest_file": "tests.py",
"extra_data": {
"delete_count": 0,
"equal_count": 0,
"insert_count": 11,
"is_symlink": false,
"orig_sha1": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
"orig_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"patched_sha1": "f27440bd48ab7d12357e294ad566ccda91e60659",
"patched_sha256": "6b3339e6027784fdab4ef1ccd31f8a69768c3f37177e28942f2e5331d25d2ead",
"raw_delete_count": 0,
"raw_insert_count": 4058,
"replace_count": 0,
"total_line_count": 11
},
"id": 44,
"links": {
"diff_comments": {
"href": "https://reviews.example.com/api/review-requests/10/diffs/1/files/44/diff-comments/",
"method": "GET"
},
"original_file": {
"href": "https://reviews.example.com/api/review-requests/10/diffs/1/files/44/original-file/",
"method": "GET"
},
"patched_file": {
"href": "https://reviews.example.com/api/review-requests/10/diffs/1/files/44/patched-file/",
"method": "GET"
},
"self": {
"href": "https://reviews.example.com/api/review-requests/10/diffs/1/files/44/",
"method": "GET"
},
"update": {
"href": "https://reviews.example.com/api/review-requests/10/diffs/1/files/44/",
"method": "PUT"
}
},
"source_attachment": null,
"source_file": "tests.py",
"source_revision": "PRE-CREATION",
"status": "modified"
},
"stat": "ok"
}