7.11 Инструменты Git - Подмодули

Простейший вариант использования подмодулей в проекте состоит в том, что вы просто получаете сам подпроект и хотите периодически получать обновления, при этом в своей копии проекта ничего не изменяете. Давайте рассмотрим этот простой пример.

Если вы хотите проверить наличие изменений в подмодуле, перейдите в его каталог и выполните git fetch, а затем git merge для обновления локальной версии отслеживаемой ветки.

Теперь если вы вернётесь в основной проект и выполните git diff --submodule, то увидите, что подмодуль обновился, а так же список новых коммитов. Если вы не хотите каждый раз при вызове команды git diff указывать опцию --submodule, то задайте конфигурационному параметру diff.submodule значение «log» для использования такого формата вывода по умолчанию.

Если сейчас вы создадите коммит, то состояние подмодуля будет зафиксировано с учётом последних изменений, что позволит другим людям их получить.

Если вы не хотите вручную извлекать и сливать изменения в подкаталог, то для вас существует более простой способ сделать то же самое. Если вы выполните git submodule update --remote, то Git сам перейдёт в ваши подмодули, получит изменения и обновит их для вас.

Эта команда по умолчанию предполагает, что вы хотите обновить локальную копию до состояния ветки master из репозитория подмодуля. Однако, при желании вы можете задать другую ветку. Например, если вы хотите, чтобы подмодуль DbConnector отслеживал ветку stable, то можете указать это либо в файле .gitmodules (тогда и другие люди также будут отслеживать эту ветку), либо в вашем локальном файле .git/config. Давайте настроим это в файле .gitmodules:

Если опустить -f .gitmodules, то команда сделает изменения в локальном файле .git/config, но, вероятно, имеет смысл всё же отслеживать эту информацию в репозитории, так чтобы и все остальные участники имели к ней доступ.

Если сейчас выполнить команду git status, то Git покажет нам наличие «новых коммитов» в подмодуле.

Если установить в настройках параметр status.submodulesummary, то Git будет также отображать краткое резюме об изменениях в ваших подмодулях:

Если сейчас выполнить git diff, то увидите изменённый файл .gitmodules, а также наличие нескольких недавно полученных коммитов, которые готовы к включению в проект нашего подмодуля.

Здорово, что мы можем увидеть список подготовленных коммитов в нашем подмодуле. После создания коммита вы тоже можете получить эту информацию, выполнив команду git log -p.

При выполнении команды git submodule update --remote Git по умолчанию будет пытаться обновить все подмодули. Поэтому, при большом количестве подмодулей вы возможно захотите указать название только того подмодуля, который необходимо обновить.

Теперь давайте поставим себя на место нашего коллеги, у которого есть собственная копия репозитория MainProject. Простого запуска команды git pull для получения последних изменений уже недостаточно:

По умолчанию, команда git pull рекурсивно получает изменения для подмодулей, что можно увидеть выше в выводе первой команды. При этом, она не обновляет подмодули. Это отображается в выводе команды git status, которая показывает, что подмодуль изменён (modified) и содержит новые коммиты (new commits). Более того, новые коммиты обозначены символом «<», означающим, что эти коммиты добавлены в проект MainProject, но не извлечены в текущем состоянии подмодуля DbConnector. Для завершения обновления следует выполнить команду git submodule update:

На всякий случай, команду git submodule update лучше запускать с параметром --init, чтобы проинициализировать новые подмодули, которые, возможно, были добавлены в новых коммитах MainProject репозитория, а так же с параметром --recursive, чтобы обновить вложенные подмодули при их наличии.

Если вы хотите автоматизировать этот процесс, то добавьте параметр --recurse-submodules при запуске команды git pull (начиная с версии 2.14). Это приведёт к выполнению команды git submodule update сразу после получения и объединения изменений, приводя подмодули в корректное состояние. Более того, если вы хотите, чтобы Git всегда добавлял параметр --recurse-submodules к команде git pull, можно установить конфигурационный параметр submodule.recurse в значение true (работает для команды git pull начиная с версии 2.15). Если этот параметр конфигурации установлен, Git будет всегда добавлять --recurse-submodules ко всем командам, которые его поддерживают (кроме clone).

