Использование git worktree

Обзор

Обеспечьте, чтобы работа шла в изолированном рабочем пространстве. Предпочитайте нативные инструменты worktree вашей платформы. Откатывайтесь на ручные git worktree только когда нативного инструмента нет.

Главный принцип: сначала обнаружьте существующую изоляцию. Затем используйте нативные инструменты. Затем откат на git. Никогда не боритесь с обвязкой (harness).

Объявите в начале: «Я использую скилл using-git-worktrees, чтобы настроить изолированное рабочее пространство.»

Шаг 0: Обнаружить существующую изоляцию

Прежде чем что-либо создавать, проверьте, не находитесь ли вы уже в изолированном рабочем пространстве.

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
BRANCH=$(git branch --show-current)

Защита от сабмодулей: GIT_DIR != GIT_COMMON верно и внутри git-сабмодулей. Прежде чем заключать «уже в worktree», убедитесь, что вы не в сабмодуле:

# Если вернулся путь — вы в сабмодуле, а не в worktree — считайте обычным репозиторием
git rev-parse --show-superproject-working-tree 2>/dev/null

Если GIT_DIR != GIT_COMMON (и это не сабмодуль): вы уже в связанном worktree. Переходите к Шагу 2 (настройка проекта). НЕ создавайте ещё один worktree.

Отчитайтесь о состоянии ветки:

• На ветке: «Уже в изолированном пространстве по пути <path> на ветке <name>.»
• Detached HEAD: «Уже в изолированном пространстве по пути <path> (detached HEAD, управляется извне). Создание ветки понадобится на этапе завершения.»

Если GIT_DIR == GIT_COMMON (или вы в сабмодуле): вы в обычной выписке репозитория.

Указал ли пользователь предпочтение по worktree в инструкциях? Если нет, спросите согласие перед созданием worktree:

«Настроить изолированный worktree? Он защитит вашу текущую ветку от изменений.»

Уважайте любое уже заявленное предпочтение без вопросов. Если пользователь отказывается — работайте на месте и переходите к Шагу 2.

Шаг 1: Создать изолированное рабочее пространство

У вас есть два механизма. Пробуйте в этом порядке.

1a. Нативные инструменты worktree (предпочтительно)

Пользователь запросил изолированное пространство (согласие из Шага 0). Есть ли у вас уже способ создать worktree? Это может быть инструмент с именем вроде EnterWorktree, WorktreeCreate, команда /worktree или флаг --worktree. Если есть — используйте его и переходите к Шагу 2.

Нативные инструменты сами обрабатывают размещение каталога, создание ветки и очистку. Использование git worktree add при наличии нативного инструмента создаёт «фантомное» состояние, которое ваша обвязка не видит и не может контролировать.

Переходите к Шагу 1b только если нативного инструмента worktree нет.

1b. Запасной вариант через git worktree

Используйте, только если Шаг 1a неприменим — нативного инструмента нет. Создайте worktree вручную через git.

Выбор каталога

Следуйте этому порядку приоритета. Явное предпочтение пользователя всегда побеждает наблюдаемое состояние файловой системы.

1. Проверьте инструкции на заявленное предпочтение каталога worktree. Если пользователь уже указал — используйте без вопросов.
2. Проверьте существующий проектный каталог worktree:

   ls -d .worktrees 2>/dev/null     # Предпочтительно (скрытый)
   ls -d worktrees 2>/dev/null      # Альтернатива
   

   Если найден — используйте. Если есть оба — побеждает .worktrees.
3. Если иных указаний нет, по умолчанию .worktrees/ в корне проекта.

Проверка безопасности (только для проектных каталогов)

ОБЯЗАТЕЛЬНО убедитесь, что каталог игнорируется, перед созданием worktree:

git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null

Если НЕ игнорируется: добавьте в .gitignore, закоммитьте изменение, затем продолжайте.

Почему критично: предотвращает случайный коммит содержимого worktree в репозиторий.

Создайте worktree

# Определите путь по выбранному расположению
path="$LOCATION/$BRANCH_NAME"

git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"

Откат для песочницы: если git worktree add падает с ошибкой прав (отказ песочницы), сообщите пользователю, что песочница заблокировала создание worktree и вы работаете в текущем каталоге. Затем запустите настройку и базовые тесты на месте.

Шаг 2: Настройка проекта

Автоопределение и запуск подходящей настройки:

# Node.js
if [ -f package.json ]; then npm install; fi
# Rust
if [ -f Cargo.toml ]; then cargo build; fi
# Python
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi
# Go
if [ -f go.mod ]; then go mod download; fi

Шаг 3: Проверить чистую базовую точку

Запустите тесты, чтобы убедиться, что пространство стартует чистым:

# Используйте команду, подходящую проекту
npm test / cargo test / pytest / go test ./...

Если тесты падают: сообщите о провалах, спросите — продолжать или разбираться. Если проходят: доложите о готовности.

Отчёт

Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>

Краткая справка

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

Борьба с обвязкой

• Проблема: использование git worktree add, когда платформа уже даёт изоляцию
• Фикс: Шаг 0 обнаруживает существующую изоляцию. Шаг 1a уступает нативным инструментам.

Пропуск обнаружения

• Проблема: создание вложенного worktree внутри существующего
• Фикс: всегда выполняйте Шаг 0 перед созданием чего-либо

Пропуск проверки игнорирования

• Проблема: содержимое worktree отслеживается, засоряет git status
• Фикс: всегда используйте git check-ignore перед созданием проектного worktree

Допущение о расположении каталога

• Проблема: создаёт несогласованность, нарушает соглашения проекта
• Фикс: следуйте приоритету: явные инструкции > существующий проектный каталог > по умолчанию

Продолжение с падающими тестами

• Проблема: нельзя отличить новые баги от уже существующих
• Фикс: сообщите о провалах, получите явное разрешение продолжать

Красные флаги

Никогда:

• Создавать worktree, когда Шаг 0 обнаружил существующую изоляцию
• Использовать git worktree add при наличии нативного инструмента (напр. EnterWorktree). Это ошибка №1 — если он есть, используйте его.
• Пропускать Шаг 1a, прыгая сразу к git-командам Шага 1b
• Создавать worktree без проверки, что он игнорируется (проектный)
• Пропускать проверку базовой точки тестами
• Продолжать с падающими тестами без вопроса

Всегда:

• Сначала выполнять обнаружение из Шага 0
• Предпочитать нативные инструменты git-откату
• Следовать приоритету каталога: явные инструкции > существующий проектный каталог > по умолчанию
• Проверять, что проектный каталог игнорируется
• Автоопределять и запускать настройку проекта
• Проверять чистую базовую точку тестами