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.
Verified against CLI v0.58.3
.treeline.yml
Lives in your project root, committed to git. Defines what GTL provisions for each worktree.
project string
Project name. Used as a namespace for allocations and database naming.
merge_target string
Branch that prune --merged checks against and template database updates fetch from origin. Uses the remote default branch when available, otherwise main.
port_count int
Number of ports to allocate per worktree. Default 1. Changes require gtl setup since port allocation affects the shared registry.
env_file string or map
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). Both paths must be relative to their project root; absolute paths, parent traversal, and symlinks escaping that root are rejected.
database.adapter string
postgresql or sqlite. Databases are cloned during gtl new. To re-clone: gtl db reset.
database.template string
Source database to clone from. For PostgreSQL, used with createdb --template.
database.name string
Naming pattern for cloned databases. Tokens: {template}, {worktree}. Formerly database.pattern — old key is still accepted as a fallback. The resolved name is available in env as {database} or {database.name}.
database.host string
Explicit host for database connections (e.g. localhost). Forces TCP instead of Unix socket connections. Required when GTL is spawned from a native macOS app (e.g. Treeline.app) to avoid Postgres.app's bundle-authorization dialog.
database.port int
Database port. Only needed when your PostgreSQL instance runs on a non-default port.
database.user string
Database user for connections and createdb/dropdb operations. Defaults to the current OS user.
database.sync_on_create bool
When true, fetches the remote merge_target and runs commands.migrate in a temporary detached checkout before a fresh database clone. Existing checkout branches and worktree databases stay unchanged. Requires Git 2.29+, commands.migrate, and an env mapping using a primary database token. Missing that mapping warns and continues with the existing template; --strict fails instead. See template updates for migration requirements.
database.sources map
Named remote sources for gtl db pull <env>. Each key is an env name (e.g. production, staging). Three source types — all store only a variable name or app reference, never a raw URL:
-
via: fly— fetches the URL from a Fly app's environment viafly ssh console. Requiresapp:. Optionalvar:overrides the env var read on the remote (defaultDATABASE_URL). -
via: heroku— fetches viaheroku config:get <var> -a <app>. Requiresapp:. Optionalvar:(defaultDATABASE_URL). -
via: env— reads apostgres://URL from a local environment variable. Requiresvar:(the env var name, not the URL). Use for platforms without native support: 1Password-injected env, bastion tunnels, Neon, RDS, etc.
database:
sources:
production:
via: fly # or heroku
app: my-fly-app
staging:
via: env
var: STAGING_DATABASE_URL # name of a local env var database.extra map or list
Auxiliary database names to allocate and track alongside the primary one. Each map key is an identifier; its value is a string naming pattern. Your framework or commands.setup must create these databases; Treeline does not clone them. A list of string patterns is also supported. Each named extra database is accessible in env via the dotted token {database.extra.queue} (replace queue with the key name). Dotted tokens are paths to config fields; bare tokens like {database} are Treeline-minted aliases.
database:
extra:
queue: "{database.name}_queue"
env:
QUEUE_DATABASE_URL: "postgresql://localhost/{database.extra.queue}" provision section
Host-level baseline for gtl provision. Declaring the section (even partially) opts the repo in: a provision run then also installs pinned language runtimes via mise — those come from the repo’s own version files (.ruby-version, .tool-versions), never from yml. No provision: section means gtl provision is a friendly no-op. Provision commands run non-interactively (stdin is EOF; passwordless sudo expected on remote hosts).
provision.apt list
apt packages to install before gtl setup. Linux only — skipped with a note on macOS. Runs apt-get update lazily before the first install. Each package is checked via dpkg before installing; already-installed packages are skipped. Requires sudo.
provision:
apt: [libvips, imagemagick] provision.services list
Services to apt-install and enable via systemctl enable --now. Linux only. Each entry is both the package name and the service unit name. Installed and enabled only if not already active.
provision:
services: [redis-server] provision.database.template string
Optional override for the template database name. Defaults to the top-level database.template — the same database gtl setup clones each worktree’s database from, so provision creates exactly what setup consumes. When neither source nor hydrate is declared, a missing template is created empty with a warning.
provision.database.source string
Named source (from database.sources) to hydrate the template database from. Reuses the same gtl db pull machinery — pg_dump from the remote, restore into the template. Skipped for non-PostgreSQL adapters.
provision.database.hydrate string
Fallback command to populate the template database when no source is configured or available. Runs in the repo directory via sh -c, like setup commands, and must be non-interactive. Example: bin/rails db:schema:load db:seed. Skipped if the template database already exists.
provision:
database:
source: production # hydrate from a named remote source
hydrate: "bin/rails db:schema:load db:seed" # fallback copy_files list
Files to copy from the main worktree, such as credentials and local config that aren't in git. Paths must be relative and stay inside both project roots; absolute paths, parent traversal, and escaping symlinks are rejected. Also copied into the temporary checkout for template migrations.
env map
Key-value pairs written to the env file. Supports interpolation tokens. Synced on fresh gtl start and gtl restart. Manual: gtl env sync.
aliases map
Project-level router aliases. Map of alias name to port offset. Resolved per-worktree. See Networking: Aliases.
commands.migrate string
Migration command run by gtl db template update and when database.sync_on_create is true. Runs in a fresh detached checkout with primary database tokens bound to database.template. Setup commands and hooks do not run, so this command must prepare any dependencies it needs. Example when dependencies are available: bin/rails db:migrate.
commands.setup list
Commands to run after env file is written. Not re-run on gtl start. Manual: gtl setup or gtl switch --setup.
commands.start string
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.
editor.title string
Window title template. Tokens: {project}, {port}, {branch}, {url}, {router_url}. VS Code and Cursor.
editor.color string
Title/status bar color. "auto" generates a deterministic color from the branch name. Or a hex value. VS Code, Cursor, JetBrains.
editor.theme string
Full IDE theme override applied when entering the worktree.
hooks.pre_setup list
Shell commands before commands.setup. On failure, setup aborts.
hooks.post_setup list
Shell commands after commands.setup and editor. On failure, warns only.
hooks.pre_release list
Shell commands after release confirmation, before freeing resources. On failure, release aborts.
hooks.post_release list
Shell commands after free/drop. On failure, warns only.
hooks.<name>.pre_start string or list
Shell commands before the supervisor launches. Activated via gtl start --with <name> or auto: true. Supports {port}. Failure aborts the start. See Hooks guide.
hooks.<name>.post_stop string or list
Shell commands on graceful supervisor exit (Ctrl+C), in reverse order. Errors logged, not fatal.
hooks.<name>.auto bool
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} | Primary cloned database name (bare alias for {database.name}) | env |
| {database.name} | Primary cloned database name (dotted path form) | env |
| {database.extra.<key>} | Name of an auxiliary database declared in database.extra (e.g. {database.extra.queue}) | 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_host} |
Router domain only (e.g. prt.dev). For host whitelisting and cookie domains.
| env |
| {router_domain} |
Deprecated alias for {router_host}. Kept for backwards compatibility — use {router_host} in new configs.
| env |
| {tunnel_url} |
Full tunnel URL (e.g. https://myapp-feature.gtltunnel.dev). Requires a named tunnel via gtl tunnel setup.
| 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_host} 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. ({router_domain} is a deprecated alias for the same value.)
{tunnel_url} is the full public tunnel URL (e.g. https://myapp-feature.gtltunnel.dev). Use when you need to inject the tunnel origin into your app config — for example, an allowed redirect URI or webhook endpoint that outside services should call. Requires a named tunnel configured via gtl tunnel setup.
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/)
|
port.base
Starting port number for allocations. Ports 3000 and 3001 are reserved for gtl proxy and the HTTPS router.
port.reservations
Map of project (or project/branch) to pinned port number. Branch-specific keys take priority.
redis.strategy
prefixed for key namespacing (unlimited worktrees) or database for separate Redis DBs (1-15).
router.domain
Base domain for the HTTPS router. To switch: gtl serve uninstall && gtl config set router.domain prt.dev && gtl serve install.
router.mode
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.
editor.name
Detected editor (Cursor, VS Code, Zed, JetBrains). Set by gtl install or gtl init.
editor.themes
Per-project or per-branch theme overrides. Keys: project or project/branch.
worktree.path
Where gtl new creates worktrees. Supports {project} and {branch}. Paths inside the repo are auto-gitignored.
review.skip_switch_confirm
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.