Jump to >

land

rbt land is used to land a change on a branch, once it has been approved through the review process. It takes care of validating that the change is approved, creates a commit for it on a destination branch, and optionally pushes that branch upstream.

The destination branch must either be specified on the command line (using --dest) or by setting LAND_DEST_BRANCH in .reviewboardrc.

There are two types of changes that can be landed: Locally-accessible branches of commits, and patches stored on Review Board.

Usage

$ rbt land [options] [<branch-name>]

Landing local branches

To land a local branch, you must either specify the branch to land, or you must first switch to the branch. The following examples are therefore equivalent:

# Landing a specific branch.
$ rbt land my-branch

# Landing the current branch.
$ git checkout my-branch
$ rbt land

rbt land will look for a matching review request, prompting if it cannot find one. In some cases, you may need to specify -r with a review request ID, along with --local, if it’s unable to find a match.

By default, the branch and all of its history will be merged into the destination branch. To instead squash the branch’s history into a single commit, pass --squash.

Squashing can be made the default by specifying LAND_SQUASH = True in .reviewboardrc. It can then be selectively disabled by passing --no-squash.

Landing remote patches

To land a remote patch, pass -r with a review request ID, and don’t specify a branch name on the command line. rbt land will attempt to apply the latest patch on that review request to the destination branch.

If the patch can’t apply, an error will be provided. You can then attempt to apply the patch manually to a branch and then land the branch.

Working with commit messages

The resulting commit’s message (whether a standard commit or a merge commit) will mirror the summary, description, and testing in the review request. The commit will follow this template:

<summary>

<description>

Testing Done:
<testing_done>

Bugs closed: <bugs>
Reviewed at <review_request_url>

If the Testing Done field was blank, that section will be omitted. The same is true of the bugs closed.

The commit message be edited in your default editor by passing --edit.

Automatically pushing changes

By default, landed changes won’t be pushed upstream. This gives the committer time to test the patch or alter it as needed before pushing.

To instead push the commit immediately after landing, pass --push.

The default behavior can be changed by specifying LAND_PUSH = True in .reviewboardrc. It can then be selectively disabled by passing --no-push.

Deleting landed branches

Typically, when a branch has landed, it’s no longer necessary to keep it around. rbt land will default to deleting this branch after landing it.

If the branch needs to stay around after landing, you can pass --no-delete-branch.

The default behavior can be changed by specifying LAND_DELETE_BRANCH = False in .reviewboardrc. It can then be selectively enabled by passing --delete-branch.

Landing review requests recursively

If you wish to land a series of review requests, each of which depends on the previous review request, you can use the --recursive option to land them all at once, provided they have all been approved. For example if you have review requests 1, 2, and 3 where 3 depends on 2 and 2 depends on 1, the following command:

$ rbt land --recursive -r 3

is equivalent to the following series of commands:

$ rbt land -r 1
$ rbt land -r 2
$ rbt land -r 3

In the case where multiple review requests depend on a review request, the review requests will be landed in an order that preserves this relationship (known as a topological sort). For example, if review requests 2 and 3 both depend on review request 1 and 4 depends on 3 and 2, then the following command:

$ rbt land --recursive -r 4

is equivalent to the following series of commands:

$ rbt land -r 1
$ rbt land -r 2  # or rbt land -r 3
$ rbt land -r 3  # or rbt land -r 2
$ rbt land -r 4

In this case, the order that review requests 2 and 3 landed is not guaranteed, except that they will land after review request 1 and before review request 4.

JSON Output

New in version 3.0.

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

Successful Payloads

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

{
    "status": "success",

    "is_approved": true,

    /*
     * A list of all review requests landed in this session.
     *
     * There may be more than one entry if using --recursive.
     */
    "landed_review_requests": [
        {
            // The branch the change was landed in.
            "destination_branch": "<string>",

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

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

            // The local branch being landed, if specified.
            "source_branch": "<string>",

            /*
             * The type of land operation. This will be one of:
             *
             * "squash" if using --squash and a local branch.
             *
             * "merge" if using --no-squash and a local branch.
             *
             * "patch" if landing a change on a review request.
             */
            "type": "<string>"
        },
        ...
    ]
}

