Git worktrees + Claude Code

Почему это важно именно вам

Представьте: вы готовите квартальный отчёт по маркетингу в одной папке. В середине работы руководитель просит срочно сделать отдельный вариант того же отчёта — но с другими данными, для другого адресата, с другим форматом. Вы открываете ту же папку и начинаете резать и переписывать. Потом выясняется, что оригинальный отчёт тоже нужен, и вы либо держите в голове, что куда изменилось, либо судорожно ищете резервную копию, которую зачем-то назвали otchet_final_final2_v3.docx.

В мире с git эта проблема решается ветками: основная версия живёт в main, экспериментальная — в draft. Но классическая работа с ветками выглядит так: сохранил одно, переключился, открыл другое. Claude при каждом переключении теряет контекст — он не знает, в какой ветке вы сейчас находитесь. Если вы работаете над двумя вещами параллельно, приходится постоянно объяснять ему ситуацию заново.

Git worktrees решают именно это. Каждая ветка живёт в своей физической папке, Claude запускается отдельно в каждой, и никакого переключения контекста. Для директора, который ведёт несколько версий документов, шаблонов, инструкций или аналитических скриптов одновременно, это реальная экономия времени и нервов.

Ещё один сценарий: вы хотите, чтобы Claude проверил текущее состояние документа, пока вы сами редактируете другой. Без worktrees Claude будет видеть незафиксированные изменения и путаться. С worktrees каждый экземпляр видит только свою версию файлов — чистую, без мусора соседнего сеанса.

Что это такое

Обычно git-репозиторий — это папка, внутри которой лежат ваши файлы. Когда вы переключаетесь между ветками (например, git checkout draft), папка физически меняет содержимое — старые файлы уходят, появляются новые. Это как если бы вы вошли в один и тот же кабинет, но каждый раз на столе оказывалась другая стопка бумаг.

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

С точки зрения файловой системы это выглядит так: есть основная папка project/ с веткой main, а рядом появляется папка project-draft/ с веткой draft. Обе папки — это один репозиторий, но каждая видит свою ветку. Изменения в одной папке не влияют на другую, пока вы явно не сольёте ветки.

Для Claude Code это означает, что вы можете запустить два независимых сеанса: один в project/, другой в project-draft/. Каждый сеанс будет читать CLAUDE.md своей ветки, работать с файлами своей ветки, и не мешать другому.

Технически под капотом одна .git/-директория обслуживает несколько рабочих папок. Git хранит информацию обо всех активных worktrees в .git/worktrees/. Это означает, что размер на диске увеличивается ровно на размер файлов новой ветки — общая история и объекты не дублируются. Для папки с документами на 50 МБ новый worktree займёт ещё ~50 МБ, а не удвоит репозиторий целиком.

Как работает на практике

Разберём на конкретном примере: вы ведёте папку с шаблонами писем для клиентов. В основной ветке — рабочие шаблоны, используемые командой каждый день. Нужно подготовить экспериментальный набор под новый регион — там другой тон, другие юридические оговорки, другие контакты. Менять рабочие шаблоны нельзя: команда на них опирается. Копировать всю папку вручную — значит потом разбираться, что куда ушло. Worktree — правильное решение: отдельная физическая папка с отдельной веткой, Claude работает только там, рабочие шаблоны не тронуты.

Шаг 1. Убедитесь, что папка — git-репозиторий

cd ~/Documents/templates
git status

Если видите fatal: not a git repository — сначала инициализируйте репозиторий:

git init
git add .
git commit -m "исходные шаблоны"

Если уже видите что-то про ветку main или master — всё готово.

Шаг 2. Создайте worktree для новой ветки

git worktree add ../templates-spb spb-region

Разберём команду по частям:
- git worktree add — создать новый «стол»
- ../templates-spb — путь к новой папке (рядом с основной)
- spb-region — название новой ветки (создаётся автоматически)

После этого на диске появляется папка templates-spb/ со всеми теми же файлами, что и в templates/, но в ветке spb-region.

Шаг 3. Запустите Claude в новой папке

cd ~/Documents/templates-spb
claude

