Skip to main content
Version: Next

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​

By default, Wasp apps use port 3000, and each managed PostgreSQL database uses port 5432. These ports prevent multiple worktrees from running at the same time.

note

We are working on automatic port selection for Wasp apps and dev databases.

We can work around this by giving each app a different port.

Configuring ports​

Configure the app's port in vite.config.ts. In development, your app serves its pages and its API on that single port.

Wasp still assumes the default port when it fills in your app's URLs, so we need to adjust them as well. For example, if we set the port to 4000:

.env.server
WASP_SERVER_URL=http://localhost:4000
WASP_WEB_CLIENT_URL=http://localhost:4000

Wasp's dev PostgreSQL database requires port 5432. To run apps in parallel worktrees, we need to manually provision a separate database for each worktree and set its DATABASE_URL in .env.server.

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.