Skip to content

Use cases

New developer, one command

A new teammate clones the repo. The README says “run these 14 steps.” Half are macOS-specific, two reference a database dump that doesn’t exist yet, and the env example file is three months stale. With Treeline in the repo, the README says gtl new feature-onboarding --start.

The scenario

Typical onboarding for a Rails or Next.js project involves: install dependencies, create a database, load the schema, seed data, copy and edit an env file, find an available port, wire up Redis, and start the server. Each step can fail for reasons unique to the developer’s machine. The .treeline.yml committed to the repo encodes all of this in a declarative config that gtl new executes in order.

The developer doesn’t need to understand worktrees to benefit. Their first environment is a worktree — it just happens to be the one they work in.

Step 1: The project maintainer sets up once

Run gtl install in the project root. It detects the framework, generates a .treeline.yml, creates user config, installs the post-checkout hook, allocates ports, writes env, and optionally sets up HTTPS routing. Commit the config.

one-time setup by maintainer

$ gtl install

Detected Rails project

Wrote .treeline.yml

Created user config: config.json

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

Allocated port 3002

Wrote .env.local

Ready. Run gtl start to start your server.

The resulting config declares everything the project needs:

.treeline.yml
project: myapp
port_count: 2

env_file: .env.local

database:
  adapter: postgresql
  template: myapp_development
  pattern: "{template}_{worktree}"

copy_files:
  - config/master.key

env:
  PORT: "{port}"
  DATABASE_NAME: "{database}"
  REDIS_URL: "{redis_url}"
  ESBUILD_PORT: "{port_2}"
  APPLICATION_HOST: "localhost:{port}"

commands:
  setup:
    - bundle install --quiet
    - yarn install --silent
  start: bin/dev

Step 2: A new developer joins

First install the project runtimes and database service, prepare the template database, and obtain required secrets such as config/master.key. A configured gtl provision can prepare host prerequisites. Then clone the repo and run gtl install once before creating a worktree. The named HTTPS URL below requires the optional router.

new developer

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

$ git clone git@github.com:acme/myapp.git

$ cd myapp

$ gtl install

$ gtl new feature-onboarding --start

Creating worktree feature-onboarding

Allocated ports 3004, 3005

Cloned database myapp_development_feature_onboarding

Wrote .env.local

Copied config/master.key

Running setup: bundle install --quiet

Running setup: yarn install --silent

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

Starting: bin/dev (port 3004)

Everything in the config happened in order: port allocation, database clone, env file generation, file copies, setup commands, and server boot. The developer is looking at a running app.

What gtl new actually does

One command, multiple steps — all derived from .treeline.yml:

Step What happens Config source
1 Create git worktree git worktree add
2 Allocate port block port_count + user config range
3 Clone database (if configured) database.template
4 Assign Redis namespace (if configured) User config redis.strategy
5 Write env file with interpolated tokens env_file + env
6 Copy files from main repo copy_files
7 Run setup commands commands.setup
8 Boot the server (if --start) commands.start

The post-checkout hook

gtl install sets up a post-checkout git hook. It provisions unallocated linked worktrees after git worktree add and refreshes editor settings on branch changes in already allocated worktrees. New worktrees get their own port, database, and env file without the developer running gtl setup manually.

The hook reuses existing allocations. Treeline defers hook-driven setup during gtl new and gtl review so setup runs once, after creation.

Framework examples

gtl install auto-detects your framework and generates a tailored config. Here are common starting points:

Next.js

.treeline.yml
project: myapp
env_file: .env.local

env:
  PORT: "{port}"
  NEXT_PUBLIC_APP_URL: "http://localhost:{port}"

commands:
  setup:
    - npm install
  start: npm run dev

Next.js loads .env.local but doesn’t use PORT for its listen port. Update your dev script: "dev": "next dev --port ${PORT:-3000}". gtl install prints this guidance automatically.

Vite (React, Vue, Svelte)

.treeline.yml
project: website
env_file: .env.local

env:
  PORT: "{port}"

commands:
  setup:
    - npm install
  start: npx vite --port {port}

Vite ignores the PORT env var, so the start command passes {port} directly. gtl install detects Vite and generates this automatically.

Express / Node

.treeline.yml
project: myapi
env_file: .env

env:
  PORT: "{port}"

commands:
  setup:
    - npm install
  start: node server.js

Lifecycle hooks for validation

Use hooks.pre_setup to validate prerequisites for your setup commands. This hook runs after resource allocation, env writing, and attempted database cloning; it does not guard the initial clone:

.treeline.yml (partial)
hooks:
  pre_setup:
    - psql -lqt | grep -q myapp_development || { echo "Template DB missing"; exit 1; }
  post_setup:
    - echo "Setup complete. Run gtl start to boot."

pre_setup aborts on failure. post_setup warns but continues. Both run at setup time — before the server boots.

Verifying the setup

$ gtl doctor

Config:

  ✓ .treeline.yml found

  ✓ User config loaded

Allocation:

  ✓ Ports 3004-3005 allocated

  ✓ Database myapp_development_feature_onboarding exists

Runtime:

  ✓ Server listening on :3004

  ✓ .env.local matches allocation

gtl doctor checks config, allocation, and runtime state. If something is wrong, it tells the developer exactly what to fix. Add --json for structured output that AI agents and CI can parse.

Read next

All use cases