| 1 | # Git и submodules — целевое требование (v1) |
| 2 | |
| 3 | **Статус:** продуктовая цель / roadmap; нативный Git-UI в IDE в разработке. |
| 4 | **Зачем:** CascadeIDE задумывается как среда, в которой можно **полностью остаться** без привычной связки «лёгкая IDE + Cursor»; Git — часть ежедневного цикла, а **submodules** не должны быть источником боли, как часто бывает в Visual Studio. |
| 5 | |
| 6 | ## Принципы |
| 7 | |
| 8 | 1. **Git — нативно**, не «только терминал». Ежедневные операции — через UI IDE; CLI остаётся для редких или продвинутых сценариев. |
| 9 | 2. **Submodules — первоклассные**, не второстепенный сценарий. Репозитории вроде родителя `open` + вложенного `cascade-ide` должны быть **понятны с первого экрана**. |
| 10 | |
| 11 | ## Чего избегать (опыт VS) |
| 12 | |
| 13 | - Непонятно, **в каком репозитории** сейчас работа: корень vs каталог submodule. |
| 14 | - **Статус и diff** по submodule размазаны: не видно сразу «изменён gitlink / есть незакоммиченное внутри submodule / расхождение с remote». |
| 15 | - **Случайные полуоперации**: закоммитили родителя, забыли submodule (или наоборот), без явного предупреждения. |
| 16 | - **Инициализация и обновление** без ясных шагов: пустой или устаревший submodule ведёт к молчаливым сбоям сборки вместо понятного диалога. |
| 17 | |
| 18 | ## Целевое поведение (критерии приёмки) |
| 19 | |
| 20 | ### Единая картина |
| 21 | |
| 22 | - Видны **родительский репозиторий и все зарегистрированные submodules** (путь, имя, привязка из `.gitmodules`). |
| 23 | - Для каждого submodule отображаются по меньшей мере: **текущий commit/ветка**, признак **грязной рабочей копии**, **отставание/опережение** относительно записанного в родителе и/или remote (в терминах, понятных пользователю). |
| 24 | |
| 25 | ### Diff и коммит |
| 26 | |
| 27 | - Ясно разделено, что попадает в коммит **родителя** (в т.ч. обновление **gitlink**) и что коммитится **внутри submodule** (файлы). |
| 28 | - Стейджинг, просмотр diff, сообщение коммита — доступны для соответствующего контекста (корень / выбранный submodule), без путаницы. |
| 29 | |
| 30 | ### Безопасные действия |
| 31 | |
| 32 | - Явные операции: **обновить submodule до записанного в родителе**, **открыть каталог submodule как корень сессии** (или отдельное окно), **синхронизировать указатель в родителе** после коммита внутри submodule — с понятными подписями и при необходимости подтверждением. |
| 33 | |
| 34 | ### При открытии workspace |
| 35 | |
| 36 | - Если submodule **не инициализирован**, **не на том commit** или **есть расхождение с ожиданиями** — **понятное сообщение** и короткий путь действий (не молчаливый провал сборки). |
| 37 | |
| 38 | ## Связь с текущей реализацией |
| 39 | |
| 40 | - Сборка аргументов CLI для git в сценариях агента **централизована** в библиотеке `GitMcp.Core` (корень meta-repo `open`), общей для встроенных команд IDE и отдельного процесса git-mcp ([ADR 0019](adr/0019-shared-git-core-ide-and-git-mcp.md)). |
| 41 | - Сводка по git в полосе телеметрии и вызовы через MCP (`GitStatusAsync`, `GitDiffAsync`, `GitCommitAsync`, `GitPushAsync` и т.д.) задают **контракт для агента**. |
| 42 | - **Вкладка «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), мастера и подтверждения для редких команд (см. критерии выше). |
| 43 | |
| 44 | ## Версионирование документа |
| 45 | |
| 46 | - **v1** — зафиксированы принципы и критерии; по мере появления UI детали можно уточнять (имена панелей, MCP-тулов для submodule — отдельными дополнениями). |
| 47 | |
| 48 | ## Operational runbook |
| 49 | |
| 50 | - For recurring `AVLN2000` regressions caused by remote/submodule drift, use: |
| 51 | - `docs/setup/avln2000-submodule-sync-checklist.md` |
| 52 | |