Git Worktrees

Hermes Agent часто используется в больших, долгоживущих репозиториях. Когда вам нужно:

• Запускать несколько агентов параллельно в одном проекте, или

• Держать экспериментальные рефакторинги изолированными от вашей основной ветки,

Worktrees (рабочие деревья) Git — это самый безопасный способ дать каждому агенту свою собственную рабочую копию без дублирования всего репозитория.

На этой странице показано, как объединить worktrees с Hermes, чтобы каждый сеанс имел чистый, изолированный рабочий каталог.

Зачем использовать Worktrees с Hermes?

Hermes считает текущий рабочий каталог корнем проекта:

• CLI: каталог, в котором вы запускаете hermes или hermes chat

• Шлюзы обмена сообщениями: каталог, заданный параметром MESSAGING_CWD

Если вы запускаете несколько агентов в одной рабочей копии, их изменения могут мешать друг другу:

• Один агент может удалить или перезаписать файлы, которые использует другой.

• Становится сложнее понять, какие изменения относятся к какому эксперименту.

С worktrees каждый агент получает:

• Собственную ветку и рабочий каталог

• Собственную историю Checkpoint Manager для /rollback

См. также: Checkpoints and /rollback.

Быстрый старт: Создание Worktree

Из вашего основного репозитория (содержащего .git/) создайте новый worktree для ветки функции:

# From the main repo root
cd /path/to/your/repo

# Create a new branch and worktree in ../repo-feature
git worktree add ../repo-feature feature/hermes-experiment

Это создаст:

• Новый каталог: ../repo-feature

• Новую ветку: feature/hermes-experiment, извлечённую в этом каталоге

Теперь вы можете перейти в новый worktree и запустить там Hermes:

cd ../repo-feature

# Start Hermes in the worktree
hermes

Hermes будет:

• Считать ../repo-feature корнем проекта.

• Использовать этот каталог для контекстных файлов, редактирования кода и инструментов.

• Использовать отдельную историю контрольных точек для /rollback, ограниченную этим worktree.

Запуск нескольких агентов параллельно

Вы можете создать несколько worktrees, каждый со своей собственной веткой:

cd /path/to/your/repo

git worktree add ../repo-experiment-a feature/hermes-a
git worktree add ../repo-experiment-b feature/hermes-b

В отдельных терминалах:

# Terminal 1
cd ../repo-experiment-a
hermes

# Terminal 2
cd ../repo-experiment-b
hermes

Каждый процесс Hermes:

• Работает в своей собственной ветке (feature/hermes-a против feature/hermes-b).

• Записывает контрольные точки под другим хешем теневого репозитория (производным от пути worktree).

• Может использовать /rollback независимо, не влияя на другой.

Это особенно полезно, когда:

• Выполняются пакетные рефакторинги.

• Опробуются разные подходы к одной и той же задаче.

• Объединяются сессии CLI и шлюза для работы с одним и тем же вышестоящим репозиторием.

Безопасная очистка Worktrees

Когда вы закончите с экспериментом:

1. Решите, сохранить или отбросить работу.

2. Если вы хотите сохранить её:

3. Слейте ветку с вашей основной веткой как обычно.

4. Удалите worktree:

cd /path/to/your/repo

# Remove the worktree directory and its reference
git worktree remove ../repo-feature

Примечания:

• git worktree remove откажется удалять worktree с незафиксированными изменениями, если только вы не принудите это.

• Удаление worktree не удаляет автоматически ветку; вы можете удалить или оставить ветку с помощью обычных команд git branch.

• Данные контрольных точек Hermes в ~/.hermes/checkpoints/ автоматически не удаляются при удалении worktree, но обычно они очень малы.

Лучшие практики

• Один worktree на эксперимент Hermes
• Создавайте отдельную ветку/worktree для каждого существенного изменения.

• Это сохраняет diffs сфокусированными, а PRs небольшими и обозримыми.

• Называйте ветки по имени эксперимента

• например: feature/hermes-checkpoints-docs, feature/hermes-refactor-tests.

• Делайте коммиты часто

• Используйте git-коммиты для вех высокого уровня.

• Используйте контрольные точки и /rollback как страховочную сетку для изменений, управляемых инструментами, в промежутках.

• Избегайте запуска Hermes из корня репозитория при использовании worktrees

• Вместо этого используйте каталоги worktree, чтобы у каждого агента была четкая область действия.

Использование hermes -w (Автоматический режим Worktree)

Hermes имеет встроенный флаг -w, который автоматически создает одноразовый worktree git с собственной веткой. Вам не нужно настраивать worktrees вручную — просто перейдите в ваш репозиторий и выполните:

cd /path/to/your/repo
hermes -w

Hermes будет:

• Создавать временный worktree в .worktrees/ внутри вашего репозитория.

• Извлекать изолированную ветку (например, hermes/hermes-<hash>).

• Запускать полную сессию CLI внутри этого worktree.

Это самый простой способ получить изоляцию worktree. Вы также можете объединить его с одним запросом:

hermes -w -q "Fix issue #123"

Для параллельных агентов откройте несколько терминалов и запустите hermes -w в каждом — каждый вызов автоматически получает свой собственный worktree и ветку.

Собираем всё вместе

• Используйте git worktrees, чтобы дать каждой сессии Hermes свою чистую рабочую копию.

• Используйте ветки, чтобы фиксировать высокоуровневую историю ваших экспериментов.

• Используйте контрольные точки + /rollback для восстановления после ошибок внутри каждого worktree.

Эта комбинация даёт вам:

• Надёжные гарантии того, что разные агенты и эксперименты не мешают друг другу.

• Быстрые циклы итераций с лёгким восстановлением после неудачных правок.

• Чистые, обозримые pull request'ы.