post¶

rbt post simplifies both creating and updating review requests. It can look at your source directory, generate a diff, and upload it to a new or existing review request on an associated Review Board server. This saves a lot of time over the web UI, and for some types of code repositories (such as Perforce), it’s actually required in order to produce a compatible diff.

Usage:

$ rbt post [options] [changenum | [<file> ...]]

Posting and Updating Review Requests¶

Depending on the repository type, rbt post will either require a changeset number, or it will rely on the changes in the current source tree. The end result is that rbt post will build a diff and post it to a Review Board server. The diff and any additional review request information will be saved on the server as a draft, which can then be published.

After posting a new review request or updating an existing one, rbt post will display the URL of the review request. If the -o parameter is passed, the default web browser will be opened to that URL.

The following subsections will explain how rbt post is used with different repository types.

Automating rbt post¶

It’s possible to automate rbt post on a user’s behalf. This can be useful from a repository’s post-commit hook to automatically create or update a review request. This works through a combination of a special Review Board user and the --submit-as option.

To set this up, first register a new user. This user will be specific to your script, and will have special permissions, so make sure the password is protected. You’ll then want to grant the "Can submit as user" Permission and "Can edit review request" Permission to the user. This will give this user to the ability to modify a review request as another user.

You can then invoke rbt post by doing the following:

$ rbt post --username=SPECIAL_USER --password=PASSWORD --submit-as=ANOTHER_USER

Of course, you can pass any other values as you see fit.

This will log in as SPECIAL_USER and perform operations as ANOTHER_USER.

You can set the default for --submit-as by setting SUBMIT_AS in .reviewboardrc.

Perforce¶

Posting Changesets¶

Perforce has a concept of changesets, which are server-stored descriptions of a change along with an ID number and associated files. For Perforce, Review Board stores changeset numbers of a posted change and can use these to associate particular changes with review requests.

To post a review request for a specific change, or to update an existing review request for that change, type:

$ rbt post CHANGENUM

Where CHANGENUM is the changeset number in Perforce.

The diff will be generated and uploaded to Review Board, and the review request information will be updated based on the changeset description.

rbt post must be used if you’re using Perforce with Review Board, as the diff generated by p4 diff doesn’t provide the information necessary to properly display a side-by-side diff.

Posting Paths¶

There are cases where you may want to post individual paths containing files instead of changesets. Take the following cases, for example:

You have code or other files that must be checked in before they’re reviewed and have undergone multiple changes.
You’re working in a side branch for a while, possibly with other people, and need to review the code before it’s integrated into the main branch.
You want to post a really old, previously abandoned change for review that previously went unreviewed.

To post with a path, rbt post should be run with a standard Perforce depot path as a parameter, which may contain revision information. The following paths are supported:

Uploading a file as a “new” file:

//path/to/file

Uploading all files in a directory as “new” files:

//path/to/dir/...

Uploading a file from a revision as a “new” file (not as common):

//path/to/file/[@#]rev

Uploading a diff of a file between two revisions:

//path/to/file[@#]rev,[@#]rev

Uploading a diff of all files between two revisions in a directory:

//path/to/dir/...[#@]rev,[#@]rev

CVS and Subversion¶

CVS and Subversion don’t have a concept of changesets, so instead the working copy’s uncommitted changes are posted for review. To post a review request with all uncommitted files in a tree, simply run:

$ rbt post

This will create a new review request and post the diff of the uncommitted changes. If you want to update an existing review request with new changes instead, use the -r parameter. For example, to update review request #42, type:

$ rbt post -r 42

If you need to post specific files, leaving other uncommitted files out of the review request, you can include them on the command line, like so:

$ rbt post src/foo.c data/bar.png

Distributed Version Control Systems¶

When using a distributed version control system, such as Git or Mercurial, rbt post will by default post the diff between the current branch and the master branch. To post a new review request with the diff between the current branches commit, and the master branch, simply run:

$ rbt post

If you’d like to update an existing review request with new changes instead, use the -r parameter. For example, to update review request #42, type:

$ rbt post -r 42

You can also use the -u parameter to automatically determine the existing review request based on the patch summary and description:

$ rbt post -u

Additionally, rbt post can generate a summary and description for your review request based on the commit messages from the involved commits. This is accomplished using the -g parameter. To post a new review request with a generated summary and description, simply run:

