Skip to content

Git Treeline · Worktree provisioner

Run Git worktrees without port or database conflicts.

Give each branch its own ports, database, and environment config. Define your setup once in .treeline.yml, then create a ready-to-run worktree with one command.

brew install git-treeline/tap/git-treeline

macOS & Linux · PostgreSQL or SQLite · Optional local HTTPS

v0.58.3 Upgrade guide

Worktrees are easy to create. Hard to run.

A git worktree is a separate checkout of your repo in its own directory — git worktree add creates one in seconds. Without per-worktree configuration, those checkouts can compete for the same ports and databases.

without git-treeline

~/feature-a $ npm run dev

▸ Ready on http://localhost:3000

~/feature-b $ bin/dev

Error: listen EADDRINUSE : :3000

~/feature-b $ psql -c "CREATE DATABASE myapp_dev"

ERROR: database "myapp_dev" already exists

with git-treeline

~ $ gtl new feature-auth

Creating worktree feature-auth

Allocated port 3010

Cloned database myapp_dev_feature_auth

Wrote .env.local

Running setup commands...

==> https://myapp-feature-auth.prt.dev

named URL via gtl serve (one-time setup)

Your worktrees should be provisioned, not duct‑taped.

Port 3000 stays free. On purpose.

OAuth callbacks, Mapbox allowlists, and CORS rules often depend on a fixed local origin. Treeline reserves port 3000 by default so gtl proxy can forward that origin to the worktree you choose.

$ gtl proxy 3000

Proxying :3000 → :4010 (feature-auth)

# OAuth callback → :4010

# Stripe CLI forwarding → :4010

# Mapbox origin → :4010

Configure once, never again

Use http://localhost:3000/callback where your OAuth provider allows localhost. For local Stripe webhooks, run stripe listen --forward-to localhost:3000/webhooks.

Switch what’s behind it

gtl proxy 3000 routes to whichever worktree you’re in. The external world sees the same origin. You rotate what’s behind it.

Branch URLs for everything else

Browse at myapp-feature.prt.dev while local integrations use port 3000. Remote webhook services need a public tunnel or a local forwarding tool.

How this works with OAuth, Stripe, and more →

Four pillars, one config file

Everything is driven by .treeline.yml at the root of your repo. Each feature page goes deeper: config options, terminal walkthroughs, and edge cases.

Two branches. Two apps. Zero conflicts.

Not containers — separate ports, databases, and config for every worktree. Declare what each branch needs in .treeline.yml and a git hook installed by gtl install provisions unallocated worktrees and refreshes editor settings when you switch branches in an existing allocation.

How isolation works →

Environment isolation

$ gtl new feature-auth

Allocated port 3010

Cloned database myapp_dev_feature_auth

Wrote .env.local

==> https://myapp-feature-auth.prt.dev

named URL via gtl serve

The URL follows the branch, not the port.

Your app still listens on localhost:{port} but the router gives every branch a named HTTPS URL so you don’t need to remember which port is which. Port 3000 stays free for gtl proxy so OAuth, Stripe, and CORS stay configured to a single origin.

Networking in depth →

Networking

Networking
localhost:3010

Ephemeral port

https://myapp-feature-auth.prt.dev

HTTPS URL for this branch

Type a PR number. Get a running app.

gtl review 42 --start fetches a PR and boots the app in one command. A lightweight process supervisor handles start, stop, and restart — no PID files, no signal guessing.

Review and supervisor →

Workflows

gtl review

$ gtl review 42 --start

✓ Fetched PR #42 (add-oauth-login)
✓ Created worktree, allocated port 3020
✓ Cloned database, ran setup
✓ Server running
→ https://myapp-add-oauth-login.prt.dev

named URL via gtl serve

Agents guess ports and config. They don't have to.

A built-in MCP server — the protocol AI coding agents use to call tools — lets agents query real port allocations, control the dev server, and inspect config. Works with any MCP-compatible editor.

Agent integration →

AI Agents

MCP config
{
  "mcpServers": {
    "gtl": {
      "command": "gtl",
      "args": ["mcp"]
    }
  }
}
No runtime dependency CLI-driven, nothing running in your app.
No lock-in A config file, not a library. Remove it and nothing breaks.
Zero bundle impact Nothing ships to production. Dev tooling only.
Opt-in per developer Works when installed, invisible when it isn’t.

See everything running

Two ways to view your worktrees: a macOS menu bar app for quick access, or a full-screen terminal dashboard for keyboard-driven control.

Solving real problems

Detailed walkthroughs for the scenarios that break multi-branch development.

All scenarios →

Every branch, fully provisioned

brew install git-treeline/tap/git-treeline

Also go install or a release binary.