Что такое git worktree?

Коротко

Git worktree — это дополнительная рабочая папка, подключённая к тому же git-репозиторию. В каждой папке открыта своя ветка, поэтому можно работать над двумя вещами одновременно, не клонируя репозиторий заново, и не давать параллельным кодинг-агентам мешать друг другу.

Как это работает

Обычно в папке репозитория открыта одна ветка, и чтобы переключиться, сначала нужно закоммитить изменения или убрать их в stash. С worktree основная папка остаётся как есть, а рядом появляется новая папка с другой веткой. Папки делят историю коммитов и базу объектов, но у каждой свои HEAD, индекс и рабочие файлы.

Основные команды

Для повседневной работы хватает нескольких команд.

git worktree add ../feature-a -b feature-a: создаёт новую ветку и папку.
git worktree list: показывает открытые worktree.
git worktree remove ../feature-a: удаляет папку.
git worktree prune: очищает записи о папках, удалённых вручную.

Почему это важно для кодинг-агентов

Два агента в одной папке могут затереть файлы друг друга, а запуск тестов одним агентом может споткнуться о недоделанное изменение другого. Отдельный worktree для каждого агента избавляет от этого: каждый работает в своей ветке, а результаты вы объединяете pull request или слиянием. Ветки, затрагивающие один и тот же файл, при слиянии всё равно могут конфликтовать.

На что обратить внимание

Worktree лёгкие, но несколько деталей ловят людей врасплох.

Одну и ту же ветку нельзя открыть в двух worktree одновременно.
Неотслеживаемые файлы, такие как node_modules, .env и результаты сборки, не копируются; зависимости, возможно, придётся установить заново.
Если в каждом worktree запущен свой dev-сервер, следите за конфликтами портов.
Удаляйте ненужные worktree, иначе забытые папки копятся на диске.

Worktree в AgentVera

AgentVera использует worktree как основу параллельного запуска агентов.

На панели worktree в разделе Git откройте ветку и папку под каждую функцию и запустите агента прямо в этой папке.
В ночной смене каждая задача выполняется в собственном worktree на ветке night/<date>-<slug>; агент коммитит, но никогда не делает push (Pro и Team).
Окружения предпросмотра запускают dev-сервер проекта и каждого worktree по своему адресу, названному по ветке.
Координация агентов предупреждает, когда агенты в разных worktree меняют один и тот же файл, так как слияние может конфликтовать.

FAQ

Чем worktree отличается от ветки?

Ветка — это именованная линия коммитов; worktree — папка, в которой открыта ветка. С одними ветками вы переключаетесь внутри одной папки; с worktree несколько веток одновременно открыты в отдельных папках.

Чем worktree отличается от двойного клонирования репозитория?

Worktree делят один репозиторий: коммиты, ветки и конфигурация общие, а места на диске уходит меньше. Коммит из одного worktree сразу виден из других, тогда как отдельным клонам нужны push и fetch.

Как удалить worktree?

Выполните git worktree remove <папка>. Если вы удалили папку вручную, запись очистит git worktree prune. Ветка останется; при необходимости удалите её отдельно через git branch -d.

Общие ли у worktree node_modules?

Нет. Неотслеживаемые файлы в каждой папке свои, поэтому зависимости устанавливаются в каждом worktree.