Worktree lifecycle

Overview

A worktree typically moves through create, setup, start, your day-to-day work, then release (teardown). Each step can be explicit (gtl setup then gtl start) or combined (gtl new runs setup for you; gtl new --start also boots the dev server).

Understanding this pipeline helps when something fails mid-setup, when you need to re-run provisioning after a config change, or when you want to know what gtl release actually tears down.

gtl new

Creates a new git worktree and runs full setup against it. You must run gtl new from the main repository checkout (not from inside another worktree), because Treeline uses the main repo as the source for allocation and shared files.

Under the hood it combines git worktree add with the same provisioning path as gtl setup: allocate resources, copy files, write env, clone the database, run setup commands and hooks.

Pass --start to launch the supervised dev server immediately after setup finishes.

# From the main repo
gtl new feature/payments
gtl new feature/payments --start

gtl setup

Idempotent provisioning for the current worktree. Safe to run again after config edits that affect ports, env, or install steps.

Execution order:

1. Allocate ports, database name, and Redis namespace (or reuse existing allocation).
2. copy_files from the main repo into the worktree.
3. Write the env file with interpolated values (ports, DB name, tokens like {port}, {database}, resolve placeholders, etc.).
4. Clone the database from the template (skipped when allocations are reused and the DB already exists).
5. pre_setup hooks.
6. commands.setup.
7. Configure the editor (title, color) for this worktree.
8. post_setup hooks.

If setup fails after a new allocation was created, Treeline releases the registry entry so ports and names do not leak.

gtl start

Launches the supervised dev server for this worktree. Before starting the child process, Treeline syncs the env file and refreshes editor metadata so what you see matches .treeline.yml.

Start hooks run according to your config: hooks marked auto, plus any hook names you pass with --with.

Fresh start means no supervisor is running yet: Treeline reads commands.start, syncs env, then boots the server. Resume means a supervisor is already listening: gtl start may only signal the existing process instead of re-reading config (see When config changes take effect).

gtl restart / gtl stop

gtl restart bounces the dev server: it syncs env (and updates the supervisor environment), then restarts the child. Use this after env or hook changes when you do not need a full new supervisor.

gtl stop stops the server process but leaves the supervisor alive. The next gtl start may resume with the previously loaded start command rather than re-provisioning from disk.

gtl stop --kill shuts down the supervisor entirely, equivalent to Ctrl+C in the terminal. Use this from agents or scripts that need to fully terminate the supervisor process remotely.

gtl switch

Fetches from origin, checks out a branch in the current worktree, updates the registry entry for this path, and refreshes env so allocations match the branch.

You can pass a pull request number instead of a branch name when your hosting integration supports it.

Pass --setup to re-run gtl setup after the checkout (for example when dependencies or migrations changed on the target branch).

gtl release

Teardown for this worktree. Runs pre_release hooks, then frees the port, database, and Redis allocation in the registry, then runs post_release hooks.

• --drop-db drops the database.
• --remove-worktree also removes the git worktree directory.
• --force skips confirmation prompts.

gtl prune

Bulk cleanup of stale worktrees. Treeline uses merge_target from .treeline.yml to decide which remote branches count as merged, so it can offer to remove worktrees whose branches are already integrated.

When config changes take effect

Each worktree has its own .treeline.yml (the file checked out on that branch). Commands read the worktree you are in, not the main repo. The table below summarizes which fields apply on fresh start, restart, and manual commands. Adapted from the Treeline CONFIG_LIFECYCLE reference.

Key insight: changing commands.start requires stopping the supervisor process entirely (for example Ctrl+C in the terminal where it runs) and running gtl start again. gtl stop stops the child only; gtl restart syncs env but does not replace an in-memory start command and will warn if it detects a mismatch.

gtl env sync refreshes the env file and editor settings without starting the server. gtl restart applies env changes to a running supervisor. gtl setup is the path for copy_files, commands.setup, port re-allocation, and database clone steps.

See also

• Hooks guide: setup, release, and start hooks.
• Configuration reference: every .treeline.yml field.