Русский ▾ Topics ▾ Latest version ▾ git-submodule last updated in 2.54.0

НАЗВАНИЕ

git-submodule - Инициализация, обновление или проверка подмодулей

ОБЗОР

git submodule [--quiet] [--cached]
git submodule [--quiet] add [<параметры>] [--] <репозиторий> [<путь>]
git submodule [--quiet] status [--cached] [--recursive] [--] [<путь>…​]
git submodule [--quiet] init [--] [<путь>…​]
git submodule [--quiet] deinit [-f|--force] (--all|[--] <путь>...)
git submodule [--quiet] update [<параметры>] [--] [<путь>…​]
git submodule [--quiet] set-branch [<параметры>] [--] <путь>
git submodule [--quiet] set-url [--] <путь> <новый-url>
git submodule [--quiet] summary [<параметры>] [--] [<путь>…​]
git submodule [--quiet] foreach [--recursive] <команда>
git submodule [--quiet] sync [--recursive] [--] [<путь>…​]
git submodule [--quiet] absorbgitdirs [--] [<путь>…​]

ОПИСАНИЕ

Проверяет, обновляет и управляет подмодулями.

Дополнительную информацию о подмодулях см. в gitsubmodules[7].

КОМАНДЫ

Без аргументов показывает состояние существующих подмодулей. Доступно несколько подкоманд для выполнения операций с подмодулями.

add [-b <ветка>] [-f | --force] [--name <имя>] [--reference <репозиторий>] [--ref-format <формат>] [--depth <глубина>] [--] <репозиторий> [<путь>]

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

<репозиторий> — это URL репозитория origin нового подмодуля. Это может быть либо абсолютный URL, либо (если он начинается с ./ или ../) расположение относительно внешнего репозитория суперпроекта по умолчанию (Обратите внимание, что для указания репозитория foo.git, который находится прямо рядом с суперпроектом bar.git, вам придётся использовать ../foo.git вместо ./foo.git — как можно было бы ожидать, следуя правилам для относительных URL-адресов — потому что вычисление относительных URL-адресов в Git идентично вычислению относительных каталогов).

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

Необязательный аргумент <путь> — это относительное расположение клонированного подмодуля в суперпроекте. Если <путь> не указан, используется каноническая часть исходного репозитория (repo для /путь/к/repo.git и foo для host.xz:foo/.git). Если <путь> существует и уже является допустимым репозиторием Git, то он индексируется для фиксации без клонирования. <путь> также используется как логическое имя подмодуля в его записях конфигурации, если только --name <имя> не используется для указания логического имени.

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

Если задан параметр --ref-format <формат>, формат хранения ссылок для подмодулей, которую будут клонированы впервые, будет установлен в соответствующее значение.

status [--cached] [--recursive] [--] [<путь>...]

Показывает состояние подмодулей. Выводит SHA-1 текущего переключённого коммита для каждого подмодуля, а также путь подмодуля и вывод git-describe[1] для SHA-1. Каждый SHA-1 может иметь префикс -, если подмодуль не инициализирован, +, если текущий переключённый коммит подмодуля не совпадает с SHA-1, найденным в индексе содержащего репозитория, и U, если подмодуль имеет конфликты слияния.

Если указан --cached, эта команда вместо этого выведет SHA-1, записанный в суперпроекте для каждого подмодуля.

Если указан --recursive, эта команда рекурсивно обработает вложенные подмодули и также покажет их состояние.

Если вас интересуют только изменения текущих инициализированных подмодулей относительно коммита, записанного в индексе или HEAD, git-status[1] и git-diff[1] также предоставят эту информацию (и могут также сообщать об изменениях в рабочем каталоге подмодуля).

init [--] [<путь>...]

Инициализирует подмодули, записанные в индексе (которые были добавлены и закоммичены в другом месте), устанавливая submodule.$имя.url в .git/config, используя ту же настройку из .gitmodules в качестве шаблона. Если URL относительный, он будет разрешён с использованием внешнего репозитория по умолчанию. Если внешнего репозитория по умолчанию нет, предполагается, что текущий репозиторий является вышестоящим.

