Worktrees

Git worktree — это вторая рабочая копия репозитория, на другой ветке, в другой папке. Joppa превращает его в окружение: то же приложение, но со своими доменами, своими портами, своим .env и, если хотите, своей базой данных. main остаётся доступным, пока ветка (или агент вроде Claude Code) работает рядом, без конфликтов портов и данных.

Вкладка Worktrees (W) проекта перечисляет его worktree. Она появляется у проектов, папка которых — git-репозиторий.

Что получает worktree

Домены

Имя ветки становится меткой домена: feature/Login UI даёт feature-login-ui (отсоединённый worktree получает имя своей папки).

Домен проекта	Домен worktree
myproject.test	feature-login-ui.myproject.test
app.myproject.test	app.feature-login-ui.myproject.test

Если это имя уже занято (ветка api, а у проекта есть api.myproject.test), Joppa добавляет номер: api-2. Сертификаты покрывают эти домены без каких-либо действий с вашей стороны. Переносятся только домены, которые указывают на сервер разработки проекта.

Порты

Каждый сервер разработки получает собственный порт: порт проекта + 100, + 200… (5173 → 5273), иначе свободный порт от 41000 до 49999. Никогда не порт, зарезервированный другим проектом (его доменами и процессами, даже остановленными), и не уже занятый порт.

Joppa передаёт его так, как понимает сервер:

1. через переменную, которую Joppa уже задаёт (${PORT:-3000} в скрипте, SERVER_PORT для php artisan serve, REVERB_SERVER_PORT для Reverb);
2. через переменную, которую читает сервер (API_PORT в его коде, PORT в его .env);
3. переписывая порт, записанный в скрипте (vite --port 5173);
4. через --port для Vite, Astro, Next.js, Nuxt, Angular, Wrangler, Storybook, Vue CLI, Docusaurus, Gatsby, VitePress и Expo (плюс PORT); через PORT для Create React App.

Сервер, порт которого задан только в коде, без переменной, перенести нельзя: Joppa оставляет его вне «Запустить всё» и сообщает об этом.

Сервер, который читает адрес другого сервера из переменной со значением по умолчанию (process.env.API_URL ?? "http://localhost:47400"), получает новый адрес: фронтенд worktree обращается к API worktree, а не к API проекта.

Сервисы Docker Compose остаются сервисами проекта: worktree пользуется ими, не запуская вторую копию (их порты фиксированы).

Файл .env

Git не копирует файлы, которые он игнорирует. Joppa копирует в worktree те, которых там нет: .env, .env.local, .env.development, .env.development.local, .dev.vars (Wrangler) и .php.ini, а также файлы закрепления версий (.php-version, .node-version, .nvmrc, .tool-versions), если они не закоммичены, — в корне и в папке каждого сервера разработки. В них он заменяет адреса: localhost:5173 → localhost:5273, VITE_PORT=5173 → 5273, https://app.myproject.test → https://app.feature-login-ui.myproject.test.

База данных

Для каждой базы данных, которую проект использует в сервисе Joppa:

Вариант	Что делает Joppa
Копия базы проекта (по умолчанию)	Создаёт myproject_feature_login_ui из базы проекта: TEMPLATE для PostgreSQL (мгновенно), иначе копию через дамп (PostgreSQL, используемый работающим сервером, MySQL, MariaDB)
Пустая база	Создаёт пустую базу; для Laravel — php artisan migrate, если зависимости устанавливаются во время подготовки
База самого проекта	Worktree использует ту же базу, что и проект

.env worktree получает имя его базы. В Reverb у него своё приложение (myproject_feature_login): его каналы не смешиваются с каналами проекта, а журнал событий показывает его под проектом. Redis, Valkey, Mailpit и поисковые движки общие с проектом.

База SQLite (Laravel с DB_CONNECTION=sqlite или DATABASE_URL вида file:, в том числе у Prisma) следует тому же выбору: файл копируется, создаётся пустым (тогда Laravel запускает миграции, если зависимости установлены), или .env worktree указывает на файл проекта. Git игнорирует такие файлы: без этого у worktree не было бы базы.

Процессы

Процессы worktree — это процессы проекта на его портах, включая воркеры Laravel: Reverb получает свой порт через REVERB_SERVER_PORT, и REVERB_PORT в скопированном .env следует за ним. Когда очередь Laravel работает через Redis (Horizon или QUEUE_CONNECTION=redis), процессы php artisan worktree получают собственные REDIS_PREFIX и HORIZON_PREFIX (myproject_database_feature_login_ui_): его воркеры никогда не берут задания проекта. Xdebug следует настройкам проекта. Процессы хранятся в конфигурации Joppa, а не в joppa.toml. Когда вы сохраняете процессы проекта, процессы его worktree обновляются вслед за ними (новый процесс получает свой порт); Обновить из myproject делает это по запросу.

Его серверы разработки засыпают через 15 минут без запросов и просыпаются при следующем: несколько десятков worktree могут оставаться открытыми, не держа каждый свои серверы в памяти.

Подготовить worktree

На вкладке Worktrees нажмите Подготовить у worktree в состоянии «не подготовлен». Выберите его базу данных, затем при необходимости отметьте:

• Установить зависимости: bun install (или менеджер пакетов проекта), если нет node_modules, composer install, если нет vendor;
• Запустить процессы, когда всё будет готово.

Появляется журнал подготовки; Открыть ведёт в окружение.

Создать worktree

Новый worktree выполняет git worktree add, а затем готовит окружение:

• Новая ветка — от текущего коммита или от другой ветки, или Существующая ветка;
• папка создаётся рядом с репозиторием: myproject-worktrees/<ветка>.

Worktree, созданные в другом месте

С включённым Подготавливать новые worktree автоматически (включено по умолчанию) Joppa каждые 3 секунды проверяет worktree проекта и готовит те, что только что создали git, Claude Code, Conductor или другой агент: домены, порты, .env и базу данных — согласно выбору База данных нового worktree. Ничего не устанавливается и не запускается: обычно этим занимается инструмент, который создал worktree. Уведомление сообщает, что окружение готово, с кнопкой Открыть. Обе настройки можно разделить с командой в разделе [worktrees] файла joppa.toml.

Автоматически готовятся только worktree, созданные после включения: уже существовавшие ждут Подготовить.

Окружение worktree

Оно появляется в боковой панели под своим проектом, с пометкой ⎇ и именем по ветке. Его страница такая же, как у проекта (домены, процессы, .env, среда выполнения, аналитика), а вверху — напоминание о ветке и:

• Открыть myproject;
• Обновить из myproject;
• Удалить…: его домены исчезают, а процессы останавливаются. При необходимости отметьте Удалить его базы данных (созданные для него) и Удалить папку worktree (git worktree remove; отклоняется, если есть незакоммиченные изменения, кроме случая с отметкой Даже с незакоммиченными изменениями).

Если вы оставите папку, Joppa больше не будет готовить её сам («пропущен»); Подготовить возвращает её.