Запустите Claude в worktree
Передайте--worktree или -w, чтобы создать изолированный worktree и запустить Claude в нём. По умолчанию worktree создаётся в .claude/worktrees/<value>/ в корне вашего репозитория на новой ветке с именем worktree-<value>:
WorktreeCreate. Запустите команду снова с другим именем в другом терминале, чтобы запустить второй изолированный сеанс:
bright-running-fox:
EnterWorktree. После входа в worktree Claude может переключиться непосредственно на другой worktree в .claude/worktrees/, вызвав EnterWorktree с целевым путём. Предыдущий worktree остаётся на диске нетронутым.
Вход в путь вне каталога .claude/worktrees/ репозитория требует вашего одобрения в первую очередь, потому что это перемещает рабочий каталог сеанса, доступ на запись и конфигурацию проекта, такую как CLAUDE.md и settings, в это место. Правило разрешения EnterWorktree permission rule или выбор “не спрашивать снова” не подавляет это приглашение; только режим bypassPermissions пропускает его. До версии 2.1.206 Claude мог войти в любой существующий путь worktree без запроса.
Начиная с версии 2.1.198, вход или выход из worktree также перемещает стенограмму сеанса в хранилище проекта этого каталога, так же как это делает /cd, поэтому /desktop и --resume находят сеанс там после этого. Worktrees, созданные hook WorktreeCreate, исключены и сохраняют стенограмму в каталоге запуска.
Worktrees работают с включённым sandboxing: песочница позволяет записывать в общий каталог .git основного репозитория, поэтому команды, такие как git commit, могут обновлять refs и индекс изнутри связанного worktree.
Перед использованием --worktree интерактивно в каталоге в первый раз примите диалог доверия рабочей области, запустив claude один раз в этом каталоге. Если доверие ещё не было принято, --worktree завершится с ошибкой и предложит вам сначала запустить claude в каталоге. Неинтерактивные запуски с -p пропускают проверку доверия, поэтому claude -p --worktree продолжает работу без неё.
Если Claude Code не может войти в каталог worktree при запуске, например потому что hook WorktreeCreate вывел что-то другое, чем каталог, который он создал, или потому что каталог был удалён после его настройки, Claude Code выводит ошибку с указанием пути и завершается с кодом 1. До версии 2.1.205 это приводило к сбою сеанса, а с -p это зависало примерно на 30 секунд перед выходом с кодом 0.
Плагины, установленные в области проекта из основной копии, также загружаются в worktrees того же репозитория, поэтому вам не нужно переустанавливать их для каждого worktree. Это применяется независимо от того, создаёте ли вы worktree с помощью --worktree или с помощью git worktree add. Требуется Claude Code версии 2.1.200 или позже.
Выберите базовую ветку
Worktrees ветвятся от ветки репозитория по умолчанию,origin/HEAD, поэтому они начинаются с чистого дерева, соответствующего удалённому серверу. Когда ничего не загружало репозиторий в течение последних 24 часов, Claude Code обновляет origin/HEAD с помощью загрузки ветки по умолчанию, ограниченной пятью секундами, и использует локально кэшированный ref, если загрузка не удалась. Если удалённый сервер не настроен или origin/HEAD не кэширован локально и не может быть загружен, worktree переходит на вашу текущую локальную HEAD.
Обновление требует Claude Code версии 2.1.208 или позже; до этого новый worktree использовал то, что уже было кэшировано локально в origin/HEAD.
Чтобы всегда ветвиться от локальной HEAD, установите worktree.baseRef на "head" в settings. Установка baseRef на "head" делает новые worktrees содержащими ваши неотправленные коммиты и состояние ветки функции, что полезно при изоляции subagents, которым нужно работать с незавершённой работой. Когда сеанс работает внутри связанного worktree, "head" разрешается в HEAD этого worktree, а не в основной копии. Параметр принимает только "fresh" или "head", а не произвольные git refs:
# или полный URL GitHub pull request. Claude Code загружает pull/<number>/head из origin и создаёт worktree в .claude/worktrees/pr-<number>:
WorktreeCreate, который полностью заменяет логику git worktree по умолчанию.
Повторное использование имени worktree
Повторное использование имени worktree, каталог которого уже существует, возобновляет этот worktree. Возобновленный worktree переходит к текущей базе вместо возобновления на его старой вершине, когда выполняются все следующие условия:- Он не имеет незафиксированных изменений или неотслеживаемых файлов.
- Он всё ещё находится на ветке, которую создал Claude Code.
- Он никогда не коммитил, или его pull request был объединён и его удалённая ветка удалена.
Скопируйте игнорируемые git файлы в worktrees
Worktree — это свежая копия, поэтому неотслеживаемые файлы, такие как.env или .env.local из вашего основного репозитория, отсутствуют. Чтобы скопировать их автоматически при создании Claude worktree, добавьте файл .worktreeinclude в корень вашего проекта.
Файл использует синтаксис .gitignore. Копируются только файлы, которые соответствуют шаблону и также игнорируются git, поэтому отслеживаемые файлы никогда не дублируются.
Этот .worktreeinclude копирует два файла env и конфиг секретов в каждый новый worktree:
.worktreeinclude
--worktree, worktrees subagent и параллельным сеансам в десктопном приложении.
Изолируйте subagents с помощью worktrees
Subagents могут работать в собственных worktrees, чтобы параллельные правки не конфликтовали. Попросите Claude “использовать worktrees для ваших агентов” или установите это постоянно на пользовательском subagent, добавивisolation: worktree в frontmatter. Каждый subagent получает временный worktree, который автоматически удаляется, когда subagent завершает работу без изменений.
Worktrees subagents используют ту же базовую ветку, что и --worktree, поэтому они ветвятся от ветки по умолчанию вашего репозитория, если только worktree.baseRef не установлен на "head".
Очистка worktrees
Когда вы выходите из сеанса worktree, очистка зависит от того, внесли ли вы изменения:- Нет неотправленных изменений, нет неотслеживаемых файлов и нет новых коммитов: worktree и его ветка удаляются автоматически. Если сеанс имеет имя, Claude вместо этого предлагает вам сохранить worktree на потом
- Существуют неотправленные изменения, неотслеживаемые файлы или новые коммиты: Claude предлагает вам сохранить или удалить worktree. Сохранение сохраняет каталог и ветку, чтобы вы могли вернуться позже. Удаление удаляет каталог worktree и его ветку, отбрасывая все неотправленные изменения, неотслеживаемые файлы и коммиты
- Неинтерактивные запуски: worktrees, созданные с помощью
--worktreeвместе с-p, не очищаются автоматически, так как нет подсказки выхода. Удалите их с помощьюgit worktree remove
cleanupPeriodDays, при условии, что они не имеют неотправленных изменений, неотслеживаемых файлов и неотправленных коммитов. Worktrees, которые вы создаёте с помощью --worktree, никогда не удаляются этой очисткой.
Пока агент работает, Claude запускает git worktree lock на его worktree, чтобы одновременная очистка не могла его удалить. Блокировка снимается, когда агент завершает работу. Чтобы очистить worktree, который очистка сохраняет, запустите git worktree remove, добавив --force, если worktree содержит неотправленные изменения или неотслеживаемые файлы.
В Windows перед удалением worktree Claude Code удаляет любое соединение NTFS или символическую ссылку на каталог на любой глубине внутри него как запись ссылки, чтобы удаление worktree не удаляло файлы, на которые указывает ссылка. До версии 2.1.205 Claude Code удалял только ссылки верхнего уровня как записи ссылок, и удаление worktree с соединением, вложенным в подкаталог, могло удалить содержимое каталога, на который указывала ссылка вне worktree.
Управляйте worktrees вручную
Для полного контроля над расположением worktree и конфигурацией ветки создавайте worktrees непосредственно с помощью Git. Это полезно, когда вам нужно проверить конкретную существующую ветку или поместить worktree вне репозитория. Создайте worktree на новой ветке:Не-git системы контроля версий
Изоляция worktrees использует git по умолчанию. Для SVN, Perforce, Mercurial или других систем настройте hooksWorktreeCreate и WorktreeRemove, чтобы предоставить пользовательскую логику создания и очистки. Поскольку hook заменяет поведение git по умолчанию, .worktreeinclude не обрабатывается при использовании --worktree. Скопируйте любые локальные файлы конфигурации внутри вашего скрипта hook вместо этого.
Этот hook WorktreeCreate читает имя worktree из stdin, проверяет свежую рабочую копию SVN и выводит путь каталога, чтобы Claude Code мог использовать его как рабочий каталог сеанса:
WorktreeRemove для очистки при завершении сеанса. Схему входных данных и пример удаления см. в справочнике hooks.
См. также
Worktrees обрабатывают изоляцию файлов. Связанные страницы ниже охватывают делегирование работы в эти изолированные копии и переключение между созданными вами сеансами:- Subagents: делегируйте работу изолированным агентам внутри сеанса
- Agent teams: координируйте несколько сеансов Claude автоматически
- Manage sessions: назовите, возобновите и переключайтесь между беседами
- Desktop parallel sessions: сеансы на основе worktree в десктопном приложении