Use cases

Frontend and API live in different checkouts

Your SPA and your API are separate git repos. Each gets its own Git Treeline project name and its own port allocation. The hard part is wiring: the browser needs a base URL for XHR, and that URL must track whichever API branch matches the work you are doing—not a stale port someone typed last week.

What breaks without a registry

Developers paste http://localhost:3030 into .env.local. Someone re-runs setup, the API moves to 3040, and every frontend worktree is wrong until someone notices. Branch names drift too: your UI is on feature-auth but the API team left their experiment on staging. Nothing in plain git fixes that—only a layer that knows both allocations.

What Git Treeline does

Git Treeline keeps a machine-local registry of allocations (ports, databases, worktree paths). From any worktree, gtl resolve <project> returns the base URL for another project’s current allocation—by default matching the same branch name as the worktree you run the command from. If you need the UI to follow a different API branch for a while, gtl link api staging stores an override in the registry, regenerates the env file, and restarts the supervised server automatically. gtl unlink api drops the override (same auto-refresh). Overrides show up in gtl status and gtl doctor.

In .treeline.yml, use API_URL: "{resolve:api}" (or {resolve:api/main} to pin a branch). Values are resolved at setup time. If the target project is not allocated, setup fails with a clear error—no silent localhost guess.

from the web repo worktree

$ gtl resolve api

http://127.0.0.1:3030

# Scripting / agents:

$ gtl resolve api --json

# Override when branch names do not match:

$ gtl link api staging

URLs vs localhost

For browser calls, you often want a named HTTPS URL per branch (via gtl serve) instead of a raw port. The frontend’s env can point at https://api-feature-auth.prt.dev while {resolve:api} fills in the right origin for server-side or tooling. See the networking page for how serve, proxy, tunnel, and share differ.

Where to read more

All use cases