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

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

git worktree — это отдельный рабочий каталог с собственными файлами и веткой, использующий ту же историю репозитория и удалённый сервер, что и ваша основная копия. Запуск каждого сеанса Claude Code в собственном worktree означает, что правки в одном сеансе никогда не затрагивают файлы в другом, поэтому вы можете одновременно работать с Claude, который создаёт функцию в одном терминале и исправляет ошибку во втором. На этой странице рассматривается изоляция worktree в CLI. Всё ниже предполагает наличие git-репозитория. Для других систем контроля версий см. Не-git системы контроля версий. Десктопное приложение автоматически создаёт worktree для каждого нового сеанса. Worktrees — один из нескольких способов запуска Claude параллельно. Они изолируют правки файлов, в то время как subagents и agent teams координируют саму работу. См. Запуск агентов параллельно, чтобы сравнить подходы, или перейдите к Изолируйте subagents с помощью worktrees, чтобы использовать worktrees и subagents вместе.

​
Запустите Claude в worktree

Передайте --worktree или -w, чтобы создать изолированный worktree и запустить Claude в нём. По умолчанию worktree создаётся в .claude/worktrees/<value>/ в корне вашего репозитория на новой ветке с именем worktree-<value>: 
claude --worktree feature-auth
Чтобы поместить worktrees в другое место, настройте hook WorktreeCreate. Запустите команду снова с другим именем в другом терминале, чтобы запустить второй изолированный сеанс: 
claude --worktree bugfix-123
Если вы опустите имя, Claude сгенерирует одно, например bright-running-fox: 
claude --worktree
Вы также можете попросить Claude “работать в worktree” во время сеанса, и он создаст один с помощью инструмента EnterWorktree. Перед использованием --worktree в каталоге в первый раз примите диалог доверия рабочей области, запустив claude один раз в этом каталоге. Если доверие ещё не было принято, --worktree завершится с ошибкой и предложит вам сначала запустить claude в каталоге, включая случаи, когда это объединено с -p.
Добавьте .claude/worktrees/ в ваш .gitignore, чтобы содержимое worktree не отображалось как неотслеживаемые файлы в вашей основной копии.

​
Выберите базовую ветку

Worktrees ветвятся от ветки репозитория по умолчанию, origin/HEAD, поэтому они начинаются с чистого дерева, соответствующего удалённому серверу. Если удалённый сервер не настроен или загрузка не удалась, worktree переходит на вашу текущую локальную HEAD. Чтобы всегда ветвиться от локальной HEAD, установите worktree.baseRef на "head" в settings. Установка baseRef на "head" делает новые worktrees содержащими ваши неотправленные коммиты и состояние ветки функции, что полезно при изоляции subagents, которым нужно работать с незавершённой работой. Параметр принимает только "fresh" или "head", а не произвольные git refs: 
{
  "worktree": {
    "baseRef": "head"
  }
}
Чтобы ветвиться от конкретного pull request, передайте номер PR с префиксом # или полный URL GitHub pull request. Claude Code загружает pull/<number>/head из origin и создаёт worktree в .claude/worktrees/pr-<number>: 
claude --worktree "#1234"
Для полного контроля над тем, как создаются worktrees, настройте hook WorktreeCreate, который полностью заменяет логику git worktree по умолчанию.

​
Скопируйте игнорируемые git файлы в worktrees

Worktree — это свежая копия, поэтому неотслеживаемые файлы, такие как .env или .env.local из вашего основного репозитория, отсутствуют. Чтобы скопировать их автоматически при создании Claude worktree, добавьте файл .worktreeinclude в корень вашего проекта. Файл использует синтаксис .gitignore. Копируются только файлы, которые соответствуют шаблону и также игнорируются git, поэтому отслеживаемые файлы никогда не дублируются. Этот .worktreeinclude копирует два файла env и конфиг секретов в каждый новый worktree:
.worktreeinclude
.env
.env.local
config/secrets.json
Это применяется к worktrees, созданным с помощью --worktree, worktrees subagent и параллельным сеансам в десктопном приложении.

​
Изолируйте subagents с помощью worktrees

Subagents могут работать в собственных worktrees, чтобы параллельные правки не конфликтовали. Попросите Claude “использовать worktrees для ваших агентов” или установите это постоянно на пользовательском subagent, добавив isolation: worktree в frontmatter. Каждый subagent получает временный worktree, который автоматически удаляется, когда subagent завершает работу без изменений.

​
Очистите worktrees

Когда вы выходите из сеанса worktree, очистка зависит от того, внесли ли вы изменения:
  • Нет изменений: worktree и его ветка удаляются автоматически
  • Существуют изменения или коммиты: Claude предлагает вам сохранить или удалить worktree. Сохранение сохраняет каталог и ветку, чтобы вы могли вернуться позже. Удаление удаляет каталог worktree и его ветку, отбрасывая все неотправленные изменения и коммиты
  • Неинтерактивные запуски: worktrees, созданные с помощью --worktree вместе с -p, не очищаются автоматически, так как нет подсказки выхода. Удалите их с помощью git worktree remove
Worktrees subagent, оставленные без присмотра из-за сбоя или прерванного запуска, удаляются при запуске, если они старше вашего параметра cleanupPeriodDays, при условии, что они не имеют неотправленных изменений, неотслеживаемых файлов и неотправленных коммитов. Worktrees, которые вы создаёте с помощью --worktree, никогда не удаляются этой очисткой.

​
Управляйте worktrees вручную

Для полного контроля над расположением worktree и конфигурацией ветки создавайте worktrees непосредственно с помощью Git. Это полезно, когда вам нужно проверить конкретную существующую ветку или поместить worktree вне репозитория. Создайте worktree на новой ветке: 
git worktree add ../project-feature-a -b feature-a
Создайте worktree из существующей ветки: 
git worktree add ../project-bugfix bugfix-123
Запустите Claude в worktree: 
cd ../project-feature-a && claude
Перечислите ваши worktrees: 
git worktree list
Удалите один, когда вы с ним закончите: 
git worktree remove ../project-feature-a
Полный справочник команд см. в документации Git worktree. Помните, что нужно инициализировать вашу среду разработки в каждом новом worktree: установить зависимости, настроить виртуальные окружения или запустить всё, что требует настройка вашего проекта.

​
Не-git системы контроля версий

Изоляция worktree использует git по умолчанию. Для SVN, Perforce, Mercurial или других систем настройте hooks WorktreeCreate и WorktreeRemove, чтобы предоставить пользовательскую логику создания и очистки. Поскольку hook заменяет поведение git по умолчанию, .worktreeinclude не обрабатывается при использовании --worktree. Скопируйте любые локальные файлы конфигурации внутри вашего скрипта hook вместо этого. Этот hook WorktreeCreate читает имя worktree из stdin, проверяет свежую рабочую копию SVN и выводит путь каталога, чтобы Claude Code мог использовать его как рабочий каталог сеанса: 
{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}
Объедините его с hook WorktreeRemove для очистки при завершении сеанса. Схему входных данных и пример удаления см. в справочнике hooks.

​
См. также

Worktrees обрабатывают изоляцию файлов. Связанные страницы ниже охватывают делегирование работы в эти изолированные копии и переключение между созданными вами сеансами:
  • Subagents: делегируйте работу изолированным агентам внутри сеанса
  • Agent teams: координируйте несколько сеансов Claude автоматически
  • Manage sessions: назовите, возобновите и переключайтесь между беседами
  • Desktop parallel sessions: сеансы на основе worktree в десктопном приложении