Как превратить директорию в Git‑субмодуль: полное руководство

Быстрые ссылки

• Что такое субмодуль в Git?

• Как превратить директорию в субмодуль

• Добавление нового субмодуля

Что такое субмодуль в Git?

Субмодуль — это Git‑репозиторий, вложенный в другой Git‑репозиторий. Это позволяет включать код стороннего проекта как зависимость, сохраняя при этом отдельную систему контроля версий для этого кода.

Когда вы клонируете родительский репозиторий, субмодули обычно тоже клонируются (или инициализируются) отдельными командами. История коммитов субмодуля хранится отдельно от истории основного проекта. Благодаря этому один и тот же библиотечный репозиторий можно подключать к нескольким проектам и обновлять его централизованно.

Альтернатива субмодулям — публиковать библиотеки как пакеты в менеджеры пакетов (npm, Maven, NuGet и пр.). Это удобно для распространённых библиотек, но не всегда применимо для приватного кода: потребуется частный реестр пакетов и дополнительные настройки аутентификации. Субмодули проще, когда нужно включить исходники напрямую.

Важно: Git ожидает, что субмодуль — это отдельный репозиторий. Простое перемещение файлов в папку и попытка «превратить» её в субмодуль без переноса истории приведёт к потере истории изменений для этой части кода.

Как превратить директорию в субмодуль

Ниже — пошаговый рабочий процесс. Он минимизирует потерю истории и помогает корректно вынести директорию в отдельный репозиторий.

1. Создайте новый репозиторий для субмодуля. Обычно это удалённый репозиторий на GitHub/GitLab/Bitbucket, но можно начать и с локального репозитория.

2. Получите свежую копию главного репозитория. Работайте с копией, чтобы не повредить основной код.

git clone git@github.com:username/repository.git submodule-repo

cd submodule-repo

3. Отфильтруйте историю так, чтобы остались только коммиты, относящиеся к нужной директории. Это удалит все коммиты, не связанные с содержимым директории. Операция разрушительная — выполняйте её только в копии репозитория.

git filter-branch --subdirectory-filter submoduledirectory -- --all

Результат: в рабочей копии останется только код директории и только связанные с ним коммиты. Таким образом вы перенесёте историю изменений этой директории в отдельный репозиторий.

4. Измените URL удалённого репозитория на URL вашего нового репозитория (обычно remote называется origin).

git remote set-url origin https://github.com/new-repository.git

5. Запушьте историю в новый репозиторий.

git push -u origin main

После этого у вас будет полноценный репозиторий субмодуля с историей.

Добавление нового субмодуля в родительский проект

Теперь, когда у вас есть отдельный репозиторий для модуля, можно подключить его к родительскому проекту.

1. В родительском репозитории прекратите трекинг директории, которую хотите превратить в субмодуль. Файлы могут оставаться в истории Git, но вы удаляете их из рабочей копии, чтобы заново добавить как субмодуль.

rm -rf directory_name

2. Добавьте субмодуль, указав URL удалённого репозитория и путь, где должен находиться модуль.

git submodule add git@github.com:username/repository.git directory_name

Эта команда создаст в родительском репозитории ссылку на конкретный коммит субмодуля и клонирует репозиторий субмодуля в указанную папку.

3. Обновление субмодуля при необходимости:

git submodule update --remote submodule_name

Команда подтянет последние коммиты из указанной ветки субмодуля и обновит ссылку в родительском репозитории.

Практические советы и частые ошибки

• Всегда делайте резервную копию (клонирование) родительского репозитория перед фильтрацией истории.
• Убедитесь, что вы сохранили все права доступа и CI/CD‑конфигурации для нового репозитория субмодуля.
• Если в истории есть большие бинарные файлы, подумайте об их обработке (git lfs) перед фильтрацией.
• Настройте README и лицензии для нового репозитория, чтобы потребители понимали, как использовать модуль.

Когда это не подходит

• Если модуль используется как библиотека в множестве проектов и нужен менеджер зависимостей с версионированием (semver), лучше опубликовать пакет в реестр.
• Для частых мелких изменений, которые должны сразу синхронизироваться с родителем, субмодули добавляют сложность управления версиями — рассмотрите моно‑репозиторий.

Альтернативные подходы

• Пакетный менеджер (npm, Maven, NuGet) — чистая модель версий и распространения.
• Git subtree — проще по UX (менеджер изменений в одной истории) и не требует отдельного репозитория, но история смешана.
• Монорепозиторий — единая история и единый CI, но требует процессов для отдельных компонент.

Пошаговый SOP для переноса директории в субмодуль

1. Клонируйте основной репозиторий в отдельную папку.
2. Выполните git filter‑branch или используйте git filter-repo (рекомендуется для больших репозиториев).
3. Подготовьте новый внешний репозиторий и настройте remote.
4. Запушьте историю в новый репозиторий.
5. В основном проекте удалите локальную директорию и выполните git submodule add.
6. Обновите документацию и CI/CD конфигурации.
7. Протестируйте сборку и интеграционные тесты.

Критерии приёмки

• В новом репозитории присутствует история коммитов только по нужной директории.
• Субмодуль корректно клонируется и компилируется в контексте родительского проекта.
• CI/CD пропускает сборку с новым модулем.
• Документация обновлена (README, инструкции по разработке).

Чек-лист ролей

• Разработчик: подготовил фильтр истории, проверил локально сборку.
• DevOps/Release: настроил доступы к новому репозиторию, обновил CI/CD.
• Тестировщик: прогнал интеграционные тесты и проверил поведение при обновлении субмодуля.
• Менеджер: подтвердил, что архитектурная причина для выделения модуля оправдана.

Решение в виде схемы (простой flowchart)

flowchart TD
  A[Начало] --> B{Есть ли необходимость сохранить историю?}
  B -- Да --> C[Клонировать репозиторий]
  C --> D[Отфильтровать директорию]
  D --> E[Создать новый репозиторий]
  E --> F[Запушить историю]
  F --> G[В родительском репо удалить директорию]
  G --> H[git submodule add]
  H --> I[Проверить сборку и CI]
  B -- Нет --> J[Рассмотреть пакетный менеджер или mono-repo]
  I --> K[Готово]

Краткая глоссарий

• Субмодуль: отдельный Git‑репозиторий, подключённый к другому репозиторию.
• git filter-branch: инструмент для переписывания истории (может быть медленным; для больших репо используйте git filter-repo).
• origin: стандартное имя удалённого репозитория.

Альтернативы и когда они лучше

• git subtree: проще объединять историю и синхронизировать изменения без отдельного репозитория.
• Публичный или приватный пакет: если нужен версионируемый артефакт и распространение через менеджер пакетов.

Заключение

Выделение директории в отдельный Git‑субмодуль помогает сохранить историю и упростить повторное использование кода. Выполняйте операции фильтрации только в копии репозитория, обновляйте CI и права доступа и выбирайте подходящий подход — субмодуль, subtree или пакетный менеджер — исходя из требований к версии и распространению.

Важно: для больших репозиториев рассмотрите git filter-repo как более быстрый и безопасный инструмент по сравнению с git filter-branch.