Configuration

rft works without any configuration. When you need to customize behavior, create a config file in your repository root.

Configuration Files

rft looks for configuration in the following order:

1. .rftrc.toml (recommended, committed)
2. .rftrc.json
3. package.json (under the rft key)

Only the first found file is used.

Local overrides

Create .rftrc.local.toml for personal settings that shouldn't be committed (e.g., host). Fields from the local file merge on top of the shared config:

# .rftrc.local.toml (gitignored)
host = "192.168.1.50"
port_offset = 30000

rft init automatically adds .rftrc.local.toml to .gitignore.

Priority: .rftrc.toml → .rftrc.local.toml → environment variables.

Options

sync

Extra files and directories to copy into each worktree alongside the compose file and Dockerfiles.

sync = ["nginx/", "scripts/init.sql", "Makefile"]

Directories are copied recursively. Paths are relative to the repository root.

port_offset

Override the base offset for port allocation. Default is 20000.

port_offset = 30000

See Port Allocation for the full formula.

main_branch

Override the name of the main branch. By default, rft auto-detects main or master. Set this if your main branch has a different name.

main_branch = "develop"

rft excludes the main branch from worktree management — it keeps default ports and is never started/stopped by rft.

host

The hostname used for clickable port links in rft list. Default is localhost.

host = "192.168.1.50"

Typically set in .rftrc.local.toml since it's machine-specific.

project_name_source

Controls how Docker Compose project names are generated. Default is "directory".

project_name_source = "directory"

With "directory", Docker volumes persist across branch switches within the same worktree — your database survives git switch.

env_overrides

Environment variable templates injected into each worktree's .env. Use ${VAR} syntax to reference allocated port values.

[env_overrides]
API_URL = "http://localhost:${API_PORT}"
WEBSOCKET_URL = "ws://localhost:${WS_PORT}"
CORS_ORIGIN = "http://localhost:${FRONTEND_PORT}"

This is useful when services need to know each other's URLs, not just ports.

JSON Format

The same configuration in .rftrc.json:

{
  "sync": ["nginx/", "scripts/init.sql"],
  "port_offset": 30000,
  "main_branch": "develop",
  "env_overrides": {
    "API_URL": "http://localhost:${API_PORT}",
    "CORS_ORIGIN": "http://localhost:${FRONTEND_PORT}"
  }
}

package.json

For JavaScript/TypeScript projects, you can embed the configuration in package.json:

{
  "name": "my-app",
  "rft": {
    "sync": ["nginx/"],
    "env_overrides": {
      "API_URL": "http://localhost:${API_PORT}"
    }
  }
}

Environment Variables

These environment variables override config file values:

Environment variables take precedence over all config file values (including .rftrc.local.toml).