Submodules, worktrees и sparse checkout

Submodule - это указатель из одного репозитория на конкретный коммит другого репозитория. Не копия, не зависимость в смысле пакетного менеджера, а именно «пиннинг» на SHA.

Внутри репо submodule выглядит как обычная директория, но в .gitmodules записан URL источника, а в индексе записан SHA коммита из этого источника:

[submodule "vendor/awesome"]

    path = vendor/awesome

    url = https://github.com/foo/awesome.git

Команды:

git submodule add https://github.com/foo/awesome vendor/awesome

git submodule init                    # инициализация (после clone)

git submodule update                  # подтянуть до SHA из индекса

git submodule update --remote         # подтянуть до HEAD upstream

git submodule deinit vendor/awesome   # деинициализировать

Типичный заход на свежем клоне:

git clone https://github.com/foo/bar

cd bar

# vendor/awesome пустая - нужно подтянуть

git submodule update --init --recursive

Или сразу при clone:

git clone --recursive https://github.com/foo/bar

Что физически записано

В индексе родительского репо vendor/awesome лежит как специальный объект «gitlink» - указатель на коммит SHA. Не tree, не blob, а ссылка на коммит. При git status ты видишь:

modified:   vendor/awesome (new commits)

Это значит: ты зашёл в submodule, сделал там что-то, теперь родительскому репо нужно обновить указатель.

Где submodules адекватны

• Вендоринг библиотеки, которая редко меняется. Пиннинг на конкретный SHA, защита от внезапного breaking change.
• Шаринг кода между несколькими проектами. Например, общий протобуф-пакет.
• Огромная third-party зависимость. Когда package manager слишком тяжёл (или его нет, например в C/C++).

Где submodules болят

• Каждая активная разработка. Если внутри submodule ты тоже часто коммитишь, цикл «обновить родительский указатель» - отдельная работа на каждое изменение.
• Сложность для новых разработчиков. Без --recursive репо просто не собирается, без объяснений где что.
• CI должен помнить про submodules. Без --recurse-submodules в pipeline - собирается пустота.
• Branch / submodule mismatch. Ветки родительского репо могут указывать на разные SHA submodule. При переключении ветки git submodule update нужен явно.

Полезный конфиг

# Автоматически обновлять submodules при checkout/pull

git config --global submodule.recurse true

# Показывать diff внутри submodule, не только «modified»

git config --global diff.submodule log

С этими настройками submodules ведут себя ощутимо менее агрессивно.

Подводный камень: detached HEAD внутри submodule

git submodule update делает checkout по SHA, не по ветке. Внутри submodule у тебя detached HEAD (см. detached-head). Если ты там что-то коммитишь, не переключаясь на ветку - твои коммиты висят на отдельном указателе, и при следующем git submodule update их можно потерять.

Правильный цикл «изменить код внутри submodule»:

cd vendor/awesome

git switch -c fix/x      # выйти из detached, создать ветку

# ... правки ...

git commit -am "fix"

git push

cd ..

git add vendor/awesome   # обновить указатель в родителе

git commit -m "bump awesome"

Submodule - не единственный способ держать несколько кодовых баз вместе. Альтернативы:

git subtree

Subtree копирует содержимое одного репо внутрь другого как обычные файлы. Без gitlink, без .gitmodules. Внешне это выглядит как обычная директория, и git clone тащит её целиком, без отдельной команды.

git subtree add --prefix=vendor/awesome https://github.com/foo/awesome main --squash

git subtree pull --prefix=vendor/awesome https://github.com/foo/awesome main --squash

Плюсы:

• Новый разработчик клонирует и сразу всё на месте.
• CI не нужно знать про submodule.
• Можно править файлы внутри, и они не теряются.

Минусы:

• Каждый pull увеличивает размер репо (история копируется).
• Команды длинные, легко забыть --prefix.
• Чтобы отправить изменения обратно в upstream - отдельная процедура git subtree push.

Subtree подходит для разового вендоринга, когда дальнейшие обновления редки. Если планируется регулярный sync - subtree становится утомительным.

Monorepo

Альтернативный подход: отказаться от идеи «несколько репо», положить всё в один. Все приложения, все библиотеки, общие зависимости - в одном дереве.

monorepo/

  apps/

    web/

    mobile/

    api/

  libs/

    auth/

    utils/

    models/

  tools/

    deploy/

    ci/

Плюсы:

• Один clone, всё на месте.
• Refactoring через всё дерево - атомарный коммит.
• Никакого pinning'а - все приложения видят актуальные библиотеки.

Минусы:

• Требует системы сборки, понимающей зависимости (Bazel, Nx, Turborepo, Pants).
• Репо растёт быстро. Часто > гигабайта.
• CI должен выбирать, что собирать (incremental builds), иначе каждое изменение запускает всю сборку.

Monorepo выбирают большие компании (Google, Meta, Stripe) и многие фронтенд-команды (Nx-based). Mid-size команды чаще сидят на multi-repo. Это политическое решение, не техническое - и часто принимается «потому что у Google monorepo», что плохой аргумент.

Сравнение

Правило большого пальца: submodules - для read-only зависимостей. Для активного кода - monorepo или multi-repo с package manager'ом.

Обычно у репозитория одно working tree - одна директория с файлами, которая отражает HEAD. Чтобы посмотреть другую ветку - git switch, и working tree переключается.