Необязательные аргументы <путь> ограничивают, какие подмодули будут инициализированы. Если путь не указан и submodule.active настроен, будут инициализированы подмодули, настроенные как активные, в противном случае инициализируются все подмодули.

Он также скопирует значение submodule.$имя.update, если оно присутствует в файле .gitmodules, в .git/config, но (1) эта команда не изменяет существующую информацию в .git/config, и (2) submodule.$имя.update, установленное в пользовательскую команду, не копируется по соображениям безопасности.

Затем вы можете настроить URL-адреса клонирования подмодулей в .git/config для вашей локальной настройки и перейти к git submodule update; вы также можете просто использовать git submodule update --init без явного шага init, если не собираетесь настраивать какие-либо расположения подмодулей.

Определение внешнего репозитория по умолчанию см. в подкоманде add.

deinit [-f | --force] (--all|[--] <путь>...)

Отменяет регистрацию указанных подмодулей, т.е. удаляет весь раздел submodule.$имя из .git/config вместе с их рабочим каталогом. Последующие вызовы git submodule update, git submodule foreach и git submodule sync будут пропускать любые незарегистрированные подмодули, пока они не будут инициализированы снова, поэтому используйте эту команду, если вы больше не хотите иметь локальное переключение подмодуля в вашем рабочем каталоге.

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

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

Если вы действительно хотите удалить подмодуль из репозитория и зафиксировать это, используйте вместо этого git-rm[1]. Варианты удаления см. в gitsubmodules[7].

update [--init] [--remote] [-N | --no-fetch] [--[no-]recommend-shallow] [-f | --force] [--checkout | --rebase | --merge] [--reference=<репозиторий>] [--ref-format=<формат>] [--depth=<глубина>] [--recursive] [--jobs <число>] [--[no-]single-branch] [--filter=<спецификатор-фильтра>] [--] [<путь>...]

Обновляет зарегистрированные подмодули в соответствии с ожиданиями суперпроекта путём клонирования отсутствующих подмодулей, получения отсутствующих коммитов в подмодулях и обновления рабочего каталога подмодулей. "Обновление" может быть выполнено несколькими способами в зависимости от параметров командной строки и значения переменной конфигурации submodule.<имя>.update. Параметр командной строки имеет приоритет над переменной конфигурации. Если ни то, ни другое не указано, выполняется checkout. (примечание: то, что находится в файле .gitmodules, на данном этапе не имеет значения; см. git submodule init выше о том, как используется .gitmodules). Процедуры update, поддерживаемые как из командной строки, так и через конфигурацию submodule.<имя>.update:

checkout

коммит, записанный в суперпроекте, будет переключён в подмодуле на отсоединённом HEAD.

Если указан --force, подмодуль будет переключён (с использованием git checkout --force), даже если коммит, указанный в индексе содержащего репозитория, уже соответствует коммиту, переключённому в подмодуле.

rebase

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

merge

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

У следующих процедур обновления есть дополнительные ограничения:

!<пользовательская-команда>

механизм для выполнения произвольных команд с идентификатором коммита в качестве аргумента. В частности, если переменная конфигурации submodule.<имя>.update установлена в !<пользовательская-команда>, имя объекта коммита, записанного в суперпроекте для подмодуля, добавляется к строке <пользовательская-команда> и выполняется. Обратите внимание, что этот механизм не поддерживается в файле .gitmodules или в командной строке.

none

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

Если подмодуль ещё не инициализирован, и вы просто хотите использовать настройку, сохранённую в .gitmodules, вы можете автоматически инициализировать подмодуль с помощью параметра --init.

Если указан --recursive, эта команда рекурсивно обработает зарегистрированные подмодули и обновит любые вложенные подмодули внутри них.

