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 | |
| Anonymous Access | Yes, if anonymous site access is enabled |
Fields¶
| 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 |
| original_file | GET | Original File 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 http://reviews.example.com/api/review-requests/8/diffs/1/files/31/ -H "Accept: text/x-patch"
Last-Modified: Wed, 25 Feb 2009 02:01:21 GMT
Content-Type: text/x-patch
Content-Disposition: inline; filename=/trunk/reviewboard/settings_local.py.tmpl.patch
Vary: Accept, Cookie
Index: /trunk/reviewboard/settings_local.py.tmpl
===================================================================
--- /trunk/reviewboard/settings_local.py.tmpl (revision 1797)
+++ /trunk/reviewboard/settings_local.py.tmpl (working copy)
@@ -13,15 +13,15 @@
# django installations, the best option is probably to use memcached.
CACHE_BACKEND = 'locmem:///'
-# Local time zone for this installation. All choices can be found here:
-# http://www.postgresql.org/docs/8.1/static/datetime-keywords.html#DATETIME-TIMEZONE-SET-TABLE
-TIME_ZONE = 'US/Pacific'
-
# Language code for this installation. All choices can be found here:
# http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes
# http://blogs.law.harvard.edu/tech/stories/storyReader$15
LANGUAGE_CODE = 'en-us'
+# Local time zone for this installation. All choices can be found here:
+# http://www.postgresql.org/docs/8.1/static/datetime-keywords.html#DATETIME-TIMEZONE-SET-TABLE
+TIME_ZONE = 'US/Pacific'
+
# This should match the ID of the Site object in the database. This is used to
# figure out URLs to stick in e-mails and related pages.
SITE_ID = 1
@@ -34,7 +34,6 @@
# to load the internationalization machinery.
USE_I18N = True
-
# TLS for LDAP. If you're using LDAP authentication and your LDAP server
# doesn't support ldaps://, you can enable start-TLS with this.
LDAP_TLS = False
application/vnd.reviewboard.org.diff.data+json¶
$ curl http://reviews.example.com/api/review-requests/8/diffs/1/files/31/ -H "Accept: application/json"
Last-Modified: Wed, 25 Feb 2009 02:01:21 GMT
Content-Type: application/json
X-Content-Type-Options: nosniff
Vary: Accept, Cookie
{
"diff_data": {
"binary": false,
"changed_chunk_indexes": [
2,
4,
6
],
"chunks": [
{
"change": "equal",
"collapsable": true,
"index": 0,
"lines": [
[
1,
1,
"# Database backend. Any supported django database engine should work.",
[],
1,
"# Database backend. Any supported django database engine should work.",
[],
false
],
[
2,
2,
"DATABASE_ENGINE = 'mysql' # 'postgresql', 'mysql', 'sqlite3' or 'ado_mssql'.",
[],
2,
"DATABASE_ENGINE = 'mysql' # 'postgresql', 'mysql', 'sqlite3' or 'ado_mssql'.",
[],
false
],
[
3,
3,
"DATABASE_NAME = 'reviewboard' # Or path to database file if using sqlite3.",
[],
3,
"DATABASE_NAME = 'reviewboard' # Or path to database file if using sqlite3.",
[],
false
],
[
4,
4,
"DATABASE_USER = '********' # Not used with sqlite3.",
[],
4,
"DATABASE_USER = '********' # Not used with sqlite3.",
[],
false
],
[
5,
5,
"DATABASE_PASSWORD = '********' # Not used with sqlite3.",
[],
5,
"DATABASE_PASSWORD = '********' # Not used with sqlite3.",
[],
false
],
[
6,
6,
"DATABASE_HOST = '' # Set to empty string for localhost.",
[],
6,
"DATABASE_HOST = '' # Set to empty string for localhost.",
[],
false
],
[
7,
7,
"DATABASE_PORT = '' # Set to empty string for default.",
[],
7,
"DATABASE_PORT = '' # Set to empty string for default.",
[],
false
],
[
8,
8,
"",
[],
8,
"",
[],
false
],
[
9,
9,
"# Make this unique, and don't share it with anybody.",
[],
9,
"# Make this unique, and don't share it with anybody.",
[],
false
],
[
10,
10,
"SECRET_KEY = '***********************************************'",
[],
10,
"SECRET_KEY = '***********************************************'",
[],
false
]
],
"meta": {
"left_headers": [],
"right_headers": []
},
"numlines": 10
},
{
"change": "equal",
"collapsable": false,
"index": 1,
"lines": [
[
11,
11,
"",
[],
11,
"",
[],
false
],
[
12,
12,
"# Cache backend. Unset this to turn off caching completely. As with most",
[],
12,
"# Cache backend. Unset this to turn off caching completely. As with most",
[],
false
],
[
13,
13,
"# django installations, the best option is probably to use memcached.",
[],
13,
"# django installations, the best option is probably to use memcached.",
[],
false
],
[
14,
14,
"CACHE_BACKEND = 'locmem:///'",
[],
14,
"CACHE_BACKEND = 'locmem:///'",
[],
false
],
[
15,
15,
"",
[],
15,
"",
[],
false
]
],
"meta": {
"left_headers": [],
"right_headers": []
},
"numlines": 5
},
{
"change": "delete",
"collapsable": false,
"index": 2,
"lines": [
[
16,
16,
"# Local time zone for this installation. All choices can be found here:",
[],
"",
"",
[],
false,
{
"to": [
21,
true
]
}
],
[
17,
17,
"# http://www.postgresql.org/docs/8.1/static/datetime-keywords.html#DATETIME-TIMEZONE-SET-TABLE",
[],
"",
"",
[],
false,
{
"to": [
22,
false
]
}
],
[
18,
18,
"TIME_ZONE = 'US/Pacific'",
[],
"",
"",
[],
false,
{
"to": [
23,
false
]
}
],
[
19,
19,
"",
[],
"",
"",
[],
false
]
],
"meta": {
"left_headers": [],
"moved-to": {
"16": 21,
"17": 22,
"18": 23
},
"right_headers": [],
"whitespace_chunk": false,
"whitespace_lines": []
},
"numlines": 4
},
{
"change": "equal",
"collapsable": false,
"index": 3,
"lines": [
[
20,
20,
"# Language code for this installation. All choices can be found here:",
[],
16,
"# Language code for this installation. All choices can be found here:",
[],
false
],
[
21,
21,
"# http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes",
[],
17,
"# http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes",
[],
false
],
[
22,
22,
"# http://blogs.law.harvard.edu/tech/stories/storyReader$15",
[],
18,
"# http://blogs.law.harvard.edu/tech/stories/storyReader$15",
[],
false
],
[
23,
23,
"LANGUAGE_CODE = 'en-us'",
[],
19,
"LANGUAGE_CODE = 'en-us'",
[],
false
],
[
24,
24,
"",
[],
20,
"",
[],
false
]
],
"meta": {
"left_headers": [],
"right_headers": [],
"whitespace_chunk": false,
"whitespace_lines": []
},
"numlines": 5
},
{
"change": "insert",
"collapsable": false,
"index": 4,
"lines": [
[
25,
"",
"",
[],
21,
"# Local time zone for this installation. All choices can be found here:",
[],
false,
{
"from": [
16,
true
]
}
],
[
26,
"",
"",
[],
22,
"# http://www.postgresql.org/docs/8.1/static/datetime-keywords.html#DATETIME-TIMEZONE-SET-TABLE",
[],
false,
{
"from": [
17,
false
]
}
],
[
27,
"",
"",
[],
23,
"TIME_ZONE = 'US/Pacific'",
[],
false,
{
"from": [
18,
false
]
}
],
[
28,
"",
"",
[],
24,
"",
[],
false
]
],
"meta": {
"left_headers": [],
"moved-from": {
"21": 16,
"22": 17,
"23": 18
},
"right_headers": [],
"whitespace_chunk": false,
"whitespace_lines": []
},
"numlines": 4
},
{
"change": "equal",
"collapsable": false,
"index": 5,
"lines": [
[
29,
25,
"# This should match the ID of the Site object in the database. This is used to",
[],
25,
"# This should match the ID of the Site object in the database. This is used to",
[],
false
],
[
30,
26,
"# figure out URLs to stick in e-mails and related pages.",
[],
26,
"# figure out URLs to stick in e-mails and related pages.",
[],
false
],
[
31,
27,
"SITE_ID = 1",
[],
27,
"SITE_ID = 1",
[],
false
],
[
32,
28,
"",
[],
28,
"",
[],
false
],
[
33,
29,
"# Set this to the place of your reviewboard if it does not reside",
[],
29,
"# Set this to the place of your reviewboard if it does not reside",
[],
false
],
[
34,
30,
"# at the root of your server. - Add the trailing slash.",
[],
30,
"# at the root of your server. - Add the trailing slash.",
[],
false
],
[
35,
31,
"# SITE_ROOT = "/reviewboard/"",
[],
31,
"# SITE_ROOT = "/reviewboard/"",
[],
false
],
[
36,
32,
"",
[],
32,
"",
[],
false
],
[
37,
33,
"# If you set this to False, Django will make some optimizations so as not",
[],
33,
"# If you set this to False, Django will make some optimizations so as not",
[],
false
],
[
38,
34,
"# to load the internationalization machinery.",
[],
34,
"# to load the internationalization machinery.",
[],
false
],
[
39,
35,
"USE_I18N = True",
[],
35,
"USE_I18N = True",
[],
false
],
[
40,
36,
"",
[],
36,
"",
[],
false
]
],
"meta": {
"left_headers": [],
"right_headers": [],
"whitespace_chunk": false,
"whitespace_lines": []
},
"numlines": 12
},
{
"change": "delete",
"collapsable": false,
"index": 6,
"lines": [
[
41,
37,
"",
[],
"",
"",
[],
false
]
],
"meta": {
"left_headers": [],
"right_headers": [],
"whitespace_chunk": false,
"whitespace_lines": []
},
"numlines": 1
},
{
"change": "equal",
"collapsable": false,
"index": 7,
"lines": [
[
42,
38,
"# TLS for LDAP. If you're using LDAP authentication and your LDAP server",
[],
37,
"# TLS for LDAP. If you're using LDAP authentication and your LDAP server",
[],
false
],
[
43,
39,
"# doesn't support ldaps://, you can enable start-TLS with this.",
[],
38,
"# doesn't support ldaps://, you can enable start-TLS with this.",
[],
false
],
[
44,
40,
"LDAP_TLS = False",
[],
39,
"LDAP_TLS = False",
[],
false
]
],
"meta": {
"left_headers": [],
"right_headers": [],
"whitespace_chunk": false,
"whitespace_lines": []
},
"numlines": 3
}
],
"new_file": false,
"num_changes": 3
},
"stat": "ok"
}
application/vnd.reviewboard.org.file+json¶
$ curl http://reviews.example.com/api/review-requests/8/diffs/1/files/31/ -H "Accept: application/json"
Last-Modified: Wed, 25 Feb 2009 02:01:21 GMT
ETag: ecfc33a66a005adc653920c3dc7a3f0f0f196f32
Content-Type: application/vnd.reviewboard.org.file+json
X-Content-Type-Options: nosniff
Vary: Accept, Cookie
{
"file": {
"dest_attachment": null,
"dest_detail": "(working copy)",
"dest_file": "/trunk/reviewboard/settings_local.py.tmpl",
"extra_data": {
"delete_count": 5,
"equal_count": 35,
"insert_count": 4,
"orig_sha1": "5ab9c202636417016379061749915006efac40a0",
"patched_sha1": "2c08ecb7ba61733c2ef794c1fa7e49090a4a334f",
"raw_delete_count": 5,
"raw_insert_count": 4,
"replace_count": 0,
"total_line_count": 44
},
"id": 31,
"links": {
"diff_comments": {
"href": "http://reviews.example.com/api/review-requests/8/diffs/1/files/31/diff-comments/",
"method": "GET"
},
"original_file": {
"href": "http://reviews.example.com/api/review-requests/8/diffs/1/files/31/original-file/",
"method": "GET"
},
"patched_file": {
"href": "http://reviews.example.com/api/review-requests/8/diffs/1/files/31/patched-file/",
"method": "GET"
},
"self": {
"href": "http://reviews.example.com/api/review-requests/8/diffs/1/files/31/",
"method": "GET"
},
"update": {
"href": "http://reviews.example.com/api/review-requests/8/diffs/1/files/31/",
"method": "PUT"
}
},
"source_attachment": null,
"source_file": "/trunk/reviewboard/settings_local.py.tmpl",
"source_revision": "1797",
"status": "modified"
},
"stat": "ok"
}