git-submodule

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Задаёт URL указанного подмодуля равным <newurl>. После этого конфигурация нового URL удалённого репозитория подмодуля будет автоматически синхронизирована.

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

Эту информацию также можно получить, используя параметр --submodule=log команды git-diff[1].

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

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

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

git submodule foreach 'echo $sm_path `git rev-parse HEAD`'

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

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

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

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

У клонированного независимо, а затем добавленного в качестве подмодуля репозитория, а также в старых конфигурациях каталог Git подмодуля находится внутри самого подмодуля, а не встроен в каталог Git суперпроекта.

По умолчанию эта команда выполняется рекурсивно.

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

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

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

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

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

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

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

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

Вместо SHA-1, записанного суперпроектом, для обновления подмодуля использовать состояние его ветки отслеживания удалённого репозитория. Этот параметр допустимо использовать только с командой update. Используется удалённый репозиторий ветки (branch.<name>.remote); по умолчанию — origin. По умолчанию используется удалённая ветка HEAD, но её имя можно переопределить, задав параметр submodule.<name>.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.<name>.branch, а git pull — branch.<name>.merge подмодуля. Предпочтительнее использовать submodule.<name>.branch, если нужно распространять ветку вышестоящего репозитория по умолчанию вместе с суперпроектом, и branch.<name>.merge, если вы хотите работать непосредственно в подмодуле в более привычном режиме.

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

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

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

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

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

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

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

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

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

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

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

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

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

Пути к подмодулям. Если они указаны, команда будет работать только с подмодулями, расположенными по указанным путям. (Этот аргумент обязателен для add).