Если задан параметр --ref-format <формат>, формат хранения ссылок для подмодулей, которую будут клонированы впервые, будет установлен в соответствующее значение.

Если указан --filter <спецификатор-фильтра>, указанный фильтр частичного клона будет применён к подмодулю. Подробности о спецификациях фильтров см. в git-rev-list[1].

set-branch (-b|--branch) <ветка> [--] <путь>
set-branch (-d|--default) [--] <путь>

Устанавливает ветку отслеживания внешнего репозитория по умолчанию для подмодуля. Параметр --branch позволяет указать внешнюю ветку. Параметр --default удаляет ключ конфигурации submodule.<имя>.branch, что приводит к тому, что ветка отслеживания по умолчанию становится внешним HEAD.

set-url [--] <путь> <новый-url>

Устанавливает URL указанного подмодуля в <новый-url>. Затем он автоматически синхронизирует новую конфигурацию URL внешнего репозитория подмодуля.

summary [--cached | --files] [(-n|--summary-limit) <число>] [коммит] [--] [<путь>...]

Показывает сводку коммитов между указанным коммитом (по умолчанию HEAD) и рабочим каталогом/индексом. Для рассматриваемого подмодуля показывается серия коммитов в подмодуле между указанным коммитом суперпроекта и индексом или рабочим каталогом (переключается с помощью --cached). Если указан параметр --files, показывается серия коммитов в подмодуле между индексом суперпроекта и рабочим каталогом подмодуля (этот параметр не позволяет использовать параметр --cached или указывать явный коммит).

Использование параметра --submodule=log с git-diff[1] также предоставит эту информацию.

foreach [--recursive] <команда>

Выполняет произвольную команду оболочки <команда> в каждом переключённом подмодуле. Команда имеет доступ к переменным $name, $sm_path, $displaypath, $sha1 и $toplevel:

$name

имя соответствующего раздела подмодуля в .gitmodules

$sm_path

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

$displaypath

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

$sha1

коммит, записанный в непосредственном суперпроекте

$toplevel

абсолютный путь к верхнему уровню непосредственного суперпроекта.

Обратите внимание, что во избежание конфликтов с $PATH в Windows переменная $path теперь является устаревшим синонимом переменной $sm_path. Любые подмодули, определённые в суперпроекте, но не переключённые, игнорируются этой командой. Если не указан --quiet, foreach выводит имя каждого подмодуля перед выполнением команды. Если указан --recursive, подмодули обрабатываются рекурсивно (т.е. указанная команда оболочки также выполняется во вложенных подмодулях). Ненулевой возврат команды в любом подмодуле приводит к прекращению обработки. Это можно переопределить, добавив ||: в конец команды.

Например, следующая команда покажет путь и текущий переключённый коммит для каждого подмодуля:

git submodule foreach 'echo $sm_path `git rev-parse HEAD`'
sync [--recursive] [--] [<путь>...]

Синхронизирует настройку URL внешнего репозитория подмодулей со значением, указанным в .gitmodules. Это повлияет только на те подмодули, которые уже имеют запись URL в .git/config (это имеет место, когда они инициализированы или только что добавлены). Это полезно, когда URL-адреса подмодулей изменяются вышестоящей веткой, и вам необходимо соответствующим образом обновить ваши локальные репозитории.

git submodule sync синхронизирует все подмодули, в то время как git submodule sync -- A синхронизирует только подмодуль A.

Если указан --recursive, эта команда рекурсивно обработает зарегистрированные подмодули и синхронизирует любые вложенные подмодули внутри них.

absorbgitdirs

Если git-каталог подмодуля находится внутри подмодуля, перемещает git-каталог подмодуля в путь $GIT_DIR/modules его суперпроекта, а затем соединяет git-каталог и его рабочий каталог, устанавливая core.worktree и добавляя файл .git, указывающий на git-каталог, встроенный в git-каталог суперпроекта.

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

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

ПАРАМЕТРЫ

-q
--quiet

