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>).
lanes: hosts_file: always primary: main vars: db_name: acme_${{ lane.name }}lanesWhich worktrees get a lane, how many ports each lane reserves, and values computed per lane (lane.<name>).
lanes.hosts_fileWhether 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.
lanes.primaryBranch 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.
lanes.varsValues 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.
lanes.vars.<name>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.
lanes.block_size
Section titled “lanes.block_size”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.
lanes: block_size: 80lanesWhich worktrees get a lane, how many ports each lane reserves, and values computed per lane (lane.<name>).
lanes.block_sizeNumber 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.
Config referencelanes.hosts_file
Section titled “lanes.hosts_file”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*.localhostwith 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*.localhostto DNS themselves.
lanes: hosts_file: autolanesWhich worktrees get a lane, how many ports each lane reserves, and values computed per lane (lane.<name>).
lanes.hosts_fileWhether 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.
lanes.matrix
Section titled “lanes.matrix”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.
lanes: matrix: - domain: acme.localhost port: 20000 - domain: acme1.localhost port: 20100lanesWhich worktrees get a lane, how many ports each lane reserves, and values computed per lane (lane.<name>).
lanes.matrixFixed 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.
lanes.matrix[].<name>A plain value or text with ${{ ... }} expressions, evaluated for each lane with names such as lane, self, services, infra and env. A value that is one whole expression keeps its type, which must fit the setting. Write ${{ '${{' }} for a literal ${{.
lanes.max
Section titled “lanes.max”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.
lanes: max: 6lanesWhich worktrees get a lane, how many ports each lane reserves, and values computed per lane (lane.<name>).
lanes.maxMost 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.
Config referencelanes.new_worktrees
Section titled “lanes.new_worktrees”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 andlane.createtasks, leaving services stopped.start: Also start the lane with the default profile.
lanes: new_worktrees: registerlanesWhich worktrees get a lane, how many ports each lane reserves, and values computed per lane (lane.<name>).
lanes.new_worktreesWhat 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.
lanes.primary
Section titled “lanes.primary”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.
lanes: primary: mainlanesWhich worktrees get a lane, how many ports each lane reserves, and values computed per lane (lane.<name>).
lanes.primaryBranch 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.
lanes.removed_worktrees
Section titled “lanes.removed_worktrees”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 untildevlanes lane gc --yesordevlanes lane cleanremoves 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, sogit worktree movekeeps it. Its logs stay until log retention removes them.lane.cleantasks andinfra.teardownneed the folder to run in, so they are skipped; data they would drop from shared containers stays.
lanes: removed_worktrees: stoplanesWhich worktrees get a lane, how many ports each lane reserves, and values computed per lane (lane.<name>).
lanes.removed_worktreesWhat 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.
lanes.vars
Section titled “lanes.vars”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.
lanes: vars: db_name: acme_${{ lane.name }}lanesWhich worktrees get a lane, how many ports each lane reserves, and values computed per lane (lane.<name>).
lanes.varsValues 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.
lanes.vars.<name>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.