Существует специфическая ситуация, которая может возникнуть при получении изменений основного проекта: в одном из коммитов изменён URL подмодуля в файле .gitmodules. Такое может произойти, например, когда проект подмодуля переехал на другой хостинг. В таком случае команды git pull --recurse-submodules или git submodule update могут завершиться с ошибкой, потому как основной проект ссылается на коммит подмодуля, который не найден в удалённом репозитории этого подмодуля, на который указывает локальная конфигурация в основном репозитории. Чтобы исправить эту ситуацию требуется запуск команды git submodule sync:

Весьма вероятно, что вы используете подмодули, потому что хотите работать над кодом подмодуля (или нескольких подмодулей) во время работы над кодом основного проекта. Иначе бы вы, скорее всего, предпочли использовать более простую систему управления зависимостями (такую как Maven или Rubygems).

Давайте теперь рассмотрим пример, в котором мы одновременно с изменениями в основном проекте внесём изменения в подмодуль, зафиксировав и опубликовав все эти изменения в одно и то же время.

Ранее, когда мы выполняли команду git submodule update для извлечения изменений из репозитория подмодуля, Git получал изменения и обновлял файлы в поддиректории, но оставлял вложенный репозиторий в состоянии, называемом «отсоединённый HEAD» («detached HEAD»). Это значит, что локальная рабочая ветка (такая, например, как master), отслеживающая изменения, отсутствует. Отсутствие отслеживающей ветки означает, что даже если вы зафиксируете изменения в подмодуле, эти изменения, скорее всего, будут потеряны при следующем запуске git submodule update. Если хотите, чтобы изменения в подмодуле отслеживались, потребуется выполнить несколько дополнительных шагов.

Для подготовки репозитория подмодуля к такой работе с ним, нужно сделать две вещи. Нужно перейти в каждый подмодуль и извлечь ветку, в которой будете далее работать. Затем необходимо сообщить Git что ему делать, если вы внесли свои изменения, а затем получаете новые изменения из удалённого репозитория командой git submodule update --remote. Возможны два варианта — вы можете слить их в вашу локальную версию или попробовать перебазировать ваши локальные наработки поверх новых изменений.

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

Давайте попробуем обновить подмодуль путём слияния изменений. Для этого просто добавьте опцию --merge при вызове команды update. Ниже мы видим, что с удалённого сервера получен коммит для подмодуля и слит с текущим состоянием:

Перейдя в каталог DbConnector, можно увидеть, что новые изменения уже слиты в нашу локальную ветку stable. Теперь давайте посмотрим что происходит, когда мы вносим локальные изменения в библиотеку, а кто-то другой в то же время отправляет другие изменения в удалённый репозиторий.

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

Если вы забудете указать параметры --rebase или --merge, то Git просто обновит подмодуль до состояния репозитория на сервере и установит его в состояние отсоединённого HEAD.

Если такое происходит — не беспокойтесь, вы всегда можете перейти в каталог подмодуля, переключиться на вашу ветку (которая всё ещё будет содержать ваши наработки) и вручную слить ветку origin/stable или перебазировать свои изменения относительно неё (или любую другую удалённую ветку).

Если вы не зафиксировали ваши изменения в подмодуле и выполнили его обновление, то это приведёт к проблемам — Git получит изменения из удалённого репозитория, но не перезапишет несохранённые изменения в каталоге вашего подмодуля.

Если ваши локальные изменения в подмодуле конфликтуют с какими-либо изменениями в удалённом репозитории, то Git вам сообщит об этом при обновлении подмодуля.

Для разрешения конфликта вы можете перейти в каталог подмодуля и сделать это как вы бы делали в обычной ситуации.

Теперь у нас есть некоторые изменения в каталоге нашего подмодуля. Какие-то из них мы получили при обновлении из удалённого репозитория, а другие были сделаны локально и пока никому не доступны, так как мы их ещё никуда не отправили.

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

Чтобы гарантированно избежать такой проблемы, вы можете попросить Git проверять отправлены ли изменения всех подмодулей до отправки изменений основного репозитория на сервер. Команда git push принимает аргумент --recurse-submodules, который может принимать значения либо «check», либо «on-demand». Использование значения «check» приведёт к тому, что push просто завершится ошибкой, если какой-то из подмодулей не был отправлен на сервер.

Как видите, эта команда также даёт нам некоторые полезные советы о том, что мы могли бы делать дальше. Самый простой вариант — это пройти по всем подмодулям и вручную отправить изменения на удалённые серверы, чтобы гарантировать доступность изменений другим людям, а затем попытать отправить изменения снова. Если вы хотите использовать поведение “check” при каждом выполнении git push, то его можно установить поведением по умолчанию, выполнив команду git config push.recurseSubmodules check.