Выводить только сообщения об ошибках.

--progress

Прогресс по умолчанию направляется в стандартный поток ошибок, если этот поток подключён к терминалу, если не указан параметр -q. Этот флаг принудительно включает отображение прогресса, даже если стандартный поток ошибок не направлен на терминал. Он действителен только для команд add и update.

--all

Отменить регистрацию всех подмодулей в рабочем каталоге. Этот параметр действителен только для команды deinit.

-b<ветка>
--branch=<ветка>

Ветка репозитория для добавления в качестве подмодуля. Имя ветки записывается как submodule.<имя>.branch в .gitmodules для update --remote. Специальное значение . используется для указания того, что имя ветки в подмодуле должно совпадать с именем текущей ветки в текущем репозитории. Если параметр не указан, по умолчанию используется внешний HEAD.

-f
--force

Заставляет команду продолжить выполнение, даже если в противном случае она завершилась бы ошибкой. Этот параметр действителен только для команд add, deinit и update.

add

разрешить добавление иначе игнорируемого пути подмодуля. Этот параметр также используется для обхода проверки того, что имя подмодуля ещё не используется. По умолчанию git submodule add завершится ошибкой, если предлагаемое имя (которое получено из пути) уже зарегистрировано для другого подмодуля в репозитории. Использование --force позволяет команде продолжить работу, автоматически генерируя уникальное имя путём добавления номера к конфликтующему имени (например, если существует подмодуль с именем child, он попробует child1 и так далее).

deinit

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

update

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

--cached

Использовать индекс для определения коммита вместо HEAD. Этот параметр действителен только для команд status и summary.

--files

Заставляет команду summary сравнивать коммит в индексе с коммитом в HEAD подмодуля.

-n<n>
--summary-limit=<n>

Ограничивает размер summary (общее количество показываемых коммитов) до <число>. Значение 0 отключает сводку; отрицательное число означает неограниченно (по умолчанию). Это ограничение применяется только к изменённым подмодулям. Для добавленных/удалённых/изменивших тип подмодулей размер всегда ограничен 1.

--remote

Вместо использования записанного SHA-1 суперпроекта для обновления подмодуля использовать состояние отслеживаемой внешней ветки подмодуля. Этот параметр действителен только для команды update. Используемый внешний репозиторий — это внешний репозиторий ветки (branch.<имя>.remote), по умолчанию origin. Используемая внешняя ветка по умолчанию — внешний HEAD, но имя ветки может быть переопределено установкой параметра submodule.<имя>.branch либо в .gitmodules, либо в .git/config (при этом .git/config имеет приоритет).

Это работает для любой из поддерживаемых процедур обновления (--checkout, --rebase и т.д.). Единственное изменение — это источник целевого SHA-1. Например, submodule update --remote --merge сольёт вышестоящие изменения подмодуля в подмодули, в то время как submodule update --merge сольёт изменения gitlink суперпроекта в подмодули.

Чтобы гарантировать актуальное состояние ветки отслеживания, update --remote получает внешний репозиторий подмодуля перед вычислением SHA-1. Если вы не хотите выполнять получение, вы должны использовать submodule update --remote --no-fetch.

Используйте этот параметр, чтобы интегрировать изменения из вышестоящего подпроекта с текущим HEAD вашего подмодуля. В качестве альтернативы вы можете выполнить git pull из подмодуля, что эквивалентно, за исключением имени внешней ветки: update --remote использует вышестоящий репозиторий по умолчанию и submodule.<имя>.branch, в то время как git pull использует branch.<имя>.merge подмодуля. Предпочитайте submodule.<имя>.branch, если вы хотите распространять вышестоящую ветку по умолчанию вместе с суперпроектом, и branch.<имя>.merge, если вы хотите более естественное ощущение при работе в самом подмодуле.

-N
--no-fetch

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

--checkout

