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	GET - Returns the information or contents on a per-file diff. PUT - Updates a per-file diff.
Parent Resource	File Diff List Resource
Child Resources	File Diff Comment List Resource Original File Resource Patched File Resource

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.
encodingString	The encoding of the original and patched file, if available. Added in 5.0.8
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: Row number of the line in the combined side-by-side diff. The line number of the line in the left-hand file, as an integer (for `replace`, `delete`, and `equal` chunks) or an empty string (for `insert`). The text for the line in the left-hand file. The indexes within the text for the left-hand file that have been replaced by text in the right-hand side. Each index is a list of `start, end` positions, 0-based. This is only available for `replace` lines. Otherwise the list is empty. The line number of the line in the right-hand file, as an integer (for `replace`, `insert` and `equal` chunks) or an empty string (for `delete`). The text for the line in the right-hand file. The indexes within the text for the right-hand file that are replacements for text in the left-hand file. Each index is a list of `start, end` positions, 0-based. This is only available for `replace` lines. Otherwise the list is empty. A boolean that indicates if the line contains only whitespace changes.
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: 1030
Content-Type: application/json
ETag: 592dbf15b3ce9e7a3e80bf005f8f392bb52c6da6
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), &#x27;frobnication&#x27;)",
            [],
            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: 1418
Content-Type: application/vnd.reviewboard.org.file+json
ETag: 8cb7c47e1273138e9d91e12c07d6c0b5dbfcc5af
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",
    "encoding": null,
    "extra_data": {
      "delete_count": 0,
      "dest_mimetype": "text/x-script.python",
      "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"
}