Другой вариант — это использовать значение «on-demand», тогда Git попытается сделать всё вышеописанное за вас.

Как видите, перед отправкой на сервер основного проекта Git перешёл в каталог модуля DbConnector и отправил его изменения на сервер. Отправка изменений основного репозитория также завершится неудачей если во время отправки изменений подмодуля возникла ошибка. Установить такое поведение по умолчанию можно с помощью команды git config push.recurseSubmodules on-demand.

Если вы измените ссылку на подмодуль одновременно с кем-то ещё, то вы можете столкнуться с некоторыми проблемами. Такое случается если истории подмодуля разошлись и они зафиксированы в разошедшихся ветках основного проекта, что может потребовать некоторых усилий для исправления.

Если один из коммитов является прямым предком другого (слияние может быть выполнено перемоткой вперёд), то Git просто выберет последний для выполнения слияния, то есть всё отработает хорошо.

Однако, Git не будет пытаться выполнить даже простейшего слияния. Если коммиты подмодуля разошлись и слияние необходимо, вы получите нечто подобное:

Здесь говорится о том, что Git понял, что в этих двух ветках содержатся указатели на разошедшиеся записи в истории подмодуля и их необходимо слить. Git поясняет это как «слияние последующих коммитов не найдено» («merge following commits not found»), что несколько обескураживает, но вскоре мы объясним почему так происходит.

Для решения этой проблемы, мы должны разобраться в каком состоянии должен находиться подмодуль. Странно, но Git не предоставляет вам для этого никакой вспомогательной информации, даже SHA-1 хешей коммитов разошедшихся веток истории. К счастью, получить эту информации довольно просто. Если выполнить команду git diff, то вы получите SHA-1 хеши коммитов обоих веток, которые вы пытаетесь слить.

В данном примере eb41d76 является нашим коммитом в подмодуле, а c771610 — коммитом из вышестоящего репозитория. Если мы перейдём в каталог нашего подмодуля, то он должен быть на коммите eb41d76, так как операция слияния его не изменяла. Если по каким-то причинам это не так, то вы можете просто создать новую ветку из этого коммита и извлечь её.

Куда более важным является SHA-1 хеш коммита второй ветки истории. Именно его мы должны будем слить и разрешить конфликты. Вы можете попытаться либо просто выполнить слияние, указав непосредственно этот SHA-1 хеш, либо создать из него отдельную ветку и слить её. Мы предлагаем использовать последний вариант, хотя бы только потому, что сообщение коммита слияния получается более читаемым.

Итак, перейдите в каталог нашего подмодуля, создайте ветку «try-merge» на основе второго SHA-1 хеша из git diff и выполните слияние вручную.

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

Это может немного запутать, но на самом деле здесь нет ничего сложного.

Интересно, что существует ещё один случай, с которым Git умеет работать. Если подмодуль содержит некий коммит слияния, который в своей истории содержит оба первоначальных коммита, то Git предложит его как возможное решение. Git видит, что в проекте подмодуля ветки, содержащие эти два коммита, уже когда-то кем-то сливались и этот коммит слияния, вероятно, именно то, что вам нужно.

Именно поэтому сообщение об ошибке выше было «merge following commits not found» — Git не мог найти такой коммит. Кто бы мог подумать, что Git пытается такое сделать?

Если Git нашёл только один приемлемый коммит слияния, то вы увидите нечто подобное:

Предлагаемая команда обновляет индекс таким же образом, как если бы вы выполнили git add (что очищает список конфликтов), а затем создали коммит. Хотя, наверное, вам не стоит так делать. Будет лучше просто перейти в каталог подмодуля, просмотреть изменения, сместить вашу ветку на этот коммит, должным образом всё протестировать и только потом создать коммит в основном репозитории.

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

Существует команда foreach, которая позволяет выполнить произвольную команду в каждом подмодуле. Это может быть, действительно, полезным если у вас в одном проекте присутствует большое количество подмодулей.

Для примера допустим, что мы хотим начать работу над какой-то новой функциональностью или исправить какую-то ошибку и наша работа затронет сразу несколько подмодулей. Мы можем легко припрятать все наработки во всех наших подмодулях.

Затем мы можем создать новую ветку и переключиться на неё во всех наших подмодулях.

Вы уловили идею. Ещё одна полезная вещь, которую можно сделать с помощью этой команды — создать комплексную дельту изменений основного проекта и всех подмодулей.