$ rbt post -g

In the case where you are working on code based on a branch that isn’t available to the repository Review Board has configured, you’ll want to take advantage of rbt post’s parent diff support.

A parent diff is a diff between some known upstream revision that Review Board has access to and the parent of your branch. It’s used to provide a working baseline for your branch’s diff.

For example, in the case of Git, you may be working on the topicB branch, which has an ancestry that looks like:

o master
 \
  o---o topicA
       \
        o---o topicB

If you want to upload a diff of everything between topicA and topicB, you would need to tell rbt post to also generate a parent diff between master and topicA.

This is done by using the --parent parameter with the branch name. For example, in this case you would simply do:

$ rbt post --parent=topicA

That would generate a parent diff between master and topicA, and a normal diff of your changes between topicA and topicB. The changes in the parent diff won’t appear as changed lines in the diff viewer, meaning that users will only see changes made between topicB and topicA.

Tracking Branches¶

When using Git, rbt post makes the assumption that the closest upstream branch for the diff will be origin/master. This may be wrong if you are working on a feature branch or have a remote named something other than origin.

In this case, you will want to use the --tracking-branch option, which specifies the remote branch name. For example:

$ rbt post --tracking-branch=upstream/master

ClearCase¶

rbt post provides basic support for posting ClearCase reviews. If you want to post a review of all currently checked out files in your view simply run:

rbt post

If you collect changesets, for example, using ClearCase/ClearQuest integration, you can pass the changeset using --revision-range. Repository will be determined based on your current VOB’s UUID or name:

$ rbt post --revision-range="/vobs/proj/file.c@@/main/0;/vobs/proj/file.c@@/main/1"

Multiple files can be posted by adding additional file/revision pairs, all separated by semicolons:

$ rbt post --revision-range="/vobs/proj/file.c@@/main/0;/vobs/proj/file.c@@/main/1;/vobs/proj/file.h@@/main/0;/vobs/proj/file.h@@/main/1"

Another way for post-commit review is send changes developed on branch by --tracking option:

$ rbt post --tracking my_dev_branch

Note

rbt post trying match reviewboard’s repository based on VOB’s UUID. In case of problems Your VOB’s name will be used. Remember. You can always overwrite this behavior using .reviewboardrc `file or passing :option:–repository-url`.

Posting Committed Code¶

By default, rbt post assumes that you’re posting uncommitted code. This is called a pre-commit review. However, it’s sometimes useful to post code that has already been committed to a repository, such as in an experimental branch. This is a post-commit review.

In order to do this, you can use the --revision-range parameter, which will generate a diff based on a range of committed revisions. This allows a single review request to show a diff representing the entire history of a branch, if desired.

Usage is easy. Simply type:

$ rbt post --revision-range=STARTREV:STOPREV

Where STARTREV is the beginning revision in the range, and STOPREV is the ending revision, inclusive. If you only need to post a single revision, you can type:

$ rbt post --revision-range=REVISION

Posting Existing Diffs¶

rbt post will generate diffs automatically based on the repository type, but if you need to post a pre-existing diff, you can use the --diff-filename parameter to specify the path to the diff file.

For example:

$ rbt post --diff-filename=mycode.diff

You can also use the special value of - to pipe a diff into STDIN:

$ cat mycode.diff | rbt post --diff-filename=-

Using STDIN will require either a valid cookie, or the --username and --password options.

Automating rbt post¶

You can then invoke rbt post by doing the following:

$ rbt post --username=SPECIAL_USER --password=PASSWORD --submit-as=ANOTHER_USER

Of course, you can pass any other values as you see fit.

This will log in as SPECIAL_USER and perform operations as ANOTHER_USER.

You can set the default for --submit-as by setting SUBMIT_AS in .reviewboardrc.

Default Options¶

A number of options to rbt post can be set by default in .reviewboardrc. These can go either in the repository’s or the user’s .reviewboardrc file.

The options include:

