Getting started

Git Treeline is a worktree provisioner: a single CLI that declaratively provisions ports, databases, routing, env files, editor config, and lifecycle hooks for every git worktree. Nothing from Treeline runs inside your app's process or bundle. It writes per-worktree env at setup time.

Install the CLI

Homebrew (macOS and Linux):

$ brew install git-treeline/tap/git-treeline

Go install:

$ go install github.com/git-treeline/git-treeline@latest

Or download a binary from the releases page. The binary installs as git-treeline with a short alias gtl. It also works as git treeline.

Set up a project

From the root of any repo:

$ cd ~/myapp

$ gtl install

Detected Rails project

Wrote .treeline.yml

Created user config at ~/.config/git-treeline/config.yml

Post-checkout hook: .git/hooks/post-checkout

Allocated port 3000

Wrote .env.local

Local HTTPS routing lets you access worktrees at https://myapp-main.prt.dev

HTTPS router setup: Yes, install now

Ready. Run gtl start to start your server.

gtl install does everything in one step:

  1. Creates .treeline.yml if missing (auto-detects framework, writes AGENTS.md)
  2. Creates user config if this is your first project
  3. Installs the post-checkout hook for automatic worktree setup
  4. Allocates ports and writes the env file for the current worktree
  5. Offers to enable the local HTTPS router (optional)

Every step is idempotent — safe to re-run any time. If you already have a .treeline.yml, it skips config generation and goes straight to allocation and setup.

The HTTPS router prompt (step 5) requires sudo to trust a local CA certificate and set up port forwarding. You can skip it and use localhost-only workflows — core commands like setup, new, clone, and review work without it. You can always run gtl serve install later. See the Networking guide for the full picture on routing, proxy, tunnel, and share.

Create your first worktree

$ gtl new feature-auth

Creating worktree feature-auth

Allocated port 3010

Cloned database myapp_dev_feature_auth

Wrote .env.local

Running setup commands…

Ready. Start your server in this worktree.

Add --start to boot the app immediately after setup. Every worktree gets its own port, database, env file, and HTTPS URL automatically.

Review a GitHub PR

$ gtl review 42 --start

Fetching PR #42 (Add OAuth login)

Creating worktree myapp-pr-42

Allocated port 3020

Cloned database myapp_dev_pr_42

Starting server on port 3020…

Requires the GitHub CLI (gh). From inside a worktree, review prompts to switch the current worktree to the PR branch.

Switch branches

$ gtl switch feature-payments

Fetching from origin…

Switched to feature-payments

Refreshed .env.local

Fetches from origin, checks out the branch, updates the registry, and refreshes the env file. Accepts PR numbers too: gtl switch 42 resolves the branch via gh. Add --setup to re-run commands.setup after switching.

Check project health

$ gtl doctor

Checks config presence, env file status, port allocation, supervisor state, and framework-specific guidance in one view. Run it when something seems off.