Подмодули (Submodules)¶
Подмодули позволяют включать другие Git-репозитории в качестве подпапок вашего проекта. Это полезно, когда нужно использовать внешнюю библиотеку или общий код, который развивается отдельно.
Что такое подмодуль?¶
Подмодуль — это ссылка на конкретный коммит другого репозитория. Ваш основной проект хранит только информацию о том, какой именно коммит подмодуля использовать, а не весь его код напрямую.
Добавление подмодуля¶
Добавить новый подмодуль¶
git submodule add <URL-репозитория> [путь/к/папке]
Пример:
git submodule add https://github.com/library/utils.git libs/utils
Git:
1. Клонирует репозиторий в указанную папку.
2. Создает файл .gitmodules с информацией о подмодуле.
3. Добавляет запись в индекс основного репозитория.
После этого нужно сделать коммит:
git commit -m "Добавить подмодуль utils"
Просмотр подмодулей¶
# Список подмодулей
git submodule
# Статус подмодулей (показывает текущий коммит)
git submodule status
# Подробная информация
git submodule foreach 'echo $name'
Клонирование проекта с подмодулями¶
При клонировании¶
git clone --recursive <URL-проекта>
Флаг --recursive автоматически инициализирует и обновит все подмодули.
Если уже склонировали без подмодулей¶
# Инициализировать подмодули
git submodule init
# Скачать их содержимое
git submodule update
Или одной командой:
git submodule update --init --recursive
Работа с подмодулями¶
Обновление подмодуля до последней версии¶
Перейдите в папку подмодуля и сделайте pull:
cd libs/utils
git pull origin main
cd ../..
Затем зафиксируйте новый коммит подмодуля в основном проекте:
git add libs/utils
git commit -m "Обновить подмодуль utils"
Обновление всех подмодулей сразу¶
git submodule update --remote
Обновит все подмодули до последних коммитов их веток по умолчанию.
Чтобы сразу добавить изменения в индекс:
git submodule update --remote --merge
Изменение ветки подмодуля¶
По умолчанию подмодуль отслеживает конкретный коммит. Можно настроить отслеживание ветки:
-
Отредактируйте
.gitmodules:text [submodule "libs/utils"] path = libs/utils url = https://github.com/library/utils.git branch = main -
Примените изменения:
bash git submodule sync git submodule update --remote
Удаление подмодуля¶
Удаление подмодуля — многоступенчатый процесс (в старых версиях Git):
# 1. Деинициализировать
git submodule deinit libs/utils
# 2. Удалить из .git/modules
rm -rf .git/modules/libs/utils
# 3. Удалить из индекса и рабочей папки
git rm -f libs/utils
# 4. Удалить запись из .gitmodules (вручную или через sed)
git add .gitmodules
git commit -m "Удалить подмодуль utils"
В новых версиях Git (2.34+) достаточно:
git rm libs/utils
git commit -m "Удалить подмодуль utils"
Частые проблемы¶
Подмодуль показывает изменения, которых нет¶
Проверьте, не забыли ли вы закоммитить изменения в самом подмодуле:
cd libs/utils
git status
Конфликты при слиянии с изменением подмодуля¶
Если в разных ветках обновили подмодуль на разные коммиты, возникнет конфликт. Разрешите его, выбрав нужный коммит:
git submodule update --init
Медленное обновление подмодулей¶
Для ускорения можно использовать параллельное обновление:
git submodule update --init --recursive --jobs 8
Альтернативы подмодулям¶
- Git Subtrees: Встраивают код другого репозитория прямо в ваш проект (без отдельной папки .git). Проще в использовании, но сложнее синхронизировать изменения обратно.
- Менеджеры пакетов: Для библиотек лучше использовать npm, pip, Maven и т.д.
- Monorepo: Хранить весь код в одном большом репозитории.
Когда использовать подмодули?¶
✅ Подходит: - Зависимость от внешнего проекта, который развивается отдельно. - Нужно точно контролировать версию используемого кода. - Код подмодуля используется в нескольких проектах.
❌ Не подходит: - Для простых библиотек (лучше менеджеры пакетов). - Если команда не знакома с работой подмодулей (высокий порог входа). - Для часто меняющегося общего кода (лучше monorepo).