Git worktree setup

Git worktrees let you work on several isolated instances of the same repository. This is useful when several coding agents work on the app in parallel.

Worktrees

A Git worktree is a separate working directory linked to the same Git repository. Each worktree can check out a different branch while sharing the repository history.

You can create a worktree from main with Git:

git worktree add -b feature/my-feature ../my-app-feature main

Tools such as Herdr, Workmux, and Conductor can create and manage worktrees for you.

Setting up a Wasp worktree

Creating the worktree is only the first step. Each worktree is a fresh copy of the app, so you also need to install its dependencies, configure its environment variables, and prepare its database.

Installing dependencies

After you create a new worktree for your Wasp app, you must first run:

wasp install

It installs the Wasp app dependencies. When creating a new project, wasp new installs them for you, but in a fresh clone or worktree you need to run it manually.

Setting up environment variables

Most apps need environment variables set up before they work. We can set up the server and client environment variables in different ways:

• Copy the example environment files to .env.server and .env.client.

  cp .env.server.example .env.server
  cp .env.client.example .env.client

  Sometimes, this is enough to get the app running if the example files contain dummy values but features like OAuth might not work.

• Copy the environment files from the existing .env.server and .env.client files.

  Reusing these files is convenient, but it also reuses all configured secrets and services. Make sure this does not cause unintended side effects, such as connecting to a production database.

• If you are using a secrets manager like Dotenvx, use its CLI to set up the environment files.

See Environment variables for Wasp's environment file rules.

Preparing the database

SQLite

If you are using SQLite, it doesn't need a separate database process. It's enough to apply the migrations:

wasp db migrate-dev

PostgreSQL

If you are using PostgreSQL, it needs to be running. Start the Wasp dev database in one terminal:

wasp start db

Then apply the migrations from another terminal:

wasp db migrate-dev

Wasp gives each worktree a unique development database name and Docker volume.

Seed data

If your app needs to seed scaffold data, you can apply it with the wasp db seed <name> command.

Start the app

After the setup, the app should start successfully:

wasp start

Running worktrees at the same time

wasp start picks free ports for your app automatically, starting from 3000 for the client and 3001 for the server, so apps from different worktrees can run at the same time. Wasp derives your app's dev URLs from those ports and sets them for you, so overriding them in .env.server or .env.client fails. If you need specific ports, use --client-port and --server-port.

wasp start db does the same for the dev database: it starts on port 5432 or the first free port after it, and wasp start finds the port on its own. Each worktree gets its own database, so you can run them side by side. If you need a specific port, use --db-port.

Extra resources

Using .worktreeinclude file

Some coding tools (e.g., Claude Code, Codex, and Conductor) read a .worktreeinclude file and copy matching ignored files into new worktrees:

.worktreeinclude

.env.server
.env.client

Keep in mind that .worktreeinclude is not a Git feature, and support differs between tools.