land¶

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¶

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.

{
    "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>"
        },
        ...
    ]
}

$ 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"
}

$ 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"
}

{
    "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>",
        ...
    ]
}

$ 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"
}

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