Подмодули, поддеревья или вендоринг: три способа включить другой репозиторий

Что это такое

Три механизма помещают код из другого репозитория в ваш:

• Подмодуль. Дерево суперпроекта содержит запись gitlink с ID коммита, на котором следует находиться подмодулю, а .gitmodules хранит путь и URL. Подмодуль сохраняет собственную историю и каталог Git. Документация указывает, что после git submodule update записанный коммит извлекается с отсоединённым HEAD.
• Поддерево. git subtree add --prefix=<dir> <repository> <ref> импортирует файлы другого проекта в подкаталог как обычные отслеживаемые файлы; с --squash вместо всей истории импортируется только один коммит. git subtree pull и git subtree push перемещают изменения в обоих направлениях. Руководство подчёркивает, что поддеревьям не нужны специальные конструкции вроде .gitmodules или gitlink и они не вынуждают конечных пользователей что-либо делать.
• Вендоринг. Скопируйте файлы, включите их в коммит и запишите версию исходного проекта, URL источника и все локальные патчи в файл рядом с ними (VENDOR.md или файл фиксации версий).

Почему это важно

Выбор определяет вид свежего клона, способ обновления и возможность локальных изменений. Подмодули точны, но требуют от всех, включая CI, git clone --recurse-submodules или git submodule update --init --recursive; если забыть об этом, останутся пустые каталоги. Поддеревья и вендоринг дают самодостаточный клон ценой более объёмной истории и менее очевидного происхождения.

Как применять

• Предпочитайте менеджер пакетов, если для языка он существует; эти три способа предназначены для случаев, когда ни один не подходит (общая конфигурация, ресурсы, частный форк).
• Используйте подмодули, когда зависимость велика, изменяется независимо и должна быть закреплена на точном коммите, с которым вы также ведёте разработку.
• Используйте поддеревья, когда от потребителей не следует требовать знания о включённом репозитории, а обновления редки (git subtree pull --squash сохраняет короткую историю).
• Используйте вендоринг, когда зависимость мала и стабильна; укажите версию и лицензию, чтобы копию можно было проверить и обновить.
• При любом выборе поместите команду обновления в README и запускайте сборку из свежего клона в CI.

Подводные камни

Коммиты подмодуля, отправленные в суперпроект, но не в удалённый репозиторий подмодуля, ломают все остальные клоны. Коммиты, сделанные внутри подмодуля с отсоединённым HEAD, не принадлежат ни одной ветке, и их легко потерять, если сначала не создать ветку. Руководство по поддеревьям требует последовательности с --squash: если все слияния выполняются со сжатием, split --rejoin также необходимо выполнять со сжатием, иначе журнал покажет копию каждого коммита. Вендорные копии незаметно расходятся с исходником, когда кто-то вносит патчи, не обновляя запись о них.