Переключает коммит, записанный в суперпроекте, на отсоединённом HEAD в подмодуле. Этот параметр действителен только для команды update. Это поведение по умолчанию, основное использование этого параметра — переопределение submodule.<имя>.update, когда оно установлено в значение, отличное от checkout. Если ключ submodule.<имя>.update либо явно не установлен, либо установлен в checkout, этот параметр подразумевается.

--merge

Сливает коммит, записанный в суперпроекте, с текущей веткой подмодуля. Этот параметр действителен только для команды update. Если указан этот параметр, HEAD подмодуля не будет отсоединён. Если сбой слияния предотвращает этот процесс, вам придётся разрешить возникшие конфликты внутри подмодуля с помощью обычных инструментов разрешения конфликтов. Если ключ submodule.<имя>.update установлен в merge, этот параметр подразумевается.

--rebase

Перемещает текущую ветку на коммит, записанный в суперпроекте. Этот параметр действителен только для команды update. HEAD подмодуля не будет отсоединён. Если сбой слияния предотвращает этот процесс, вам придётся разрешить эти сбои с помощью git-rebase[1]. Если ключ submodule.<имя>.update установлен в rebase, этот параметр подразумевается.

--init

Инициализирует все подмодули, для которых git submodule init ещё не вызывался, перед обновлением. Этот параметр действителен только для команды update.

--name=<имя>

Устанавливает имя подмодуля в указанную строку вместо использования по умолчанию его пути. <имя> должно быть допустимым как имя каталога и не может заканчиваться на /.

--reference=<репозиторий>

Передаёт локальный <репозиторий> в качестве ссылки при клонировании подмодуля. Этот параметр действителен только для команд add и update. Этим командам иногда требуется клонировать внешний репозиторий. В этом случае этот параметр будет передан команде git-clone[1].

Note
 Не используйте этот параметр, если вы внимательно не прочитали примечание о параметрах --reference, --shared и --dissociate команды git-clone[1].
--dissociate

После использования репозитория-ссылки для клонирования больше не полагаться на него. Этот параметр действителен только для команд add и update. Этим командам иногда требуется клонировать внешний репозиторий. В этом случае этот параметр будет передан команде git-clone[1].

Note
 См. ПРИМЕЧАНИЕ выше для параметра --reference.
--recursive

Рекурсивно обходить подмодули. Этот параметр действителен только для команд foreach, update, status и sync. Операция выполняется не только в подмодулях текущего репозитория, но и в любых вложенных подмодулях внутри этих подмодулей (и так далее).

--depth=<глубина>

Создаёт частичный клон с историей, усечённой до <глубина> редакций. Этот параметр действителен для команд add и update. См. git-clone[1]

--recommend-shallow
--no-recommend-shallow

Рекомендовать или нет частичное клонирование подмодулей. Этот параметр действителен только для команды update. Начальное клонирование подмодуля по умолчанию будет использовать рекомендуемый submodule.<имя>.shallow, предоставленный файлом .gitmodules. Чтобы игнорировать предложения, используйте --no-recommend-shallow.

-j<n>
--jobs=<n>

Клонировать новые подмодули параллельно с <n> заданиями. Этот параметр действителен только для команды update. По умолчанию используется параметр submodule.fetchJobs.

--single-branch
--no-single-branch

Клонировать только одну ветку во время обновления: HEAD или указанную с помощью --branch. Этот параметр действителен только для команды update.

<путь>…

Пути к подмодулю(ям). При указании это ограничит команду только подмодулями, найденными по указанным путям. (Этот аргумент обязателен для add).

ФАЙЛЫ

При инициализации подмодулей файл .gitmodules в верхнем каталоге содержащего репозитория используется для поиска URL каждого подмодуля. Этот файл должен быть отформатирован так же, как $GIT_DIR/config. Ключом для каждого URL подмодуля является submodule.<имя>.url. Подробности см. в gitmodules[5].

СМ. ТАКЖЕ

gitsubmodules[7], gitmodules[5].

GIT

Является частью пакета git[1]