Перейти к содержанию

Git worktrees: рабочий каталог сессии

Worktree — вторичная рабочая копия репозитория. Она позволяет вести несколько задач в одном проекте одновременно: у каждой сессии свой каталог и своя ветка, а история, хуки и stash остаются общими.

Зачем это нужно

Обычная сессия работает в каталоге проекта. Если привязать к ней worktree, файловые, shell- и git-инструменты переключатся на отдельный каталог с отдельной веткой — и не будут мешать остальным сессиям.

  • Две задачи параллельно: пока одна собирает и тестирует ветку, вторая правит основную копию.
  • Проверка чужой ветки без переключения основной копии и без «заначки» правок.
  • Чистое сравнение поведения: одинаковый репозиторий, но разное содержимое.

Раздел «Worktree'ы»

Вкладка «Проект» → раздел «Worktree'ы» с описанием «Вторичные рабочие копии репозитория — сессия может работать в своём каталоге».

  • «Создать» открывает диалог «Новый worktree».
  • В строке — ветка, имя каталога и бейджи «изменения», «привязан», «нет каталога», «Ветка: …», «Сессия: …».
  • Действия — «Привязать» / «Отвязать» / «Удалить».
  • «Очистить» убирает записи, у которых каталог уже исчез, и выполняет git worktree prune (рабочие копии с каталогом не трогает).

Создание

В диалоге «Новый worktree» два поля:

  • «Ветка» — например, feature/my-branch.
  • «Имя каталога» — например, my-branch.

Подсказка гласит: «Оставьте поля пустыми — ветку и имя каталога подберёт сервер». Каталог создаётся в скрытом .worktrees, имя нормализуется; при совпадении добавляется суффикс -2, -3 и так далее.

Создание не привязывает сессию: worktree появляется в списке, а привязка — отдельный шаг. Так копию можно подготовить заранее и привязать к другой сессии.

Рабочий каталог сессии

Вкладка «Сессия» → блок «Рабочий каталог»:

  • «Каталог проекта» — обычный рабочий каталог проекта.
  • «Worktree: {имя}» — каталог выбранного worktree; подсказка «Каталог worktree используется как рабочий каталог сессии».
  • В шапке — бейдж «worktree: {имя} · {ветка}»; клик открывает инвентарь проекта.

Саб-агенты наследуют привязку на один уровень. Если каталог worktree исчез (например, его удалили вручную), инструменты вернут явную ошибку: тихого перехода на каталог проекта не будет.

Удаление

  • «Удалить» в строке worktree — подтверждение «Удалить worktree».
  • Если есть незакоммиченные изменения, потребуется второе подтверждение: «Удалить worktree с незакоммиченными изменениями».
  • Worktree, привязанный к живой сессии, удалить нельзя: сначала «Отвязать».
  • При архивации сессии worktree не удаляется автоматически.

Ограничения

  • Общий .git: refs, хуки и stash общие; одну и ту же ветку нельзя взять вторым worktree.
  • Ignored-файлы (.env, локальные настройки) в новую копию не копируются — нужен скрипт подготовки проекта.
  • Режим plan: мутации запрещены, список worktree'ов доступен только на чтение.
  • Дерево файлов: каталог .worktrees скрыт всегда.
  • Безопасность: worktree — не граница изоляции, данные репозитория общие.

Что видят инструменты

  • git_worktree_list — чтение, доступно и в режиме plan.
  • git_worktree_create, git_worktree_remove, git_worktree_prune — изменения; в plan-режиме запрещены.
  • git_worktree_prune убирает записи, каталог которых уже исчез.

Проект берётся только из сессии: подставить другой проект или произвольный путь нельзя.

Что дальше