Jump to >

This documentation covers the in-development release of RBTools. You can see the latest stable docs or all previous versions.

patch

rbt patch will download the latest diff from the review request matching review-request-id and apply it to the local working directory. The --diff-revision option may be used to specify a specific revision of the diff to use.

Usage

$ rbt patch [options] <review-request-id>

JSON Output

New in version 3.0.

When running with --json, the results of patching a change will be outputted as JSON. This can be used by programs that wrap RBTools in order to automate patching source trees from review requests.

Successful Payloads

When patching is successful, the results are in the form of:

{
    "status": "success",

    // The revision of the diff that was applied.
    "diff_revision": <int>,

    // The total number of patches that were applied.
    "total_patches": <int>,

    // The ID of the review request.
    "review_request_id": <int>,

    // The URL of the review request.
    "review_request_url": "<string>",

    // Any warnings found during patching that could affect the tree.
    "warnings": [
        "<string>",
        ...
    ]
}

For example:

$ rbt patch --json 123
{
    "diff_revision": 2,
    "review_request_id": 123,
    "review_request_url": "https://example.com/r/123/",
    "status": "success",
    "total_patches": 1,
}
If the working directory is not clean:
$ rbt patch --json 123
{
    "diff_revision": 2,
    "review_request_id": 123,
    "review_request_url": "https://example.com/r/123/",
    "status": "success",
    "total_patches": 1,
    "warnings": [
        "Working directory is not clean."
    ]
}

Error Payloads

When there’s an error applying a patch, the results will be in the form of:

{
    "status": "failed",

    /*
     * A list of filenames that conflicted when applying the patch.
     *
     * This key is only present if conflicts were found.
     */
    "conflicting_files": [
        "<string>",
        ...
    ],

    // The revision of the diff that RBTools was trying to apply.
    "diff_revision": <int>,

    // A list of errors from the operation.
    "errors": [
        "<string>",
        ...
    ],

    // The number of the patch in the series that failed to patch.
    "failed_patch_num": <int>,

    // The total number of patches that RBTools were trying to apply.
    "total_patches": <int>,

    // The ID of the review request.
    "review_request_id": <int>,

    // The URL of the review request.
    "review_request_url": "<string>",

    // Any warnings found that could have affected the tree.
    "warnings": [
        "<string>",
        ...
    ]
}

Most errors will have identifying information, but not all. Consumers should not assume the presence of any fields except for errors and status.

Examples:

If there’s an invalid patch:
$ rbt patch --json 123
{
    "diff_revision": 2,
    "errors": [
        "Unable to apply the patch. The patch may be invalid, or there may be conflicts that could not be resolved.",
    ],
    "failed_patch_num": 1,
    "review_request_id": 123,
    "review_request_url": "https://example.com/r/123/",
    "status": "failed",
    "total_patches": 1
}
If there are conflicts:
$ rbt patch --json 123
{
    "conflicting_files": [
        "README.txt",
        "src/main.c"
    ],
    "diff_revision": 2,
    "errors": [
        "The patch was partially applied, but there were conflicts.",
        "Could not revert patch 1 of 1",
    ],
    "failed_patch_num": 1,
    "review_request_id": 123,
    "review_request_url": "https://example.com/r/123/",
    "status": "failed",
    "total_patches": 1
}

Options

-c, --commit

Commits using information fetched from the review request (Git/Mercurial only).

New in version 0.5.3.

-C, --commit-no-edit

Commits using information fetched from the review request (Git/Mercurial only). This differs from --commit by not invoking the editor to modify the commit message.

--diff-revision <revision>

The Review Board diff revision ID to use for the patch.

--px <num>

Strips the given number of paths from filenames in the diff. Equivalent to patch’s -p argument.

--print

Prints the patch to standard output instead of applying it to the tree.

New in version 0.5.3.

-R, --revert

Revert the given patch instead of applying it.

This feature does not work with Bazaar or Mercurial repositories.

New in version 0.7.3.

--write

Write the patch to a given file instead of applying it to the tree.

New in version 2.0.1.

