forgeplan git-sync

Инкрементально синхронизирует LanceDB с изменениями в markdown, внесёнными операцией git - обычно git pull, git merge или git rebase. Вместо полной перестройки индекса git-sync сравнивает рабочее дерево с ссылкой git и повторно парсит только те артефакты, которые фактически изменились.

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

forgeplan git-sync [OPTIONS]

Опции

      --since <SINCE>  Ссылка Git для сравнения (по умолчанию: ORIG_HEAD из последнего pull/merge)
  -h, --help           Вывести справку
  -V, --version        Вывести версию

Как это работает

1. Выполняет git diff --name-only <SINCE> HEAD в области .forgeplan/.
2. Фильтрует результат, оставляя файлы артефактов с расширением .md.
3. Для каждого изменённого файла: повторно парсит и обновляет соответствующую строку в LanceDB.
4. Для удалённых файлов: удаляет соответствующие строки из индекса.
5. Пересчитывает производные поля (теги, ссылки, оценки) для затронутого набора.

ORIG_HEAD используется по умолчанию, потому что git pull/git merge/git rebase устанавливают его на предыдущий кончик текущей ветки, предоставляя git-sync точное «окно» того, что было получено при данном pull.

Когда это использовать

• После git pull - коллеги объединили новые PRD/RFC в dev, вы только что выполнили pull, и хотите, чтобы они появились в вашем локальном LanceDB. git-sync выполняется за долю времени полной переиндексации.
• После git merge feature/xyz - то же самое для локальных слияний.
• После git checkout между ветками с расходящимся состоянием артефактов - передайте --since <other-branch> для синхронизации изменений.

Рабочий процесс удалённой команды

# Утренняя рутина с активной командой
git checkout dev
git pull origin dev          # получает 3 новых PRD от коллег
forgeplan git-sync           # <1с: переиндексированы только 3 новых файла
forgeplan list --since 1d    # посмотреть, что пришло
forgeplan health             # проверить наличие новых слепых пятен

Сравнение с холодной пересборкой:

forgeplan reindex            # обходит всё рабочее пространство - безопасно, но медленнее

Для небольших рабочих пространств разница незначительна; для рабочих пространств с сотнями артефактов git-sync значительно быстрее.

git-sync vs reindex vs watch

Команда	Использовать, когда	Стоимость
git-sync	После git pull/merge, если известна ссылка для сравнения	O(изменённые файлы)
reindex	Ручные изменения, свежее клонирование, неизвестное расхождение	O(все артефакты)
watch	Интерактивное редактирование, нужна живая синхронизация	демон, O(событие)

Эмпирическое правило: если git только что переместил HEAD, используйте git-sync. Если вы редактировали файлы самостоятельно в редакторе, используйте reindex (или оставьте watch запущенным). Если вы не уверены, синхронизирован ли индекс, reindex всегда является безопасным запасным вариантом.

Пример

# По умолчанию - с момента последнего pull/merge
forgeplan git-sync

# Явная база для сравнения (например, с main)
forgeplan git-sync --since origin/main

# Проверить, что принесла ветка PR
git checkout feat/prd-050-discover
forgeplan git-sync --since dev

Ограничения

• Требует чистого рабочего дерева git для надёжного сравнения - незафиксированные изменения могут быть пропущены или учтены дважды. Используйте в паре с watch для «грязных» деревьев.
• Если ORIG_HEAD устарел (не было недавних pull/merge), передайте --since явно.
• Не обнаруживает внеполосные изменения markdown - используйте reindex для таких случаев.

См. также

• Обзор CLI
• forgeplan reindex - запасной вариант полной пересборки
• forgeplan watch - демон живой синхронизации
• forgeplan health - проверка после синхронизации