For example:

Landing a local branch:
$ rbt land --json my-branch
{
    "is_approved": true,
    "landed_review_requests": [
        {
            "destination_branch": "dest-branch",
            "review_request_id": 123,
            "review_request_url": "https://example.com/r/123/",
            "source_branch": "my-branch",
            "type": "merge"
        },
    ],
    "status": "success"
}
Landing a change on a review request:
$ rbt land --json -r 123
{
    "is_approved": true,
    "landed_review_requests": [
        {
            "destination_branch": "dest-branch",
            "review_request_id": 123,
            "review_request_url": "https://example.com/r/123/",
            "source_branch": null,
            "type": "merge"
        },
    ],
    "status": "success"
}

Error Payloads

When there’s an error landing a change (such as the change not yet being approved), the results will be in the form of:

{
    "status": "success",

    // If the change is not approved, this will be present.
    "approval_failure": {
        // The approval failure message.
        "message": "<string>",

        // The ID of the review request that wasn't approved.
        "review_request_id": <int>

        // The URL of the review request that wasn't approved.
        "review_request_url": "<string>"
    },

    // If the change is not approved, this will be present and `false`.
    "is_approved": false,

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

For example:

Attempting to land a change that isn’t approved:
$ rbt close --json my-branch
{
    "approval_failure": {
        "message": "This review is not marked Ship It!",
        "review_request_id": 123,
        "review_request_url": "https://example.com/r/123/",
    },
    "errors": [
        "Cannot land review request 123: This review is not marked Ship It!",
    ],
    "is_approved": false,
    "status": "failed"
}
The change was approved but could not be applied.
$ rbt close --json -r 123
{
    "errors": [
        "Failed to execute \"rbt patch\": ..."
    ],
    "is_approved": true,
    "status": "failed"
}

Options

--dest

Specifies the destination branch to land changes on.

The default can be set in LAND_DEST_BRANCH in .reviewboardrc.

-r <id>, --review-request-id <id>

Specifies the review request ID.

--local

Forces the change to be merged without patching, if merging a local branch. Defaults to true unless --review-request-id is used.

-p, --push

Pushes the branch after landing the change.

The default can be set in LAND_PUSH in .reviewboardrc.

-n, --no-push

Prevents pushing the branch after landing the change, if pushing is enabled by default.

This option is set by default. The default can be changed by setting LAND_PUSH in .reviewboardrc.

--squash

Squashes history into a single commit.

The default can be set in LAND_SQUASH in .reviewboardrc.

--no-squash

Disables squashing history into a single commit, choosing instead to merge the branch, if squashing is enabled by default.

This option is set by default. The default can be changed by setting LAND_SQUASH in .reviewboardrc.

-e, --edit

Invokes the editor to edit the commit message before landing the change.

--delete-branch

Deletes the local branch after it’s landed. Only used if landing a local branch. This is the default.

This option is set by default. The default can be changed by setting LAND_DELETE_BRANCH in .reviewboardrc.

--no-delete-branch

Prevents the local branch from being deleted after it’s landed.

The default can be set in LAND_DELETE_BRANCH in .reviewboardrc.

--dry-run

Simulates the landing of a change, without actually making any changes to the tree.

--recursive

Recursively fetch patches for review requests that the specified review request depends on. This is equivalent to calling “rbt patch” for each of those review requests.

New in version 1.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.

Branch Options

Options for selecting branches.

--tracking-branch <branch>

The remote tracking branch from which your local branch is derived (Git/Mercurial only).

For Git, the default is to use the remote branch that the local branch is tracking, if any, falling back on origin/master.

For Mercurial, the default is one of: reviewboard, origin, parent, or default.

The default can be set in TRACKING_BRANCH in .reviewboardrc.