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. The settings listed in this file are oriented towards user preferences, and should most likely be set in a .reviewboardrc file in your home directory, but these can also be used in repository-specific configurations, if you want to set behavior for all users.

The user configuration file from your home directory is loaded last, so any settings in a repository-specific file will override them. If you need to override repository settings for yourself, you have two options:

Set $RBTOOLS_CONFIG_PATH to a list of paths (separated by colons for Linux and Mac OS, or semicolons for Windows). Files in this path are loaded with the highest priority.
Use TREES to specify overrides based on filesystem or repository path.

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¶

Added in version 5.1.

Type: Boolean

Default: False

RBTools uses cookies to manage Review Board login sessions. By default, 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.

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.

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_SUMMARY = "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¶

Type: Boolean

Default: False

For commands that navigate you to a URL, this will automatically open a browser to the URL.

If set, this will affect the following:

When authenticating to a command with --web-login, this will open a browser to the Review Board login page.
After running rbt post a web browser will be opened to the review request.

Example:

OPEN_BROWSER = True

This can also be provided by using --open-browser.

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.

Added in version 1.0.3: Added support for RBTOOLS_EDITOR.

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.