Git и submodules — целевое требование (v1)¶

Статус: продуктовая цель / roadmap; нативный Git-UI в IDE в разработке.
Зачем: CascadeIDE задумывается как среда, в которой можно полностью остаться без привычной связки «лёгкая IDE + Cursor»; Git — часть ежедневного цикла, а submodules не должны быть источником боли, как часто бывает в Visual Studio.

Принципы¶

Git — нативно, не «только терминал». Ежедневные операции — через UI IDE; CLI остаётся для редких или продвинутых сценариев.
Submodules — первоклассные, не второстепенный сценарий. Репозитории вроде родителя open + вложенного cascade-ide должны быть понятны с первого экрана.

Чего избегать (опыт VS)¶

Непонятно, в каком репозитории сейчас работа: корень vs каталог submodule.
Статус и diff по submodule размазаны: не видно сразу «изменён gitlink / есть незакоммиченное внутри submodule / расхождение с remote».
Случайные полуоперации: закоммитили родителя, забыли submodule (или наоборот), без явного предупреждения.
Инициализация и обновление без ясных шагов: пустой или устаревший submodule ведёт к молчаливым сбоям сборки вместо понятного диалога.

Целевое поведение (критерии приёмки)¶

Единая картина¶

Видны родительский репозиторий и все зарегистрированные submodules (путь, имя, привязка из .gitmodules).
Для каждого submodule отображаются по меньшей мере: текущий commit/ветка, признак грязной рабочей копии, отставание/опережение относительно записанного в родителе и/или remote (в терминах, понятных пользователю).

Diff и коммит¶

Ясно разделено, что попадает в коммит родителя (в т.ч. обновление gitlink) и что коммитится внутри submodule (файлы).
Стейджинг, просмотр diff, сообщение коммита — доступны для соответствующего контекста (корень / выбранный submodule), без путаницы.

Безопасные действия¶

Явные операции: обновить submodule до записанного в родителе, открыть каталог submodule как корень сессии (или отдельное окно), синхронизировать указатель в родителе после коммита внутри submodule — с понятными подписями и при необходимости подтверждением.

При открытии workspace¶

Если submodule не инициализирован, не на том commit или есть расхождение с ожиданиями — понятное сообщение и короткий путь действий (не молчаливый провал сборки).

Связь с текущей реализацией¶

Сборка аргументов CLI для git в сценариях агента централизована в библиотеке GitMcp.Core (корень meta-repo open), общей для встроенных команд IDE и отдельного процесса git-mcp (ADR 0019).
Сводка по git в полосе телеметрии и вызовы через MCP (GitStatusAsync, GitDiffAsync, GitCommitAsync, GitPushAsync и т.д.) задают контракт для агента.
Вкладка «Git» в нижней панели (Вид → Git): ветка/статус, строка «Корень git» (git rev-parse --show-toplevel) vs каталог решения — чтобы видеть родительский репозиторий и вложенный; список git status --short, diff по выбранной строке, блок git submodule status, стейджинг (git add / git restore --staged), пометка submodule по .gitmodules ([sm]), папка submodule в проводнике, git submodule update --init --recursive и git submodule sync --recursive с выводом в панели, «Открыть решение в submodule» — поиск .slnx/.sln в корне или подпапке первого уровня и LoadSolution (контекст IDE переключается на этот репозиторий), коммит add -A или только staged, push. Дальнейшее развитие — расширенный статус submodule (ветка/грязь/remote), мастера и подтверждения для редких команд (см. критерии выше).

Версионирование документа¶

v1 — зафиксированы принципы и критерии; по мере появления UI детали можно уточнять (имена панелей, MCP-тулов для submodule — отдельными дополнениями).

Operational runbook¶

For recurring AVLN2000 regressions caused by remote/submodule drift, use:
docs/setup/avln2000-submodule-sync-checklist.md