Jump to >

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

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

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:

  1. Row number of the line in the combined side-by-side diff.
  2. 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).
  3. The text for the line in the left-hand file.
  4. 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.
  5. 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).
  6. The text for the line in the right-hand file.
  7. 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.
  8. 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: 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"
}