AICodingLab
Claude Code лайфхаки · Урок 23 из 35

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:

  1. Создание: EnterWorktree создаёт новый worktree в .claude/worktrees/
  2. Изоляция: Переключает сессию в новую директорию
  3. Ветвление: Автоматически создаёт новую git ветку
  4. Очистка: 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

📝 Домашнее задание

  1. Базовое задание: Создайте изолированную ветку для новой функции в вашем проекте, используя команду EnterWorktree. Внесите минимум 3 коммита с реальными изменениями.
  2. Параллельная работа: Создайте два worktree одновременно для разных задач. Поработайте в обоих, делая коммиты попеременно. Убедитесь, что изменения изолированы.
  3. Hotfix сценарий: Симулируйте ситуацию срочного исправления: работайте над feature, затем создайте второй worktree для hotfix, исправьте баг, вернитесь к feature.
  4. Очистка: Вернитесь в основную ветку с помощью команды ExitWorktree. Попробуйте оба варианта: --action keep и --action remove.
  5. Автоматизация: Напишите bash-скрипт, который создаёт worktree, выполняет тесты, и автоматически удаляет worktree после завершения.
  6. Мониторинг: Реализуйте функцию в вашем проекте, которая показывает список всех активных worktree и их возраст. Автоматически предупреждайте о worktree старше недели.
  7. Отчёт: Подготовьте краткий отчет о том, как использование изолированных веток повлияло на вашу работу. Какие сценарии оказались самыми полезными?

🎓 После урока вы умеете

  • Создавать изолированные ветки для разработки с помощью команды EnterWorktree
  • Управлять изменениями и тестировать их без риска для основной кодовой базы
  • Возвращаться к основной ветке проекта, используя команду ExitWorktree
  • Работать с несколькими ветками параллельно без переключения контекста
  • Проводить A/B тестирование разных подходов в изолированных средах
  • Быстро переключаться на hotfix без потери текущей работы
  • Интегрировать worktree в CI/CD pipeline для автоматического тестирования
  • Диагностировать и решать типичные проблемы с worktree
  • Автоматизировать управление worktree с помощью скриптов
  • Оптимизировать использование дискового пространства при работе с множеством worktree

🔗 Дополнительные ресурсы

Рекомендуемые курсы

Продолжите обучение по смежным темам

ИИ-наставник по этому уроку

Задайте вопрос по теме урока «EnterWorktree / ExitWorktree: изолированные ветки» — наставник ответит, опираясь на его содержание. Он помогает понять, но не делает домашку за вас.

Привет! Я наставник по этому уроку. Спросите что угодно по теме — объясню простыми словами. 🙂
Ответы генерирует ИИ и может ошибаться — сверяйтесь с уроком.
ИИ-консультант
Помогу выбрать курс