Skip to content

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

requires gtl setup

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

destructive

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

default: false

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 via fly ssh console. Requires app:. Optional var: overrides the env var read on the remote (default DATABASE_URL).
  • via: heroku — fetches via heroku config:get <var> -a <app>. Requires app:. Optional var: (default DATABASE_URL).
  • via: env — reads a postgres:// URL from a local environment variable. Requires var: (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

requires gtl setup

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

auto-synced

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

requires gtl setup

Commands to run after env file is written. Not re-run on gtl start. Manual: gtl setup or gtl switch --setup.

commands.start string

fresh start only

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

auto-synced

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

--with or auto

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

default: false

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

default: 3002

Starting port number for allocations. Ports 3000 and 3001 are reserved for gtl proxy and the HTTPS router.

port.increment

default: 2

Gap between port allocations. Must be ≥ your port_count.

port.reservations

default: {}

Map of project (or project/branch) to pinned port number. Branch-specific keys take priority.

redis.strategy

default: prefixed

prefixed for key namespacing (unlimited worktrees) or database for separate Redis DBs (1-15).

redis.url

default: redis://localhost:6379

Redis server URL used for namespace assignment.

router.domain

default: prt.dev (new) / localhost (existing)

Base domain for the HTTPS router. To switch: gtl serve uninstall && gtl config set router.domain prt.dev && gtl serve install.

router.port

default: 3001

Port the HTTPS router listens on. Must not equal port.base.

router.aliases

default: {}

User-defined alias name to target port. Managed via gtl serve alias.

router.mode

default: prompt

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

auto-detected

Detected editor (Cursor, VS Code, Zed, JetBrains). Set by gtl install or gtl init.

editor.themes

default: {}

Per-project or per-branch theme overrides. Keys: project or project/branch.

editor.colors

default: {}

Per-project or per-branch color overrides. Same key format.

worktree.path

default: sibling directory

Where gtl new creates worktrees. Supports {project} and {branch}. Paths inside the repo are auto-gitignored.

tunnel.name

set by gtl tunnel setup

Cloudflare tunnel name.

tunnel.domain

set by gtl tunnel setup

Domain for named tunnel subdomains.

warnings.safari

default: true

Show Safari resolution warnings. Rarely needed with prt.dev.

review.skip_switch_confirm

default: false

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.

Back to docs