Per-User Configuration¶

There’s a lot of flexibility when it comes to the RBTools setup. You can provide your own defaults for nearly all RBTools command options, and can define custom aliases to improve your workflows.

Like with repository configuration, these settings are stored in a .reviewboardrc file. These can go in the repository’s own version of the file, if these options should apply to all users by default. Otherwise, they can go in the .reviewboardrc in your home directory.

On Linux and MacOS X, this file can be found in your home directory.

On Windows, it’s in $USERPROFILE\Local Settings\Application Data.

If you need to override repository-wide settings for yourself, you can set $RBTOOLS_CONFIG_PATH to a list of paths, separated by colons (Linux, Mac OS X) or semicolons (Windows). These paths are searched first for .reviewboardrc files.

Custom Option Defaults¶

Most options to RBTools commands allow for custom defaults. Each command has documentation on what to set to change the default.

For instance, if you look at the rbt post documentation, you’ll see that you can automatically open your browser when posting a review request by setting:

OPEN_BROWSER = True

Or, you can disable usage of your HTTP proxy on any command by setting:

ENABLE_PROXY = False

The following options might be useful to set in your own .reviewboardrc file. This can also contain anything normally found in a repository’s .reviewboardrc.

API_TOKEN¶

Type: String

Default: Unset

Your Review Board API token, for logging into Review Board.

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

Warning

We recommend that you provide your credentials only on demand, rather than setting this in a file. However, this can be useful for specialized automation in a locked-down environment.

CACHE_LOCATION¶

Type: String

Default: See Cache Database

A custom path used to store any cached HTTP responses.

Example:

CACHE_LOCATION = "/tmp/rbtools-cache"

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

COOKIES_STRICT_DOMAIN_MATCH¶

New in version 5.1.

Type: Boolean

Default: False

RBTools uses cookies to manage Review Board login sessions. By defaut, if RBTools has stored cookies for both a domain and a parent domain (e.g., staging.rb.example.com and rb.example.com), both cookies may be passed, and this may interfere with authentication.

Setting COOKIES_STRICT_DOMAIN_MATCH = True will only match cookies that exactly match the domain name you’re connecting to.

Example:

COOKIES_STRICT_DOMAIN_MATCH = True

DEBUG¶

Type: Boolean

Default: False

If enabled, RBTools commands will output extra debug information.

Example:

DEBUG = True

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

DISABLE_CACHE¶

Type: Boolean

Default: False

If enabled, HTTP responses will be cached (either in memory or saved to a local cache – see IN_MEMORY_CACHE), speeding up subsequent requests.

If disabled, RBTools always perform full HTTP requests.

Example:

DISABLE_CACHE = True

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

DISABLE_SSL_VERIFICATION¶

Type: Boolean

Default: False

If enabled, SSL certificates won’t be verified.

Example:

DISABLE_SSL_VERIFICATION = True

Warning

Disabling SSL verification presents a security risk. We instead recommend using CA_CERTS.

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

EXT_AUTH_COOKIES¶

Type: String

Default: Unset

This can be set to a local file path to use an existing pre-fetched cookie store, which can be useful for automation. This file must be compatible with Python’s urllib2 cookie

Example:

EXT_AUTH_COOKIES = "/opt/scripts/rbtools/cookies.txt"

This can also be provided by passing --ext-auth-cookies to any command.

GUESS_FIELDS¶

Commands: rbt post

Type: String

Default: "auto"

The default behavior for guessing the value for the review request’s intended summary and description based on the posted commit’s message (on repositories that support posting from an existing commit). This can be set to "yes", "no", or "auto".

If set to "yes", then the review request’s fields will always be set, overriding any manual changes you’ve made the next time you run rbt post.

If set to "no", then the review request’s fields will never be updated.

If set to "auto" (the default), then only newly-posted review requests will have their fields updated. Updates to an existing review request won’t override any fields.

