Repository Configuration¶

There are many ways to configure rbt in order to associate a Review Board server with a repository. The ideal setup is to configure a repository to point to a Review Board server, so that users can use rbt out of the box, but there are other methods available.

All repository types support a .reviewboardrc file, which is the recommended way to configure your repository. Through here, you can specify the URL to your Review Board server, the repository name, and provide some helpful defaults.

Alternatively, some types of repositories can have special metadata associated that point to your server, but those don’t support some of the more advanced features of .reviewboardrc.

.reviewboardrc¶

The .reviewboardrc file is a generic place for configuring a repository. This must be in a directory in the user’s checkout path to work. It must parse as a valid Python file, or you’ll see an error when using rbt.

This is the recommended way of configuring your repository to talk to Review Board.

You can generate this file automatically, starting with RBTools 0.5.3, by typing:

$ rbt setup-repo

Just follow the instructions, and it will create your .reviewboardrc. You should then commit this to your repository.

The rest of this section covers some of the more common settings you may want for your .reviewboardrc. You can find more in the documentation for many of the commands. For example, see rbt post’s options.

The main configuration settings you’ll want to set are:

BRANCH
REPOSITORY
REPOSITORY_TYPE
REVIEWBOARD_URL
TRACKING_BRANCH (if using Git)

BASEDIR¶

Type: String

Default: Auto-detected

This is used only for Subversion repositories, and specifies a path within the repository that should be prepended to all files in a diff.

Example:

BASEDIR = "trunk/myproject/"

Note

This is normally not needed, as this information is auto-detected. It should only be set if there’s a specialized requirement.

This can also be provided by passing --basedir to most commands.

BRANCH¶

Type: String

Default: Unset

A review request’s Branch field is a helpful way of seeing where a change is expected to be merged into. You can specify the default for all review requests on a branch by setting the BRANCH field.

Note that the intent is to show the destination branch, and not the feature branch that the code is being developed on.

This also does not affect code generation. It’s used solely to display to the reviewers where the code will land.

Example:

BRANCH = "release-2.0.x"

This can also be provided by passing --branch to most commands.

CA_CERTS¶

Type: String

Default: Unset

A path to a custom SSL CA certifications file.

Example:

CA_CERTS = "/mnt/corp-shared/ssl/ca-certs.pem"

This can also be provided by passing --ca-certs to any command.

CLIENT_CERT¶

Type: String

Default: Unset

A path to a SSL certification file.

Example:

CLIENT_CERT = "/mnt/corp-shared/ssl/repo.pem"

This can also be provided by passing --client-cert to any command.

CLIENT_KEY¶

Type: String

Default: Unset

A path to a SSL client authentication key.

Example:

CLIENT_KEY = "/mnt/corp-shared/ssl/repo.key"

This can also be provided by passing --client-key to any command.

DEPENDS_ON¶

Commands: rbt post

Type: List of String

Default: Unset

A comma-separated list of review request IDs that any posted chagne will automatically depend on.

This is rarely needed, but can be useful if all the work being done on a branch depends on some main review request.

Example:

DEPENDS_ON = '42,43'

This can also be provided by using rbt post --depends-on.

ENABLE_PROXY¶

Type: Boolean

Default: True

By default, any configured HTTP/HTTPS proxy will be used for requests. If your server is within your own network, you may want to turn this off.

Example:

ENABLE_PROXY = False

This can also be disabled by passing --disable-proxy to any command.

EXCLUDE_PATTERNS¶

Type: List of String

Default: Unset

Excludes one or more files or file patterns from being posted for review. This uses standard UNIX glob patterns, like most shell commands.

Example:

EXCLUDE_PATTERNS = ['_build', '*.min.js', '.*.swp']

Patterns that begin with a path separator (/ on Mac OS and Linux, \\ on Windows) will be treated as being relative to the root of the repository. All other patterns are treated as being relative to the current working directory.

When working with Mercurial, the patterns are provided directly to hg and are not limited to globs. For more information on advanced pattern syntax in Mercurial, run hg help patterns.

When working with CVS, all diffs are generated relative to the current working directory so patterns beginning with a path separator are treated as relative to the current working directory.

When working with Perforce, an exclude pattern beginning with // will be matched against depot paths. All other patterns will be matched against local paths.

This can also be provided by passing --exclude to most commands.

INCLUDE_PATTERNS¶

Type: List of String

Default: Unset

Includes one or more files or file patterns when posting a review. Only these files will be posted by default. This uses standard UNIX glob patterns, like most shell commands.

Example:

INCLUDE_PATTERNS = ['src/*.c', 'doc/*.txt']

This can also be provided by passing --include to most commands.

LAND_DELETE_BRANCH¶

Commands: rbt land

Type: Boolean

Default: True

If enabled, and rbt land is landing a local branch, then that branch will be deleted once landed. This is the default behavior, as it indicates that work on that branch is complete.

Example:

LAND_DELETE_BRANCH = False

This can also be enabled by using rbt land --delete-branch, or disabled by using rbt land --no-delete-branch.

LAND_DEST_BRANCH¶

Commands: rbt land

Type: String

Default: Current branch

The branch where rbt land should land changes.

This is often set in common upstream branches where feature branches are derived from.

Example:

LAND_DEST_BRANCH = "release-4.x"

This can also be provided by using rbt land --dest.

LAND_SQUASH¶

Commands: rbt land

Type: Boolean

Default: False

If enabled, rbt land will squash all commits on a review request into a single commit before landing it, which can lead to cleaner, more linear commit histories.

Example:

LAND_SQUASH = True

This can also be enabled by using rbt land --squash, or disabled if using rbt land --no-squash.

LAND_PUSH¶

Commands: rbt land

Type: Boolean

Default: False

If enabled, rbt land will push the branch upstream once successfully landing a change.

Example:

LAND_PUSH = True

This can also be enabled by using rbt land --push, or disabled if using rbt land --no-push.

MARKDOWN¶

Commands: rbt post

Type: Boolean

Default: False

If enabled, any commit message used to auto-populate a review request’s description will be interpreted as valid Markdown.

This can be a useful setting if standardizing on Markdown-formatted commit descriptions, as it will also allow for nicely-formatted review requests by default.

Example:

MARKDOWN = True

This can also be enabled by using rbt post --markdown.

P4_PORT¶

Type: String

Default: Unset

The IP address or hostname of the Perforce server, overriding the P4PORT environment variable.

Example:

P4_PORT = "perforce.example.com:1666"

This can also be provided by passing --p4-port to most commands.

PARENT_BRANCH¶

Type: String

Default: Unset

A specific parent branch that the change should be generated from.

Note

This is rarely needed. Normally, you’ll just want to pass a revision range to rbt land or other commands.

REPOSITORY¶

Type: String

Default: Unset

By default, RBTools will try to determine the repository path and pass that to Review Board. This won’t always work in all setups, particularly when different people are checking out the repository with different URLs.

You can use the REPOSITORY setting to specify the name of the repository to use. This is the same as on Review Board’s New Review Request page.

Example:

REPOSITORY = "RBTools"

This can also be provided by passing --repository to any command.

REPOSITORY_TYPE¶

Type: String

Default: Unset

The type of the repository. If set, RBTools won’t have to scan to find the type of repository, which is a slow process.

Valid repository types include:

bazaar
clearcase
cvs
git
git
mercurial
perforce
plastic
svn
tfs

Example:

REPOSITORY_TYPE = "git"

This can also be provided by passing --repository-type to any command.

REPOSITORY_URL¶

Type: String

Default: Unset

The URL pointing to the upstream 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.

Example:

REPOSITORY_URL = "https://git.example.com/myrepo.git"

This can also be provided by passing --repository-url to most commands.

REVIEWBOARD_URL¶

Type: String

Default: Unset

To specify the Review Board server to use, you can use the REVIEWBOARD_URL setting. This takes the URL to the Review Board server as a value.

Example:

REVIEWBOARD_URL = "https://reviewboard.example.com"

This can also be provided by passing --server to any command.

SQUASH_HISTORY¶

New in version 2.0.

Commands: rbt post

Type: Boolean

Default: False

If enabled, rbt post will squash all commits comprising a review request into a single diff when uploading to Review Board. The default is to retain each commit so the reviewer has the option of reviewing each individually.

Example:

SQUASH_HISTORY = True

This can also be provided by using rbt post --squash.

TF_CMD¶

Type: String

Default: Auto-detected

The full path to the tf command, overriding any detected path. This can be useful if there’s a central copy of this command on a shared drive.

Example:

TF_CMD = "/opt/tfs/bin/tf"

This can also be provided by passing --tf-cmd to most commands.

TRACKING_BRANCH¶

Type: String

Default: Unset

When using Git or other DVCS repositories, RBTools makes an assumption about the upstream branch, which it needs to know in order to generate a diff. You can set the TRACKING_BRANCH setting to the branch name in order to force the usage of a specific branch. This is equivalent to providing the --tracking-branch option.

We recommend you set this for any .reviewboardrc files on any long-running release or feature branches.

Example:

TRACKING_BRANCH = "origin/release-2.0.x"

This can also be provided by passing --tracking-branch to most commands.

Git Properties¶

Repository information can be set in a reviewboard.url property on the Git tree. Users may need to do this themselves on their own Git tree, so in some cases, it may be ideal to use dotfiles instead.

To set the property on a Git tree, type:

$ git config reviewboard.url http://reviewboard.example.com

Perforce Counters¶

Repository information can be set on Perforce servers by using reviewboard.url Perforce counters. How this works varies between versions of Perforce.

Perforce version 2008.1 and up support strings in counters, so you can simply do:

$ p4 counter reviewboard.url http://reviewboard.example.com

Older versions of Perforce support only numeric counters, so you must encode the server as part of the counter name. As / characters aren’t supported in counter names, they must be replaced by | characters. | is a special character in shells, so you’ll need need to escape these using \|. For example:

$ p4 counter reviewboard.url.http:\|\|reviewboard.example.com 1

Subversion Properties¶

Repository information can be set in a reviewboard:url property on a directory. This is usually done on whatever directory or directories are common as base checkout paths. This usually means something like /trunk or /trunk/myproject. If the directory is in the user’s checkout, it will be faster to find the property.

To set the property on a directory, type:

$ svn propset reviewboard:url http://reviewboard.example.com .