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 string

Project name. Used as a namespace for allocations and database naming.

merge_target string

Branch that prune --merged checks against. Auto-detected from remote if omitted.

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).

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.pattern string

Naming pattern for cloned databases. Tokens: {template}, {worktree}.

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, pulls merge_target and runs commands.migrate in the root repo before cloning a new worktree database. Ensures every new worktree starts with a current schema. Only fires on fresh database clones — refresh, reallocate, and rename flows are unaffected. Requires commands.migrate.

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
copy_files list
requires gtl setup

Files to copy from the main worktree. Secrets, credentials, local config that aren't in git. Run during provisioning only.

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. Example: 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} 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_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/)
Windows %APPDATA%/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.

Related

Back to docs