See Controlling Guessing Behavior for more information.

For example:

GUESS_FIELDS = "yes"

This can also be provided by using rbt post --guess-fields.

GUESS_DESCRIPTION¶

Commands: rbt post

Type: String

Default: Value of GUESS_FIELDS

The default behavior for guessing a review request’s intended description based on the posted commit’s message.

Most of the time, you’ll just want to use GUESS_FIELDS. See Controlling Guessing Behavior for additional information.

Example:

GUESS_DESCRIPTION = "no"

This can also be provided by using rbt post --guess-description.

GUESS_SUMMARY¶

Commands: rbt post

Type: String

Default: Value of GUESS_FIELDS

The default behavior for guessing a review request’s intended summary based on the posted commit’s message.

Most of the time, you’ll just want to use GUESS_FIELDS. See Controlling Guessing Behavior for additional information.

Example:

GUESS_DESCRIPTION = "yes"

This can also be provided by using rbt post --guess-summary.

IN_MEMORY_CACHE¶

Type: Boolean

Default: False

If enabled, any cached HTTP responses will be stored only in local memory, and not saved to disk.

If disabled, and DISABLE_CACHE isn’t used, HTTP responses will be saved locally.

See CACHE_LOCATION for configuring the cache location.

Example:

IN_MEMORY_CACHE = True

This can also be enabled by passing --disable-cache to any command.

OPEN_BROWSER¶

Commands: rbt post

Type: Boolean

Default: False

If set, a web browser will be opened to the review request after running rbt post.

Example:

OPEN_BROWSER = True

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

P4_CLIENT¶

Type: String

Default: Unset

The Perforce client name to use, overriding the default for your local setup.

Example:

P4_CLIENT = "my-client"

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

P4_PASSWD¶

Type: String

Default: Unset

The password or ticket for your Perforce user, corresponding to the user set in the P4USER environment variable.

Example:

P4_PASSWD = "ticket123"

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

Warning

We recommend that you provide your credentials through a p4 login, rather than setting this in a file. However, this can be useful for specialized automation in a locked-down environment.

PASSWORD¶

Type: String

Default: Unset

Your password, for logging into Review Board.

Example:

PASSWORD = "s3cr3t"

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

Warning

We recommend that you provide your credentials only on demand, rather than setting this in a file. However, this can be useful for specialized automation in a locked-down environment.

PUBLISH¶

Commands: rbt post

Type: Boolean

Default: False

If set, any new review request drafts will be automatically published. This does require all fields on the review request to be provided.

Example:

PUBLISH = True

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

SAVE_COOKIES¶

Type: Boolean

Default: True

If enabled, cookies will be saved after logging in (see Cookies for cookie store location).

If disabled, no cookies will be stored, and the next RBTools command will require logging in again.

Example:

SAVE_COOKIES = False

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

STAMP_WHEN_POSTING¶

Commands: rbt post

Type: Boolean

Default: False

If enabled, the latest commit for a review request will be stamped with the review request URL when posting the commit for review.

Example:

STAMP_WHEN_POSTING = True

This can also be enabled by using rbt post --stamp-when-posting.

SUBMIT_AS¶

Commands: rbt post

Type: String

Default: Unset

The username to use instead of the logged-in user when posting a change for review. This is useful for automation, enabling a script to post changes on behalf of users.

This requires that the logged-in user is either an administrator or has the reviews.can_submit_as permission set.

Most of the time, it won’t make much sense to put this in .reviewboardrc. Using rbt post --submit-as might be a better option.

Example:

SUBMIT_AS = "other-user"

TREES¶

Type: Dictionary

Default: Unset

This setting allows a central .reviewboardrc file to override settings for individual repositories or directories. This is defined as a dictionary where the keys can be either the remote or local repository paths. The values should be a dictionary of configuration settings to apply for that directory or repository.