Здесь видно, что мы определили в подмодуле функцию и вызываем её в основном проекте. Это, конечно, упрощённый пример, но надеемся, что мы смогли донести до вас всю полезность этой функции.

Возможно, вы захотите настроить псевдонимы для некоторых из этих команд, так как они могут быть довольно длинными и для большинства из них вы не можете задать значения по умолчанию. Мы рассмотрели настройку псевдонимов Git в разделе Псевдонимы в Git главы 2, однако ниже приведён пример, который вы наверняка захотите использовать, если планируете часто работать с подмодулями Git.

Таким образом, для обновления подмодулей достаточно выполнить команду git supdate, а для отправки всех изменений с учётом подмодулей — команду git spush.

Например, переключение веток с подмодулями в них может оказаться довольно запутанным, особенно для версий Git старше 2.13. Если вы создадите новую ветку и добавите в ней подмодуль, а затем переключитесь обратно на ветку без подмодуля, то каталог подмодуля всё равно останется и будет неотслеживаемым:

Удалить каталог не сложно, но может показаться странным, что он вообще присутствует. Если удалить каталог и снова переключиться на ветку с подмодулем, то потребуется выполнить submodule update --init, чтобы в нём появились файлы.

Опять же, это не сильно сложно, но может немного сбивать с толку.

В более новых версиях (Git >= 2.13) всё несколько упрощено за счёт поддержки командой git checkout параметра --recurse-submodules, который отвечает за приведение подмодулей в состояние, соответствующее извлекаемой ветке.

Использование параметра --recurse-submodules команды git checkout помогает при работе с несколькими ветками основного проекта, когда в каждой из них используется разное состояние подмодуля. Действительно, если вы переключитесь между ветками, в которых зафиксированы разные состояния подмодуля, то команда git status отметит подмодуль как изменённый («modified») и покажет наличие новых коммитов в нём. Это происходит из-за того, что по умолчанию состояние подмодуля не изменяется при переключении веток.

Такое поведение может сильно сбивать с толку, поэтому рекомендуется всегда использовать git checkout --recurse-submodules если в вашем проекте есть подмодули. В более старых версиях Git, в которых команда git checkout не поддерживает параметр --recurse-submodules, для приведения подмодулей в ожидаемое состояние используйте команду git submodule update --init --recursive сразу после извлечения ветки.

К счастью, вы можете указать Git (начиная с версии 2.14) всегда использовать параметр --recurse-submodules с помощью изменения конфигурации: git config submodule.recurse true. Как упоминалось выше, это заставит Git автоматически добавлять параметр --recurse-submodules ко всем командам (кроме git clone), которые его поддерживают, и рекурсивно обрабатывать подмодули.

Другая большая проблема возникает при переходе от использования подкаталогов к использованию подмодулей. Если у вас были отслеживаемые файлы в вашем проекте и вы хотите переместить их в подмодуль, то вы должны быть осторожны, иначе Git будет ругаться на вас. Предположим, у вас есть файлы в каком-то каталоге вашего проекта и вы хотите переместить их в подмодуль. Если вы удалите подкаталог, а затем выполните submodule add, то Git ругнётся на вас:

Первым делом вы должны удалить каталог CryptoLibrary из индекса. Затем можно добавить подмодуль:

Предположим, что вы сделали это в какой-то ветке. Если вы попробуете переключиться обратно на ветку, в которой эти файлы всё ещё являются частью основного проекта, то вы получите ошибку:

Вы всё же можете извлечь ветку принудительно, используя команду checkout -f, только убедитесь перед этим в отсутствии несохранённых изменений, так как они могут быть перезаписаны.

Если вернуться обратно на предыдущую ветку, то по какой-то причине каталог CryptoLibrary будет пустым, а команда git submodule update не сможет это исправить. Чтобы вернуть свои файлы, вам понадобится перейти в каталог подмодуля и выполнить команду git checkout .. Можно использовать эту команду вместе с submodule foreach для извлечения сразу всех подмодулей.

Важно отметить, что в современных версиях Git подмодули сохраняют все служебные данные в каталоге .git основного проекта, поэтому, в отличие от более старых версий Git, удаление каталога подмодуля не приведёт к потере каких-либо коммитов или веток.

Все эти инструменты делают подмодули довольно простым и эффективным методом работы одновременно над несколькими тесно связанными, но разделёнными проектами.