worktree-portless

Deterministic port allocation and portless subdomain isolation for git worktrees.

When working with multiple git worktrees, each instance needs unique ports to avoid conflicts, and unique subdomains to prevent cookie collisions. wtp solves both problems by hashing the worktree name into deterministic port assignments and wrapping commands with portless for subdomain routing.

Install

pnpm install -g worktree-portless

This also installs portless globally if not already present.

Usage

# Command first, flags after
wtp pnpm nx run banana-server:serve --portless --port PORT:5000-5999 WDS_PORT:3000-3999

# With a configuration from config
wtp --config server

# Configuration with command override
wtp pnpm nx run banana-server:serve:e2e --config server

# Simple command
wtp make serve --port PORT:5000-5999

Flags

| Flag | Description | Default | |------|-------------|---------| | --portless | Wrap command with portless for subdomain routing | false | | --portless-port <port> | Portless proxy port | 1355 | | --port <entries...> | Port range env vars: PORT:3000-3999 | — | | --origin <keys...> | Origin env vars: CYPRESS_BASE_URL | — | | --env <entries...> | Static env vars: NODE_ENV:test FOO:bar | — | | --config <name> | Load configuration from config file | — |

Config file

Create worktreeportless.config.js (or .ts, .json, .yaml) in your project root:

export default {
  configurations: {
    server: {
      command: 'pnpm nx run banana-server:serve',
      portless: true,
      computedEnv: [
        { type: 'port', key: 'PORT', min: 5000, max: 5999 },
        { type: 'port', key: 'WDS_PORT', min: 3000, max: 3999 },
      ],
    },
    tests: {
      command: 'pnpm nx run banana-acceptance-tests:e2e',
      computedEnv: [
        { type: 'port', key: 'PORT', min: 5000, max: 5999 },
        { type: 'origin', key: 'CYPRESS_BASE_URL' },
      ],
    },
  },
};

CLI flags override configuration values when both are provided.

How it works

1. Detects the repo name (from git remote get-url origin) and worktree name (from git rev-parse --show-toplevel)
2. Hashes repoName/worktreeName with SHA-256 to deterministically assign ports within configured ranges
3. Optionally wraps the command with portless for subdomain-based routing (http://worktree.localhost:port)
4. Spawns the command with resolved environment variables

License

MIT