BRANCH (--branch)
DEBUG (-d)
ENABLE_PROXY (--disable-proxy)
GUESS_DESCRIPTION (--guess-description)
GUESS_FIELDS (-g)
GUESS_SUMMARY (--guess-summary)
OPEN_BROWSER (-o)
P4_CLIENT (--p4-client)
P4_PASSWD (--p4-passwd)
P4_PORT (--p4-port)
PARENT_BRANCH (--parent)
PASSWORD (--password)
PUBLISH (-p)
REPOSITORY_TYPE (--repository-type)
SUBMIT_AS (--submit-as)
TARGET_GROUPS (--target-groups)
TARGET_PEOPLE (--target-people)
TRACKING_BRANCH (--tracking-branch)
USERNAME (--username)

Options¶

-d, –debug¶

Display debug output.

The default can be set in DEBUG in .reviewboardrc.

-r, –review-request-id¶: Existing review request ID to update.

-u, –update¶: Determine the existing review request to update.

–server¶

Specify a different Review Board server to use.

The default can be set in REVIEWBOARD_URL in .reviewboardrc.

–disable-proxy¶

Prevents requests from going through a proxy server.

The default can be set in ENABLE_PROXY in .reviewboardrc.

-p, –publish¶: Publish the review request immediately after submitting.

-o, –open¶

Open a web browser to the review request page.

The default can be set in OPEN_BROWSER in .reviewboardrc.

–target-groups¶

Names of the groups who will perform the review.

The default can be set in TARGET_GROUPS in .reviewboardrc.

–target-people¶

Names of the people who will perform the review.

The default can be set in TARGET_PEOPLE in .reviewboardrc.

–summary¶: Summary of the review.

–description¶: Description of the review.

–description-file¶: Text file containing a description of the review.

-g, –guess-fields¶

Equivalent to –guess-summary –guess-description.

The default can be set in GUESS_FIELDS in .reviewboardrc.

–guess-summary¶

Guess summary from the latest commit (bzr/Git/hg/hgsubversion only).

The default can be set in GUESS_SUMMARY in .reviewboardrc.

–guess-description¶

Guess description based on commits on this branch (bzr/Git/hg/hgsubversion only).

The default can be set in GUESS_DESCRIPTION in .reviewboardrc.

–testing-done¶: Details of testing done.

–testing-done-file¶: Text file containing details of testing done.

–branch¶

Affected branch.

The default can be set in BRANCH in .reviewboardrc.

–bugs-closed¶: List of bugs closed.

–change-description¶: Description of what changed in this revision of the review request when updating an existing request.

–revision-range¶: Generate the diff for review based on given revision range.

–submit-as¶

Username to be recorded as the author of the review request, instead of the logged in user. This is useful when used in a repository’s post-commit script to update or create review requests. See automating-rbt-post for information on this use case..

The default can be set in SUBMIT_AS in .reviewboardrc.

–username¶

Username to be supplied to the Review Board server.

The default can be set in USERNAME in .reviewboardrc.

–password¶

Password to be supplied to the Review Board server.

The default can be set in PASSWORD in .reviewboardrc.

–change-only¶: Updates info from changelist, but does not upload a new diff (only available if your repository supports changesets).

–parent¶

The parent branch this diff should be against (only available if your repository supports parent diffs).

The default can be set in PARENT_BRANCH in .reviewboardrc.

–tracking-branch¶

Tracking branch from which your branch is derived (git only, defaults to origin/master)

The default can be set in TRACKING_BRANCH in .reviewboardrc.

–p4-client¶

The Perforce client name that the review is in.

The default can be set in P4_CLIENT in .reviewboardrc.

–p4-port¶

The Perforce servers IP address that the review is on.

The default can be set in P4_PORT in .reviewboardrc.

–p4-passwd¶

The Perforce password or ticket of the user in the P4USER environment variable.

The default can be set in P4_PASSWD in .reviewboardrc.

–svn-changelist¶: Generate the diff for review based on a local SVN changelist.

–repository-url¶

The url for a repository for creating a diff outside of a working copy (currently only supported by Subversion with --revision-range or --diff-filename and 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 Git client.

The default can be set in REPOSITORY in .reviewboardrc.

–diff-filename¶: Upload an existing diff file, instead of generating a new diff.

–basedir¶: the absolute path in the repository the diff was generated in. Will override the detected path.

–repository-type¶

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

–svn-show-copies-as-adds¶

Treat copied or moved files as new files.

This is only supported in Subversion 1.7+.