Теперь Claude работает в контексте ветки spb-region. Всё, что он читает и изменяет — только в этой папке. Основная папка templates/ не затронута.

Параллельно можно открыть второй терминал и работать в основной папке:

cd ~/Documents/templates
claude

Два Claude, две ветки, одновременно. Каждый в своём контексте.

Шаг 4. Флаг --worktree для Claude

Claude Code поддерживает флаг -w (или --worktree), который принимает имя, а не путь, и создаёт копию внутри репозитория — в <корень>/.claude/worktrees/<имя>/ на новой ветке worktree-<имя>:

claude --worktree templates-spb "проверь все шаблоны на соответствие регламенту СПб"

Это удобно, если вы хотите запустить задачу в конкретном worktree, не переходя туда вручную. Особенно полезно в сочетании с флагом -p для неинтерактивного режима:

claude -p -w templates-spb "сформируй список всех шаблонов с описанием"

Шаг 5. Просмотр всех worktrees

git worktree list

Вывод покажет все активные «столы»:

/Users/you/Documents/templates       abc1234 [main]
/Users/you/Documents/templates-spb   def5678 [spb-region]

Шаг 6. Удаление worktree после работы

Когда ветка больше не нужна (или вы слили изменения обратно в main):

git worktree remove ~/Documents/templates-spb

Папка удалится. Ветка spb-region при этом останется в репозитории — её можно восстановить позже той же командой git worktree add.

Частые ошибки

Ошибка 1: Попытка открыть одну ветку в двух worktrees

git worktree add ../templates-copy main
# error: 'main' is already checked out at '/Users/you/Documents/templates'

Git не разрешает одну и ту же ветку подключить к двум папкам одновременно. Это защита от конфликтов: если бы два места редактировали одни и те же файлы из одной ветки, система не знала бы, какую версию сохранять.

Решение: для каждого worktree нужна своя ветка. Создайте новую от нужной точки:

git branch templates-copy
git worktree add ../templates-copy templates-copy

Ошибка 2: Удалить папку вручную, не через git

Если вы просто удалили папку worktree через Finder или rm -rf, git продолжает считать, что worktree существует. При следующей попытке создать worktree с тем же именем получите ошибку.

Решение — очистить устаревшие ссылки:

git worktree prune

После этого git забудет об удалённых папках и позволит создавать новые.

Ошибка 3: CLAUDE.md не найден в новом worktree

Если в основной ветке есть CLAUDE.md с инструкциями для Claude, но вы создали worktree от более ранней точки или от другой ветки — в новой папке CLAUDE.md может не быть или быть устаревшим.

Claude начнёт работать без контекста и правил, что даст неожиданные результаты.

Незакоммиченные файлы (например, .env) копируются автоматически, если положить в корень проекта файл .worktreeinclude с их перечислением — синтаксис как у .gitignore. Саму папку .claude/worktrees/ стоит внести в .gitignore. Решение для CLAUDE.md: после создания worktree проверьте его наличие:

ls ~/Documents/templates-spb/CLAUDE.md

Если файла нет — скопируйте из основной папки:

cp ~/Documents/templates/CLAUDE.md ~/Documents/templates-spb/
git -C ~/Documents/templates-spb add CLAUDE.md
git -C ~/Documents/templates-spb commit -m "добавлен CLAUDE.md"

Ошибка 4: Передавать в -w путь вместо имени

claude -w ~/Documents/templates-spb создаст worktree с этим текстом в качестве имени внутри .claude/worktrees/ . Правильно — claude -w templates-spb. Чтобы попасть в worktree, созданный руками через git worktree add, просто перейдите в его папку и запустите claude или корректно относительным. ~/Documents/templates-spb работает в терминале, но не всегда в скриптах — там ~ может не раскрыться.

Решение: в скриптах используйте $HOME вместо ~:

claude -p -w templates-spb "проверь шаблоны"

Когда нужно / когда нет

Используйте git worktrees, когда:

• Вы ведёте несколько версий одного набора документов и хотите работать с ними одновременно, не переключаясь
• Нужно дать Claude задачу в одной ветке, пока в другой ветке идёт интерактивная сессия
• Вы тестируете новую структуру папок или шаблонов, не рискуя сломать рабочую версию
• Используете -p режим для автоматических задач в разных ветках (например, генерация отчётов из разных версий данных)
• Хотите, чтобы два человека работали с одним репозиторием в разных ветках на одном компьютере — каждый в своей папке, не наступая друг другу на ноги
• Готовите «горячий резерв»: основная ветка — продакшн-версия документов, worktree — staging, куда идут правки до финального согласования

Не используйте git worktrees, если:

• Репозиторий не настроен — для разовых задач проще просто скопировать папку
• Вам не нужна история изменений — если важны только текущие файлы, не история, worktrees добавляют сложность без выгоды
• Задача решается за один сеанс — переключение между ветками без параллельной работы не требует worktrees
• Вы не понимаете, в какой ветке находитесь — это признак того, что структура репозитория требует упрощения, а не добавления новых механизмов
• Нужно просто сравнить две версии файла — для этого достаточно git diff или инструментов сравнения, worktree избыточен
• Вы работаете с очень большим репозиторием, где checkout новой ветки занимает минуты — в этом случае worktree не ускорит процесс, папка всё равно наполняется файлами

Связь с другими уроками

День 36 (Ветки диалога) — там мы разветвляли один разговор, чтобы попробовать два подхода. Worktrees — та же идея на уровне файловой системы. Git worktrees — это та же идея, но на уровне файловой системы: несколько физических контекстов для параллельной работы. Worktrees хорошо сочетаются с форком субагентов — каждый агент работает в своём worktree.

День 38 (Pre-commit хуки) — хуки, настроенные в основной ветке, не автоматически переносятся в worktree. Если вы используете pre-commit проверки, их нужно отдельно настроить в каждой ветке или убедиться, что конфигурация попала в git. Об этом стоит помнить при создании нового worktree.

День 38 (Pre-commit + Claude Code интеграция) — следующий урок покажет, как автоматически вызывать Claude при сохранении изменений. В контексте worktrees это означает, что каждый «стол» может иметь свой хук с разными инструкциями — например, основная ветка проверяет строгий регламент, экспериментальная работает мягче.

Задание на сегодня

Возьмите любую папку с документами, которая уже является git-репозиторием (или инициализируйте новую с git init + один коммит). Создайте worktree и запустите Claude внутри:

git worktree add ../my-project-draft draft-version
cd ../my-project-draft
claude

Попросите Claude: «ты находишься в черновой ветке draft-version. Посмотри на файлы в этой папке и скажи, что ты видишь».

Если хочется проверить флаг -w без перехода в папку — попробуйте так (из любого места):

claude -p --worktree my-draft "перечисли файлы и их назначение"

Критерий выполнения: в обоих случаях Claude назвал реальные файлы из папки и не сообщил об ошибках. Значит, worktree работает, Claude находится в правильном контексте, и флаг -w функционирует корректно. После завершения сеанса можете убрать тестовый worktree: git worktree remove "$HOME/my-project-draft".

Резюме

• Git worktree — это отдельная физическая папка для каждой ветки. Несколько папок = несколько параллельных контекстов без переключений. Дисковое пространство расходуется только на файлы новой ветки, история git не дублируется.
• Флаг -w в Claude Code позволяет запускать сеанс или задачу в конкретном worktree, не переходя туда вручную. В сочетании с -p это основа для автоматизированных задач над несколькими ветками из скриптов.
• Удалять worktree нужно через git worktree remove, а не через Finder — иначе git теряет ориентацию и нужно запускать git worktree prune.
• CLAUDE.md не копируется автоматически в новый worktree — проверяйте наличие файла после создания, иначе Claude работает без контекста.
• Одна ветка — один worktree. Попытка открыть ту же ветку в двух папках вызовет ошибку git. Для параллельной работы создавайте новую ветку от нужной точки.
• Инструмент полезен при параллельной работе с несколькими версиями документов; для однопоточной работы добавляет сложность без выгоды.