--commit-ids

Comma-separated list of commit IDs to apply.

This only applies to review requests created with commit history.

New in version 2.0.

--squash

Squash all patches into one commit. This is only used if also using -c/--commit or -C/--commit-no-edit.

New in version 2.0.

-d, --debug

Displays debug output.

This information can be valuable when debugging problems running the command.

The default can be set in DEBUG in .reviewboardrc.

--json

Output results as JSON data instead of text.

The default can be set in JSON_OUTPUT in .reviewboardrc.

New in version 3.0.

Review Board Server Options

Options necessary to communicate and authenticate with a Review Board server.

--server <url>

Specifies the Review Board server to use.

The default can be set in REVIEWBOARD_URL in .reviewboardrc.

--username <username>

The user name to be supplied to the Review Board server.

The default can be set in USERNAME in .reviewboardrc.

--password <password>

The password to be supplied to the Review Board server.

The default can be set in PASSWORD in .reviewboardrc.

--ext-auth-cookies <ext auth cookies>

Use an external cookie store with pre-fetched authentication data. This is useful with servers that require extra web authentication to access Review Board, e.g. on single sign-on enabled sites.

The default can be set in EXT_AUTH_COOKIES in .reviewboardrc.

New in version 0.7.5.

--api-token <token>

The API token to use for authentication, instead of using a username and password.

The default can be set in API_TOKEN in .reviewboardrc.

New in version 0.7.

--disable-proxy

Prevents requests from going through a proxy server.

The default can be set in ENABLE_PROXY in .reviewboardrc.

--disable-ssl-verification

Disable SSL certificate verification. This is useful with servers that have self-signed certificates.

The default can be set in DISABLE_SSL_VERIFICATION in .reviewboardrc.

New in version 0.7.3.

Use an in-memory cookie store instead of writing them to a file. No credentials will be saved or loaded.

The default can be set in SAVE_COOKIES in .reviewboardrc.

New in version 0.7.3.

--disable-cache

Disable the HTTP cache completely. This will result in slower requests.

The default can be set in DISABLE_CACHE in .reviewboardrc.

New in version 0.7.3.

--disable-cache-storage

Disable storing the API cache on the filesystem, instead keeping it in memory temporarily.

The default can be set in IN_MEMORY_CACHE in .reviewboardrc.

New in version 0.7.3.

--cache-location <file>

The file to use for the API cache database.

The default can be set in CACHE_LOCATION in .reviewboardrc.

New in version 0.7.3.

--ca-certs <file>

Additional TLS CA bundle.

The default can be set in CA_CERTS in .reviewboardrc.

--client-key <file>

Key for TLS client authentication.

The default can be set in CLIENT_KEY in .reviewboardrc.

--client-cert <file>

Certificate for TLS client authentication.

The default can be set in CLIENT_CERT in .reviewboardrc.

--proxy-authorization <proxy authorization>

Value of the Proxy-Authorization header to send with HTTP requests.

The default can be set in PROXY_AUTHORIZATION in .reviewboardrc.

Repository Options

--repository <name>

The name of the repository configured on Review Board that matches the local repository.

The default can be set in REPOSITORY in .reviewboardrc.

--repository-url <url>

The URL for a repository.

When generating diffs, this can be used for creating a diff outside of a working copy (currently only supported by Subversion with specific revisions or --diff-filename, and by ClearCase with relative paths outside the view).

For Git, this specifies the origin URL of the current repository, overriding the origin URL supplied by the client.

The default can be set in REPOSITORY_URL in .reviewboardrc.

Changed in version 0.6: Prior versions used the REPOSITORY setting in .reviewboardrc, and allowed a repository name to be passed to --repository-url. This is no longer supported in 0.6 and higher. You may need to update your configuration and scripts appropriately.

--repository-type <type>

The type of repository in the current directory. In most cases this should be detected automatically, but some directory structures containing multiple repositories require this option to select the proper type. The rbt list-repo-types command can be used to list the supported values.

The default can be set in REPOSITORY_TYPE in .reviewboardrc.