Docs / Configuration
Configuration reference
Two config layers: .treeline.yml in your repo (project-level, committed) and a user config on your machine (per-developer, not committed). This page is a pure reference for every field.
.treeline.yml
Lives in your project root, committed to git. Defines what GTL provisions for each worktree.
Project name. Used as a namespace for allocations and database naming.
Branch that prune --merged checks against. Auto-detected from remote if omitted.
Number of ports to allocate per worktree. Default 1. Changes require gtl setup since port allocation affects the shared registry.
Env file path as a string shorthand (e.g. .env.local). When the output file differs from the seed, use a map: path: (where values are written) and seed_from: (source template to copy first).
postgresql or sqlite. Databases are cloned during gtl new. To re-clone: gtl db reset.
Source database to clone from. For PostgreSQL, used with createdb --template.
Naming pattern for cloned databases. Tokens: {template}, {worktree}.
Files to copy from the main worktree. Secrets, credentials, local config that aren't in git. Run during provisioning only.
Key-value pairs written to the env file. Supports interpolation tokens. Synced on fresh gtl start and gtl restart. Manual: gtl env sync.
Project-level router aliases. Map of alias name to port offset. Resolved per-worktree. See Networking: Aliases.
Commands to run after env file is written. Not re-run on gtl start. Manual: gtl setup or gtl switch --setup.
Command to boot the app. Read on fresh gtl start only. If the supervisor is alive, it uses the original command. gtl restart warns on mismatch.
Window title template. Tokens: {project}, {port}, {branch}, {url}, {router_url}. VS Code and Cursor.
Title/status bar color. "auto" generates a deterministic color from the branch name. Or a hex value. VS Code, Cursor, JetBrains.
Full IDE theme override applied when entering the worktree.
Shell commands before commands.setup. On failure, setup aborts.
Shell commands after commands.setup and editor. On failure, warns only.
Shell commands after release confirmation, before freeing resources. On failure, release aborts.
Shell commands after free/drop. On failure, warns only.
Shell commands before the supervisor launches. Activated via gtl start --with <name> or auto: true. Supports {port}. Failure aborts the start. See Hooks guide.
Shell commands on graceful supervisor exit (Ctrl+C), in reverse order. Errors logged, not fatal.
When true, this hook runs on every fresh gtl start without --with.
Interpolation tokens
Used in the env map. Replaced with allocated values at setup time and env sync.
| Token | Value | Available in |
|---|---|---|
| {port} | Primary allocated port | env, commands.start, hooks |
| {port_2} ... {port_10} |
Additional allocated ports (when port_count > 1)
| env, commands.start, hooks |
| {database} | Cloned database name | env |
| {redis_url} | Redis URL with namespace applied | env |
| {redis_prefix} | Redis key prefix (prefix strategy) | env |
| {project} | Project name from config | env |
| {worktree} | Worktree directory name | env |
| {branch} | Branch name of this worktree | editor.title only |
| {router_url} |
HTTPS URL (https://myapp-feature.prt.dev). Requires gtl serve.
| env |
| {router_domain} |
Router domain only (e.g. prt.dev). For host whitelisting and cookie domains.
| env |
| {tunnel_host} |
Bare tunnel domain (e.g. gtltunnel.dev). For cookie domains, CORS wildcards, or any config that needs the tunnel base without the project-branch subdomain.
| env |
| {resolve:project} |
Base URL (http://127.0.0.1:{port}) of another project. Default branch matches current worktree; gtl link overrides.
| env |
| {resolve:project/branch} | Same, pinned to a specific branch. Link overrides do not apply. | env |
When to use each host token
localhost:{port} is your app's canonical listen address. The safe default. Works whether or not gtl serve is running. Use for HOST, APP_URL, default_url_options, mailer host, and anything that must keep working if the router is down.
{router_url} is the HTTPS branch URL (e.g. https://myapp-feature.prt.dev). Use when a value specifically needs the routed HTTPS origin: CORS allowed origins, CSP directives, or OAuth redirect URIs. Depends on gtl serve.
{router_domain} is just the domain (e.g. prt.dev). Use for host whitelisting, cookie domains, or wildcard CSP entries. Required if your framework validates the Host header.
See OAuth callbacks across worktrees for a full walkthrough.
User config
Per-machine settings. Manage with gtl config list, get, set, path, edit.
| Platform | Path |
|---|---|
| macOS | ~/Library/Application Support/git-treeline/ |
| Linux | $XDG_CONFIG_HOME/git-treeline/ (defaults to ~/.config/git-treeline/)
|
| Windows | %APPDATA%/git-treeline/ |
Starting port number for allocations. Ports 3000 and 3001 are reserved for gtl proxy and the HTTPS router.
Gap between port allocations. Must be ≥ your port_count.
Map of project (or project/branch) to pinned port number. Branch-specific keys take priority.
prefixed for key namespacing (unlimited worktrees) or database for separate Redis DBs (1-15).
Redis server URL used for namespace assignment.
Base domain for the HTTPS router. To switch: gtl serve uninstall && gtl config set router.domain prt.dev && gtl serve install.
Port the HTTPS router listens on. Must not equal port.base.
User-defined alias name to target port. Managed via gtl serve alias.
Controls HTTPS router intent. prompt offers router setup during gtl install. enabled auto-repairs the router when needed. disabled suppresses prompts and uses localhost-only workflows.
Detected editor (Cursor, VS Code, Zed, JetBrains). Set by gtl install or gtl init.
Per-project or per-branch theme overrides. Keys: project or project/branch.
Per-project or per-branch color overrides. Same key format.
Where gtl new creates worktrees. Supports {project} and {branch}. Paths inside the repo are auto-gitignored.
Cloudflare tunnel name.
Domain for named tunnel subdomains.
Show Safari resolution warnings. Rarely needed with prt.dev.
When true, gtl review <PR> from inside an existing worktree switches the current worktree to the PR branch without prompting. For users who always want to switch.
Related
- Hooks guide: how lifecycle and start hooks work.
- Networking guide: port allocation, routing, and the full networking stack.
- CLI reference: every command and flag.