Skip to content

devlanes is in beta and not ready for production use.Report an issue

lanes in devlanes.yaml

A top-level key of devlanes.yaml.

Type: mapping.

Which worktrees get a lane, how many ports each lane reserves, and values computed per lane (lane.<name>).

devlanes.yaml
lanes:
hosts_file: always
primary: main
vars:
db_name: acme_${{ lane.name }}

Type: integer or an expression.

Number of ports reserved for each lane. By default devlanes counts the ports the config needs and adds half again, rounded up to ten. A fixed size smaller than what the config needs is an error.

devlanes.yaml
lanes:
block_size: 80

Type: string.

Whether this project’s hostnames are also written to /etc/hosts, for programs that cannot resolve *.localhost by themselves (Wrangler’s workerd, musl or pure-Go binaries). Overrides the user’s hostnames.hosts_file (default auto), except that a user never always wins. Writing needs the helper devlanes setup installs, and only exact names are written, never wildcards.

Values:

  • auto: Write the exact hostnames only when the daemon’s startup check finds that the system resolver does not answer *.localhost with a loopback address.
  • never: Never write hostnames to /etc/hosts. Set in the user config, it applies to every project whatever the project sets.
  • always: Always write the exact hostnames, even when the system resolver handles *.localhost, for programs that send *.localhost to DNS themselves.
devlanes.yaml
lanes:
hosts_file: auto

Type: list of mappings of names to strings, booleans, numbers or expressions.

Fixed values per lane instead of computed vars: entry N holds lane N’s values, read as lane.<name>. A lane whose index has no entry fails to resolve. Cannot be combined with vars.

devlanes.yaml
lanes:
matrix:
- domain: acme.localhost
port: 20000
- domain: acme1.localhost
port: 20100

Type: integer or an expression.

Most lanes the project may hold at once; further worktrees stay unassigned, without ports. Lowering it keeps existing lanes. Unset, the number of lanes is limited only by free port blocks.

devlanes.yaml
lanes:
max: 6

Type: string.

What devlanes does when a worktree gets its lane: only reserve it, also set it up, or also start it. Defaults to register. A worktree gets a lane the first time start, status or another command that acts on lanes runs in it, not merely because it exists.

Values:

  • register: Only reserve the lane (its index, port block and domain); nothing runs until the lane is started.
  • setup: Also run infrastructure setup and lane.create tasks, leaving services stopped.
  • start: Also start the lane with the default profile.
devlanes.yaml
lanes:
new_worktrees: register

Type: string.

Branch whose worktree is lane 0, the main lane (lanes.main in expressions) and the only worktree that gets a lane by itself. Defaults to the remote’s default branch, else main or master. In CI (a variable such as CI or GITHUB_ACTIONS is set) the checkout takes lane 0 on any branch when lane 0 is free.

devlanes.yaml
lanes:
primary: main

Type: string.

What happens to a lane whose worktree folder is deleted, for example by git worktree remove after a merge. Defaults to stop, which stops its processes and keeps its data, containers and ports until devlanes lane gc --yes or devlanes lane clean removes them. Set clean to have devlanes clean the lane by itself.

Values:

  • stop: Stop the lane’s processes and keep the lane: its data folder, containers, index and ports stay until devlanes lane gc --yes or devlanes lane clean removes them.
  • clean: Clean the lane by itself: stop its processes, remove its own containers and data folder, and free its index and ports. An idle lane is cleaned once its folder has been gone for 5 seconds, so git worktree move keeps it. Its logs stay until log retention removes them. lane.clean tasks and infra.teardown need the folder to run in, so they are skipped; data they would drop from shared containers stays.
devlanes.yaml
lanes:
removed_worktrees: stop

Type: mapping of names to strings, booleans, numbers or expressions.

Values computed for each lane and read as ${{ lane.<name> }}, such as a database name, vhost, bucket or Redis index per lane. Build names from ${{ lane.name }}, which is main in lane 0 and lane<N> in lane N whatever the branch, and numbers from ${{ lane.index }}. A var named domain replaces the default lane domain, and one named port fixes where the lane’s port block starts. ${{ domain('pages') }} gives a name a site of its own in each lane, such as pages2.localhost in lane 2. Cannot be combined with matrix.

devlanes.yaml
lanes:
vars:
db_name: acme_${{ lane.name }}