Это раздражает, когда нужно одновременно работать с двумя ветками. Типичный сценарий: ты пишешь фичу в feat/x, прилетает срочный hotfix-запрос на main. Варианты:

• Stash текущие изменения, переключиться на main, починить, вернуться, unstash. Работает, но контекст рассыпается.
• Клонировать репо ещё раз в другую директорию - оверхед на clone, две .git/ директории на диск.
• Worktree - несколько working tree из одного .git/.

git worktree add ../bar-hotfix main

# создаёт ../bar-hotfix с checkout main

Что произошло: в ../bar-hotfix появилась полная working copy, как будто это отдельный клон. Но .git/ шарится с основной директорией - никакого второго fetch'а, никакого дублирования объектов.

В этой директории ты делаешь hotfix, коммитишь, пушишь, как обычно. В основной директории всё это время продолжается работа в feat/x - без переключения.

Когда закончил - удалить worktree:

git worktree remove ../bar-hotfix

# либо просто rm -rf, если внутри ничего не сохраняется

Список worktree

git worktree list

# /path/to/main         abc123 [feat/x]

# /path/to/bar-hotfix   def456 [main]

Видно, какие directories связаны с какими ветками.

Ограничения

• Одна ветка - одна worktree. Нельзя checkout одну и ту же ветку в двух worktree одновременно. Git защищается от двух одновременных коммитов на одну ветку.
• Не для submodules-сценариев. Submodules внутри worktree работают, но с нюансами; лучше избегать.
• git worktree remove отказывается с грязными изменениями. Либо commit/stash, либо --force.

Когда worktree оправданы

• Hotfix во время фича-работы.
• Сравнение поведения двух веток вживую (запустить обе одновременно).
• Долгий тест на одной ветке, продолжение работы на другой.
• Code review большой ветки в отдельной директории, чтобы IDE не мешалась.

В commercial-проектах worktree часто недооценён. В большом проекте, где ребилд занимает 5 минут, два рабочих копии могут экономить десятки минут в день.

.git/ шарится между worktrees, но reflog и некоторые refs - per-worktree:

.git/

  HEAD                  ← per-worktree (main worktree)

  worktrees/

    bar-hotfix/

      HEAD              ← per-worktree (hotfix worktree)

      index

      logs/

Это значит:

• HEAD в основной директории != HEAD в hotfix.
• git stash в одной не видит stash другой (stash хранится в per-worktree-refs).
• reflog HEAD в одной не показывает события другой.

Эти изоляции по большей части незаметны, но иногда удивляют. Когда «не нахожу stash в новом worktree» - это потому, что он на самом деле в старом.

Sparse checkout управляет тем, какие файлы Git кладёт в рабочее дерево. По умолчанию sparse checkout сам по себе не уменьшает то, что качается с remote, - чтобы не тащить blob'ы всего репо, его комбинируют с partial clone (--filter=blob:none, см. ниже). Полезно, когда репо большое (монорепо), а нужна только конкретная директория.

Включение:

git clone --filter=blob:none --no-checkout https://github.com/foo/monorepo

cd monorepo

git sparse-checkout init --cone

git sparse-checkout set apps/web libs/auth

git checkout main

После этого в рабочем каталоге будут только apps/web/* и libs/auth/*. Файлы из apps/mobile/, libs/utils/ и т.д. физически не на диске - только в .git/objects/. Это экономит место и время первого checkout.

--cone - режим, в котором sparse-checkout работает быстро на больших репах (по директориям, не по файловым паттернам). --no-cone (старый) поддерживает gitignore-style patterns, но медленнее.

Когда полезен

• Монорепо. Frontend-команда работает только с apps/web и несколькими libs/. Sparse checkout убирает остальное с диска.
• Очень большие репозитории. Linux kernel клонируется целиком ~3 GB; если нужна только определённая поддерева драйверов - sparse сокращает до сотен MB.
• CI на одну часть. Если в pipeline проверяется только frontend/, sparse checkout сокращает время clone в разы.

Ограничения

• Не для всех команд прозрачно. git log показывает всю историю (как и должен), но если кто-то спросит «покажи мне изменения в файле X» - а файл вне sparse, тебе нужно расширить sparse, чтобы увидеть его.
• Не «virtualизация», как Git LFS или VFS. Файлы или есть на диске, или нет; чтобы получить - нужно поменять sparse-set.

Partial clone

Sparse checkout + --filter=blob:none (partial clone) - мощная пара. Partial clone не качает blob'ы (содержимое файлов) до checkout. Sparse checkout говорит, какие blob'ы понадобятся. Вместе - clone в несколько раз быстрее на больших репах.

Поддерживается Git 2.25+. На GitHub partial clone работает, sparse checkout - локальная команда, не требует поддержки сервера.

Шпаргалка для типичных сценариев:

Что НЕ делать

• Не использовать submodule «потому что коллеги их видели». Это специфический инструмент, не общая практика. Если ты не уверен - скорее всего, не нужны.
• Не лечить submodule-боль ещё более глубокими submodule. Если submodule болит, рассмотри subtree или monorepo.
• Не делать worktree «временно навсегда». Через год у тебя в директории-сестре старый код, на котором не сделан pull полгода. Удаляй worktree после задачи.
• Не путать sparse checkout с .gitignore. .gitignore не даёт Git'у видеть файлы. Sparse checkout говорит, какие из видимых файлов класть на диск. Это разные слои.