This was available in RBTools 4 and earlier, but was previously limited to just the REVIEWBOARD_URL setting. As of RBTools 5.1, this allows including any configuration settings.

TREES = {
    'https://svn.example.com/': {
        'REVIEWBOARD_URL': 'https://reviews.example.com',
    },
    '/home/user/dev': {
        'MARKDOWN': False,
        'TRACKING_BRANCH': 'origin/rewrite',
    }
}

USERNAME¶

Type: String

Default: Unset

Your username, for logging into Review Board.

Example:

USERNAME = "myuser"

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

Warning

We recommend that you provide your credentials only on demand, rather than setting this in a file. However, this can be useful for specialized automation in a locked-down environment.

Environment Variables¶

You can set the following environment variables to customize the RBTools experience:

RBTOOLS_CONFIG_PATH¶

A list of paths to check for .reviewboardrc files. These paths will be checked before any other location.

Each path should be separated using the native environment path separator on your platform (: on Linux/UNIX/macOS, ; on Windows).

RBTOOLS_EDITOR¶

VISUAL¶

EDITOR¶

These specify a text editor to use to edit commits or other content. The given editor is invoked when running commands like rbt land --edit or rbt patch --commit.

We recommending using RBTOOLS_EDITOR, but any of the above environment variables are supported for compatibility purposes. They order of precedence is the order shown above.

New in version 1.0.3: Added support for RBTOOLS_EDITOR.

Aliases¶

rbt can be configured to add command aliases. The ALIASES value in .reviewboardrc can be added to allow for command aliasing. It is a dictionary where the keys are the alias names and the value is the command that will be executed.

Aliases will only be executed when an rbt command is executed that rbt does not recognize and when rbt-<commandname> does not exist in the path. Aliases are case-sensitive.

For example, consider the following aliases:

ALIASES = {
    'post-this': 'post HEAD',
    'push': '!git push && rbt close $1'
}

The following commands are equivalent:

$ rbt post-this
$ rbt post HEAD

As are the following:

$ rbt push 3351
$ git push && rbt close 3351

Types of Aliases¶

There are two types of aliases: aliases for other rbt commands and system aliases.

Aliases For Other rbt Commands¶

These aliases allow short forms for frequently used rbt commands with parameter substitution. An alias of the form cmd is equivalent to calling rbt cmd. This will launch another instance of rbt and therefore can be used to reference other aliases or commands of the form rbt-<commandname>.

System Command Aliases¶

System aliases are aliases that begin with !. These aliases are more flexible because they are executed by the shell. However, since they are more powerful it is possible to write an alias that will destroy data. Everything after the ! will be passed to the shell for execution after going through parameter substitution.

Positional Parameter Substitution¶

Aliases in rbt supports inserting bash-like variables representing positional arguments into aliases. Positional variables take the form $1 (which corresponds to the first argument), $2 (which corresponds to the second argument), etc., and $* (which corresponds to all arguments).

If a positional variable is specified and not enough arguments were specified, it will be replaced with an empty argument.

If no parameter substitution is performed, all supplied arguments will be appended to the command when it is executed. Non-numeric variables are not replaced in the parameter and, if the alias is a system command alias, will be handled by the shell.

Special Files¶

Cookies¶

The rbt command stores its login session in a cookies file called ~/.rbtools-cookies. To force RBTools to log in again, simply delete this file.

If the file is missing, RBTools will check for a legacy ~/.post-review-cookies.txt file. This is for compatibility with the old post-review command.

Cache Database¶

The rbt command stores cached API request responses in a SQLite database in a cache directory. This is to reduce the time it takes to perform certain API requests.

On macOS, this is in ~/Library/Caches/rbtools/apicache.db.

On Linux, this is in ~/.cache/.rbtools/apicache.db.

On Windows, this is in %APPDATA%\rbtools\rbtools\apicache.db.

This location can be controlled by setting CACHE_LOCATION.

To delete the cache, either remove this file, or call rbt clear-cache.