Review Board 2.0 Documentation

Need help? Talk to us today about a support contract!

Jump to >

This documentation covers Review Board 2.0. You can see the latest Review Board documentation or all other versions.

Draft File Diff Resource

Provides information on per-file diffs that are part of a draft.

Each of these contains a single, self-contained diff file that applies to exactly one file on a repository.

Details

Name draft_file
URI /api/review-requests/{review_request_id}/draft/diffs/{diff_revision}/files/{filediff_id}/
HTTP Methods
  • GET - Returns the information or contents on a per-file diff.
  • PUT - Updates a per-file diff.
Parent Resource Draft File Diff List Resource
Child Resources
Anonymous Access No

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.
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.
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.
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.

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

HTTP PUT

Updates a per-file diff.

If this represents a binary file, then the contents of the binary file can be uploaded before the review request is published.

Extra data can be stored for later lookup by passing extra_data.key_name=value. The key_name and value can be any valid strings. Passing a blank value will remove the key. The extra_data. prefix is required.

Request Parameters

dest_attachment_fileUploaded File The file attachment to upload, representing the modified file. This can only be used for binary files.

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

Examples

text/x-patch

$ curl http://reviews.example.com/api/review-requests/8/draft/diffs/2/files/35/ -H "Accept: text/x-patch"

Last-Modified: Wed, 25 Feb 2009 02:03:05 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
@@ -33,8 +33,3 @@
 # If you set this to False, Django will make some optimizations so as not
 # 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/draft/diffs/2/files/35/ -H "Accept: application/json"

Last-Modified: Wed, 25 Feb 2009 02:03:05 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
          ]
        ], 
        "meta": {
          "left_headers": [], 
          "right_headers": [], 
          "whitespace_chunk": false, 
          "whitespace_lines": []
        }, 
        "numlines": 11
      }, 
      {
        "change": "delete", 
        "collapsable": false, 
        "index": 6, 
        "lines": [
          [
            40, 
            36, 
            "", 
            [], 
            "", 
            "", 
            [], 
            false
          ], 
          [
            41, 
            37, 
            "", 
            [], 
            "", 
            "", 
            [], 
            false
          ], 
          [
            42, 
            38, 
            "# 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.", 
            [], 
            "", 
            "", 
            [], 
            false
          ], 
          [
            44, 
            40, 
            "LDAP_TLS = False", 
            [], 
            "", 
            "", 
            [], 
            false
          ]
        ], 
        "meta": {
          "left_headers": [], 
          "right_headers": [], 
          "whitespace_chunk": false, 
          "whitespace_lines": []
        }, 
        "numlines": 5
      }
    ], 
    "new_file": false, 
    "num_changes": 3
  }, 
  "stat": "ok"
}

application/vnd.reviewboard.org.file+json

$ curl http://reviews.example.com/api/review-requests/8/draft/diffs/2/files/35/ -H "Accept: application/json"

Last-Modified: Wed, 25 Feb 2009 02:03:05 GMT
ETag: 6224e4851cd246120498c9bc3ca426d77ae7be58
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": 9, 
      "equal_count": 31, 
      "insert_count": 4, 
      "orig_sha1": "5ab9c202636417016379061749915006efac40a0", 
      "patched_sha1": "a9a5606c12ccf3a7d064b5ae3ff147f27535e2a2", 
      "raw_delete_count": 9, 
      "raw_insert_count": 4, 
      "replace_count": 0, 
      "total_line_count": 44
    }, 
    "id": 35, 
    "links": {
      "original_file": {
        "href": "http://reviews.example.com/api/review-requests/8/draft/diffs/2/files/35/original-file/", 
        "method": "GET"
      }, 
      "patched_file": {
        "href": "http://reviews.example.com/api/review-requests/8/draft/diffs/2/files/35/patched-file/", 
        "method": "GET"
      }, 
      "self": {
        "href": "http://reviews.example.com/api/review-requests/8/draft/diffs/2/files/35/", 
        "method": "GET"
      }, 
      "update": {
        "href": "http://reviews.example.com/api/review-requests/8/draft/diffs/2/files/35/", 
        "method": "PUT"
      }
    }, 
    "source_attachment": null, 
    "source_file": "/trunk/reviewboard/settings_local.py.tmpl", 
    "source_revision": "1797"
  }, 
  "stat": "ok"
}