EnterWorktree / ExitWorktree: изолированные ветки
EnterWorktree и ExitWorktree для создания изолированных веток в Claude Code, что позволит эффективно управлять проектами и тестировать изменения без влияния на основную ветку.📖 Теория
В процессе разработки программного обеспечения часто возникает необходимость тестирования новых функций или исправлений без риска повредить основную кодовую базу. Команды EnterWorktree и ExitWorktree в Claude Code позволяют создавать и использовать изолированные ветки, что делает процесс более безопасным и управляемым.
Что такое Git Worktree?
Git worktree — это механизм Git, позволяющий иметь несколько рабочих директорий одновременно для одного репозитория. Вместо переключения между ветками с помощью git checkout, вы можете работать с несколькими ветками параллельно в разных директориях.
Традиционный подход (git checkout):
git checkout main # работаем на main
git checkout feature-auth # переключаемся, теряем контекст main
git checkout main # возвращаемся, теряем контекст feature-auth
Подход с worktree:
# Основная директория на main
/project (main)
# Параллельные worktree
/project/.claude/worktrees/feature-auth (feature-auth)
/project/.claude/worktrees/bugfix-123 (bugfix-123)
Преимущества изолированных веток
- Безопасность: изменения не влияют на основную кодовую базу
- Параллельная работа: можно работать над несколькими задачами одновременно
- Чистота: возможность тестирования и отладки в изолированной среде
- Гибкость: простота в управлении различными версиями кода
- Упрощение коллаборации: работа в команде становится более организованной
- Изоляция зависимостей: каждый worktree может иметь свои node_modules, venv и т.д.
- Быстрое сравнение: легко сравнить код между ветками без переключения
Когда использовать Worktree
✅ Используйте worktree когда:
- Нужно срочно переключиться на hotfix, не теряя текущую работу
- Тестируете сложный рефакторинг и хотите сравнить со старым кодом
- Работаете над несколькими feature одновременно
- Проводите code review и хотите локально запустить чужую ветку
- Экспериментируете с breaking changes без риска
❌ Не используйте worktree когда:
- Простое переключение между ветками (обычный git checkout быстрее)
- Ограничены в дисковом пространстве (worktree дублирует файлы)
- Работаете с одной задачей линейно
Как Claude Code управляет Worktree
Claude Code автоматизирует создание и управление worktree:
- Создание:
EnterWorktreeсоздаёт новый worktree в.claude/worktrees/ - Изоляция: Переключает сессию в новую директорию
- Ветвление: Автоматически создаёт новую git ветку
- Очистка:
ExitWorktreeудаляет worktree или сохраняет его
🛠 Практика
Базовое использование
Шаг 1. Создание изолированной ветки с помощью команды EnterWorktree.
EnterWorktree my-feature-branch
Эта команда создаст новую изолированную ветку с именем my-feature-branch. Теперь вы можете вносить изменения и тестировать их, не затрагивая основную ветку проекта.
Что происходит под капотом:
# Claude Code выполняет:
git worktree add .claude/worktrees/my-feature-branch -b my-feature-branch
cd .claude/worktrees/my-feature-branch
# Теперь вы в изолированной среде:
pwd # /project/.claude/worktrees/my-feature-branch
git branch # * my-feature-branch
Шаг 2. Работа в worktree.
# Все файлы доступны, можете редактировать
cat src/app.js
# Изменения влияют только на эту ветку
echo "console.log('feature');" >> src/app.js
# Коммиты идут в изолированную ветку
git add .
git commit -m "feat: add new feature"
Шаг 3. Выход из изолированной ветки с помощью команды ExitWorktree.
ExitWorktree --action keep
После завершения работы над изменениями и их тестирования, вы можете выйти из изолированной ветки, вернувшись в основную рабочую область.
Варианты выхода:
# Сохранить worktree (для продолжения работы позже)
ExitWorktree --action keep
# Удалить worktree (работа завершена)
ExitWorktree --action remove
# Удалить даже с несохранёнными изменениями
ExitWorktree --action remove --discard_changes true
Продвинутые сценарии
Сценарий 1: Срочный Hotfix во время feature-разработки
# Работаем над фичей
EnterWorktree feature-user-auth
# ... пишем код ...
# Внезапно нужен срочный hotfix!
# Создаём второй worktree
EnterWorktree hotfix-security-patch
# Исправляем критичный баг
echo "Fixed security issue" > CHANGELOG.md
git add . && git commit -m "fix: security patch"
git push origin hotfix-security-patch
# Возвращаемся к feature
ExitWorktree --action keep
# Теперь вернулись в feature-user-auth, продолжаем работу
Сценарий 2: A/B тестирование двух подходов
# Подход A: REST API
EnterWorktree feature-rest-api
# ... реализуем REST ...
npm run benchmark # 150ms average response
# Подход B: GraphQL
EnterWorktree feature-graphql
# ... реализуем GraphQL ...
npm run benchmark # 95ms average response
# Сравниваем результаты и выбираем лучший
# Удаляем неудачный вариант
ExitWorktree --action remove
Сценарий 3: Code Review локально
# Коллега отправил PR, хотим проверить локально
EnterWorktree review-pr-456
# Скачиваем его ветку
git fetch origin pull/456/head:pr-456
git checkout pr-456
# Тестируем
npm install
npm test
npm start
# Если всё ОК, мержим в основной репозиторий
# Удаляем worktree
ExitWorktree --action remove
Сценарий 4: Экспериментальный рефакторинг
# Хотим попробовать переписать модуль на TypeScript
EnterWorktree experiment-typescript-migration
# Переписываем один модуль
mv src/auth.js src/auth.ts
# ... конвертируем код ...
# Тестируем производительность
npm run perf-test
# Если результаты плохие - просто удаляем worktree
ExitWorktree --action remove --discard_changes true
# Никаких следов эксперимента в истории Git!
Интеграция с CI/CD
Автоматическое тестирование worktree перед мержем:
#!/bin/bash
# scripts/test-in-worktree.sh
BRANCH_NAME="test-$RANDOM"
# Создаём временный worktree
git worktree add /tmp/worktree-$BRANCH_NAME -b $BRANCH_NAME
# Переходим в него
cd /tmp/worktree-$BRANCH_NAME
# Устанавливаем зависимости
npm ci
# Прогоняем тесты
npm test
npm run lint
npm run type-check
# Сохраняем результат
TEST_RESULT=$?
# Чистим за собой
cd -
git worktree remove /tmp/worktree-$BRANCH_NAME
git branch -D $BRANCH_NAME
exit $TEST_RESULT
Управление несколькими Worktree
Список активных worktree:
git worktree list
# Вывод:
# /project abc1234 [main]
# /project/.claude/worktrees/feature-auth def5678 [feature-auth]
# /project/.claude/worktrees/hotfix-123 ghi9012 [hotfix-123]
Удаление старых worktree:
# Удалить конкретный worktree
git worktree remove .claude/worktrees/feature-auth
# Очистить все неактивные
git worktree prune
# Принудительное удаление (если есть несохранённые изменения)
git worktree remove --force .claude/worktrees/old-feature
Production-Ready скрипт управления Worktree
#!/usr/bin/env python3
"""
Worktree Manager - управление git worktree с автоматической очисткой
"""
import os
import subprocess
import json
from pathlib import Path
from datetime import datetime, timedelta
class WorktreeManager:
def __init__(self, repo_path="."):
self.repo_path = Path(repo_path).resolve()
self.worktree_dir = self.repo_path / ".claude" / "worktrees"
self.state_file = self.worktree_dir / "state.json"
def create(self, name, base_branch="main"):
"""Создать новый worktree"""
worktree_path = self.worktree_dir / name
if worktree_path.exists():
raise ValueError(f"Worktree {name} already exists")
# Создаём worktree
subprocess.run([
"git", "worktree", "add",
str(worktree_path),
"-b", name,
base_branch
], check=True)
# Сохраняем метаданные
self._save_metadata(name, {
"created_at": datetime.now().isoformat(),
"base_branch": base_branch,
"path": str(worktree_path)
})
return worktree_path
def remove(self, name, force=False):
"""Удалить worktree"""
worktree_path = self.worktree_dir / name
if not worktree_path.exists():
raise ValueError(f"Worktree {name} not found")
# Удаляем worktree
cmd = ["git", "worktree", "remove", str(worktree_path)]
if force:
cmd.append("--force")
subprocess.run(cmd, check=True)
# Удаляем метаданные
self._remove_metadata(name)
def list_all(self):
"""Список всех worktree"""
result = subprocess.run(
["git", "worktree", "list", "--porcelain"],
capture_output=True,
text=True,
check=True
)
worktrees = []
current = {}
for line in result.stdout.split("\n"):
if line.startswith("worktree "):
if current:
worktrees.append(current)
current = {"path": line.split(" ", 1)[1]}
elif line.startswith("branch "):
current["branch"] = line.split(" ", 1)[1]
elif line.startswith("HEAD "):
current["commit"] = line.split(" ", 1)[1]
if current:
worktrees.append(current)
return worktrees
def cleanup_old(self, max_age_days=7):
"""Удалить worktree старше N дней"""
metadata = self._load_metadata()
cutoff = datetime.now() - timedelta(days=max_age_days)
removed = []
for name, data in metadata.items():
created = datetime.fromisoformat(data["created_at"])
if created < cutoff:
try:
self.remove(name, force=True)
removed.append(name)
except Exception as e:
print(f"Failed to remove {name}: {e}")
return removed
def _save_metadata(self, name, data):
"""Сохранить метаданные worktree"""
self.worktree_dir.mkdir(parents=True, exist_ok=True)
metadata = self._load_metadata()
metadata[name] = data
with open(self.state_file, "w") as f:
json.dump(metadata, f, indent=2)
def _remove_metadata(self, name):
"""Удалить метаданные worktree"""
metadata = self._load_metadata()
metadata.pop(name, None)
with open(self.state_file, "w") as f:
json.dump(metadata, f, indent=2)
def _load_metadata(self):
"""Загрузить метаданные всех worktree"""
if not self.state_file.exists():
return {}
with open(self.state_file) as f:
return json.load(f)
# Использование
if __name__ == "__main__":
manager = WorktreeManager()
# Создать worktree
manager.create("feature-new-api")
# Список всех
for wt in manager.list_all():
print(f"{wt['branch']}: {wt['path']}")
# Очистить старые
removed = manager.cleanup_old(max_age_days=7)
print(f"Removed old worktrees: {removed}")
⚠️ Troubleshooting
Проблема 1: "worktree already exists"
Симптомы: Ошибка при попытке создать worktree с существующим именем.
Error: worktree 'feature-auth' already exists
Решение:
# Проверить список worktree
git worktree list
# Удалить существующий
git worktree remove .claude/worktrees/feature-auth
# Или использовать другое имя
EnterWorktree feature-auth-v2
Проблема 2: "cannot remove worktree, uncommitted changes"
Симптомы: Не можете удалить worktree с несохранёнными изменениями.
Решение:
# Вариант 1: Сохранить изменения
cd .claude/worktrees/my-feature
git add .
git commit -m "WIP: save progress"
cd ../..
git worktree remove .claude/worktrees/my-feature
# Вариант 2: Принудительно удалить
git worktree remove --force .claude/worktrees/my-feature
# Вариант 3: Через Claude Code
ExitWorktree --action remove --discard_changes true
Проблема 3: Конфликт node_modules между worktree
Симптомы: После переключения между worktree приложение не запускается из-за разных версий зависимостей.
Решение:
# Каждый worktree должен иметь свои node_modules
cd .claude/worktrees/feature-a
npm install # устанавливаем зависимости локально
# Добавить в .gitignore
echo ".claude/worktrees/**/node_modules" >> .gitignore
# Или использовать symlink на общие зависимости
ln -s ../../../node_modules .claude/worktrees/feature-a/node_modules
Проблема 4: Забыли в каком worktree находимся
Симптомы: Коммитите в неправильную ветку.
Решение:
# Добавить индикатор в prompt
# В ~/.bashrc или ~/.zshrc:
parse_git_worktree() {
if git worktree list 2>/dev/null | grep -q "$(pwd)"; then
echo "[worktree]"
fi
}
PS1='$(parse_git_worktree) \w $ '
# Теперь prompt покажет:
# [worktree] /project/.claude/worktrees/feature-auth $
Проблема 5: Worktree занимает слишком много места
Симптомы: Диск заполнен из-за множества worktree.
Решение:
# Проверить размер
du -sh .claude/worktrees/*
# Удалить неиспользуемые
git worktree prune
# Настроить автоматическую очистку (cron)
# /etc/cron.daily/cleanup-worktrees
#!/bin/bash
cd /path/to/project
git worktree list | grep "\.claude/worktrees" | while read path rest; do
# Если worktree старше 7 дней
if [ $(find "$path" -maxdepth 0 -mtime +7) ]; then
git worktree remove --force "$path"
fi
done
Проблема 6: Ветка заблокирована другим worktree
Симптомы: Не можете checkout ветку, потому что она используется в worktree.
error: branch 'feature-x' is already checked out at '.claude/worktrees/feature-x'
Решение:
# Удалить worktree, использующий эту ветку
git worktree remove .claude/worktrees/feature-x
# Или работать с этой веткой в существующем worktree
cd .claude/worktrees/feature-x
# продолжить работу здесь
Проблема 7: Потерян путь к worktree после перезагрузки
Симптомы: git worktree list показывает путь, но директория не существует.
Решение:
# Очистить "призрачные" worktree
git worktree prune
# Пересоздать worktree
git worktree add .claude/worktrees/feature-x feature-x
📝 Домашнее задание
- Базовое задание: Создайте изолированную ветку для новой функции в вашем проекте, используя команду
EnterWorktree. Внесите минимум 3 коммита с реальными изменениями. - Параллельная работа: Создайте два worktree одновременно для разных задач. Поработайте в обоих, делая коммиты попеременно. Убедитесь, что изменения изолированы.
- Hotfix сценарий: Симулируйте ситуацию срочного исправления: работайте над feature, затем создайте второй worktree для hotfix, исправьте баг, вернитесь к feature.
- Очистка: Вернитесь в основную ветку с помощью команды
ExitWorktree. Попробуйте оба варианта:--action keepи--action remove. - Автоматизация: Напишите bash-скрипт, который создаёт worktree, выполняет тесты, и автоматически удаляет worktree после завершения.
- Мониторинг: Реализуйте функцию в вашем проекте, которая показывает список всех активных worktree и их возраст. Автоматически предупреждайте о worktree старше недели.
- Отчёт: Подготовьте краткий отчет о том, как использование изолированных веток повлияло на вашу работу. Какие сценарии оказались самыми полезными?
🎓 После урока вы умеете
- Создавать изолированные ветки для разработки с помощью команды
EnterWorktree - Управлять изменениями и тестировать их без риска для основной кодовой базы
- Возвращаться к основной ветке проекта, используя команду
ExitWorktree - Работать с несколькими ветками параллельно без переключения контекста
- Проводить A/B тестирование разных подходов в изолированных средах
- Быстро переключаться на hotfix без потери текущей работы
- Интегрировать worktree в CI/CD pipeline для автоматического тестирования
- Диагностировать и решать типичные проблемы с worktree
- Автоматизировать управление worktree с помощью скриптов
- Оптимизировать использование дискового пространства при работе с множеством worktree
🔗 Дополнительные ресурсы
Рекомендуемые курсы
Продолжите обучение по смежным темам
ИИ-наставник по этому уроку
Задайте вопрос по теме урока «EnterWorktree / ExitWorktree: изолированные ветки» — наставник ответит, опираясь на его содержание. Он помогает понять, но не делает домашку за вас.