українська мова ▾ Topics ▾ Latest version ▾ git-submodule last updated in 2.54.0

НАЗВА

git-submodule — Ініціалізація, оновлення або перевірка субмодулів

СИНОПСИС

git submodule [--quiet] [--cached]
git submodule [--quiet] add [<options>] [--] <repository> [<path>]
git submodule [--quiet] status [--cached] [--recursive] [--] [<path>…​]
git submodule [--quiet] init [--] [<path>…​]
git submodule [--quiet] deinit [-f|--force] (--all|[--] <path>...)
git submodule [--quiet] update [<options>] [--] [<path>…​]
git submodule [--quiet] set-branch [<options>] [--] <path>
git submodule [--quiet] set-url [--] <path> <newurl>
git submodule [--quiet] summary [<options>] [--] [<path>…​]
git submodule [--quiet] foreach [--recursive] <command>
git submodule [--quiet] sync [--recursive] [--] [<path>…​]
git submodule [--quiet] absorbgitdirs [--] [<path>…​]

ОПИС

Перевіряє, оновлює та керує субмодулями.

Для отримання додаткової інформації про субмодулі див. gitsubmodules[7].

КОМАНДИ

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

add [-b <branch>] [-f | --force] [--name <name>] [--reference <repository>] [--ref-format <format>] [--depth <depth>] [--] <repository> [<path>]

Додати вказаний репозиторій як субмодуль за вказаним шляхом до набору змін, який буде зафіксовано поруч із поточним проєктом: поточний проєкт називається «суперпроєктом».

<repository> — це URL-адреса репозиторію origin нового субмодуля. Вона може бути або абсолютним URL, або (якщо вона починається з ./ або ../), розташуванням відносно стандартного віддаленого репозиторію суперпроєкту (Зверніть увагу, що для вказання репозиторію foo.git, який розташований безпосередньо поруч із суперпроєктом bar.git, вам доведеться використовувати ../foo.git замість ./foo.git, як і слід було б очікувати, дотримуючись правил для відносних URL-адрес, оскільки обчислення відносних URL-адрес у Git ідентичне обчисленню відносних тек).

Стандартним віддаленим репозиторієм є віддалений репозиторій гілки remote-tracking поточної гілки. Якщо такої гілки remote-tracking не існує або HEAD є відʼєднаним, то за стандартний віддалений репозиторій вважається origin. Якщо у суперпроєкті не налаштовано стандартний віддалений репозиторій, суперпроєкт є своїм власним авторитетним upstream, і замість нього використовується поточна робоча тека.

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

Вказана URL-адреса записується в .gitmodules для використання наступними користувачами, які клонують суперпроєкт. Якщо URL-адреса вказана відносно репозиторію суперпроєкту, передбачається, що репозиторії суперпроєкту та субмодулів будуть зберігатися разом в одному відносному місці, і потрібно вказати лише URL-адресу суперпроєкту. git-submodule правильно знайде субмодуль, використовуючи відносну URL-адресу в .gitmodules.

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

status [--cached] [--recursive] [--] [<path>...]

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

Якщо вказано --cached, ця команда натомість виведе SHA-1, записаний у суперпрєкті для кожного субмодуля.

Якщо вказано --recursive, ця команда рекурсивно перейде до вкладених субмодулів та також покаже їхній стан.

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

init [--] [<path>...]

Ініціалізація субмодулів, записаних в індексі (які були додані та зафіксовані в іншому місці), шляхом налаштування параметра submodule.$name.url у файлі .git/config, використовуючи як шаблон відповідне значення з файлу .gitmodules. Якщо URL-адреса є відносною, вона буде визначена за допомогою стандартного віддаленого репозиторію. Якщо стандартного віддаленого репозиторію немає, поточний репозиторій буде вважатися upstream.

Необовʼязкові аргументи <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 для визначення стандартного віддаленого репозиторію.

deinit [-f | --force] (--all|[--] <path>...)

Скасує реєстрацію вказаних субмодулів, тобто видалить весь розділ submodule.$name із файлу .git/config разом із їхнім робочим деревом. Надалі команди git submodule update, git submodule foreach та git submodule sync пропускатимуть усі незареєстровані субмодулі, доки їх не буде знову ініціалізовано, тому скористайтеся цією командою, якщо більше не хочете мати локальну копію субмодуля у своєму робочому дереві.

Коли команда виконується без pathspec, вона видає помилку, замість того, щоб скасовувати ініціалізацію всього, щоб запобігти помилкам.

Якщо вказано --force, робоче дерево субмодуля буде видалено, навіть якщо воно містить локальні модифікації.

Якщо ви дійсно хочете видалити субмодуль з репозиторію та створити його коміт, використовуйте git-rm[1]. Дивіться gitsubmodules[7] для отримання інформації про варіанти видалення.

update [--init] [--remote] [-N | --no-fetch] [--[no-]recommend-shallow] [-f | --force] [--checkout | --rebase | --merge] [--reference=<repository>] [--ref-format=<format>] [--depth=<depth>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--filter=<filter-spec>] [--] [<path>...]

Оновлює зареєстровані субмодулі відповідно до вимог суперпроєкту шляхом клонування відсутніх субмодулів, завантаження відсутніх комітів у субмодулях та оновлення робочого дерева субмодулів. «Оновлення» можна виконати кількома способами залежно від параметрів командного рядка та значення змінної конфігурації submodule.<name>.update. Параметр командного рядка має пріоритет над змінною конфігурації. Якщо жоден з них не вказано, виконується checkout. (Примітка: вміст файлу .gitmodules на цьому етапі не має значення; див. git submodule init вище, щоб дізнатися, як використовується .gitmodules). Процедури update, що підтримуються як з командного рядка, так і через конфігурацію submodule.<name>.update, такі:

checkout

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

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

rebase

поточна гілка субмодуля буде перебазована на основі коміту, записаного в суперпроєкті.

merge

коміт, записаний у суперпроєкті, буде обʼєднано з поточною гілкою в субмодулі.

Наведені нижче процедури оновлення мають додаткові обмеження:

!<custom-command>

механізм для виконання довільних команд з ідентифікатором коміта як аргументом. Зокрема, якщо змінна конфігурації submodule.<name>.update встановлена на !<custom-command>, імʼя обʼєкта коміта, записане в суперпроєкті для субмодуля, додається до рядка <custom-command> та виконується. Зверніть увагу, що цей механізм не підтримується у файлі .gitmodules або в командному рядку.

none

субмодуль не оновлюється. Ця процедура оновлення не дозволена в командному рядку.

Якщо субмодуль ще не ініціалізовано, і ви просто хочете використовувати налаштування, що зберігаються в .gitmodules, ви можете автоматично ініціалізувати субмодуль за допомогою опції --init.

Якщо вказано --recursive, ця команда рекурсивно звернеться до зареєстрованих субмодулів та оновить будь-які вкладені субмодулі всередині них.

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

Якщо вказано --filter <специфікація-фільтра>, до субмодуля буде застосовано вказаний фільтр часткового клонування. Див. git-rev-list[1] для отримання детальної інформації про специфікації фільтрів.

set-branch (-b|--branch) <branch> [--] <path>
set-branch (-d|--default) [--] <path>

Встановлює стандартну віддалену гілку відстеження для субмодуля. Опція --branch дозволяє вказати віддалену гілку. Опція --default видаляє ключ конфігурації submodule.<name>.branch, внаслідок чого стандартною гілкою відстеження стає віддалена гілка HEAD.

set-url [--] <path> <newurl>

Встановлює URL-адресу зазначеного субмодуля на <newurl>. Потім автоматично синхронізує нову конфігурацію віддаленої URL-адреси субмодуля.

summary [--cached | --files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...]

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

Використання опції --submodule=log з git-diff[1] також надасть цю інформацію.

foreach [--recursive] <command>

Виконати довільну команду оболонки <command> у кожному отриманому субмодулі. Команда має доступ до змінних $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] [--] [<path>...]

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

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

Цей параметр дійсний лише для команди export. Це стосується лише команди deinit.

-b<branch>
--branch=<branch>

Гілка репозиторію, яку потрібно додати як субмодуль. Назва гілки записується як submodule.<назва>.branch у .gitmodules для update --remote. Спеціальне значення . використовується для позначення того, що назва гілки в субмодулі має збігатися з назвою поточної гілки в поточному репозиторії. Якщо опцію не вказано, стандартно використовується віддалений HEAD.

-f
--force

Примусово виконати команду, навіть якщо за звичайних умов вона завершилася б з помилкою. Ця опція діє лише для команд add, deinit та update.

add

дозволяє додати шлях до субмодуля, який інакше ігнорується. Ця опція також використовується для обходу перевірки на те, чи імʼя субмодуля вже не використовується. Зазвичай команда git submodule add завершиться з помилкою, якщо запропоноване ім’я (яке утворюється на основі шляху) вже зареєстровано для іншого субмодуля в репозиторії. Використання --force дозволяє команді продовжити роботу, автоматично генеруючи унікальну назву шляхом додавання номера до конфліктної назви (наприклад, якщо існує субмодуль з назвою child, вона спробує child1 і так далі).

deinit

робочі дерева субмодулів будуть видалені, навіть якщо вони містять локальні зміни.

update

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

--cached

Використовуйте індекс для визначення коміту замість HEAD. Ця опція діє лише для команд status та summary.

--files

Змушує команду summary порівнювати коміт в індексі з комітом у HEAD субмодуля.

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

Обмежте розмір summary (загальну кількість показаних комітів) до <n>. Якщо вказати 0, підсумок буде вимкнено; від’ємне число означає необмежену кількість (стандартно). Це обмеження застосовується лише до змінених субмодулів. Для доданих, видалених або таких, у яких змінився тип, розмір завжди обмежується значенням 1.

--remote

Замість використання записаного SHA-1 суперпроєкту для оновлення субмодуля, використовуйте стан гілки віддаленого відстеження субмодуля. Ця опція діє лише для команди update. Використовується віддалений репозиторій гілки (branch.<name>.remote), зазвичай це origin. Використовується віддалена гілка, зазвичай це віддалений HEAD, але імʼя гілки можна змінити, встановивши опцію submodule.<name>.branch у файлі .gitmodules або .git/config (причому .git/config має пріоритет).

Це працює для будь-якої з підтримуваних процедур оновлення (--checkout, --rebase тощо). Єдина зміна — це джерело цільового SHA-1. Наприклад, submodule update --remote --merge обʼєднає зміни субмодуля upstream з субмодулями, тоді як submodule update --merge обʼєднає зміни gitlink суперпроєкту з субмодулями.

Щоб забезпечити поточний стан гілки відстеження, update --remote отримує дані з віддаленого репозиторію субмодуля перед обчисленням SHA-1. Якщо ви не хочете отримувати дані, слід використовувати submodule update --remote --no-fetch.

Використовуйте цю опцію, щоб інтегрувати зміни з субпроєкту upstream у поточний HEAD вашого субмодуля. Як альтернативу, ви можете виконати команду git pull із субмодуля, що є еквівалентним, за винятком імені віддаленої гілки: update --remote використовує стандартне репозиторій upstream та submodule.<name>.branch, тоді як git pull використовує гілку branch.<name>.merge субмодуля. Віддайте перевагу submodule.<name>.branch, якщо ви хочете розподілити стандартну гілку upstream із суперпроєктом, і branch.<name>.merge, якщо ви хочете отримати більш природне відчуття під час роботи в самому субмодулі.

-N
--no-fetch

Не завантажувати нові об’єкти з віддаленого сервера. Ця опція діє лише для команди update.

--checkout

Виконати checkout коміту, записаного в суперпроєкті, на відокремленому HEAD у підмодулі. Ця опція діє лише для команди update. Це стандартна поведінка; основне призначення цієї опції — замінити значення submodule.<name>.update, якщо воно встановлено на значення, відмінне від checkout. Якщо ключ submodule.<name>.update явно не встановлено або встановлено на checkout, ця опція застосовується неявним чином.

--merge

Обʼєднати коміт, записаний у суперпроєкті, з поточною гілкою субмодуля. Ця опція діє лише для команди update. Якщо вказано цю опцію, HEAD субмодуля не буде від’єднано. Якщо цей процес не вдається виконати через помилку злиття, вам доведеться усунути конфлікти, що виникли в субмодулі, за допомогою звичайних інструментів розвʼязання конфліктів. Якщо ключ submodule.<name>.update встановлено на merge, ця опція є неявною.

--rebase

Виконати перебазування поточної гілки на коміт, записаний у суперпроєкті. Ця опція діє лише для команди update. Покажчик HEAD субмодуля не буде відʼєднано. Якщо цей процес неможливий через помилки злиття, вам доведеться усунути ці помилки за допомогою команди git-rebase[1]. Якщо для ключа submodule.<name>.update встановлено значення rebase, ця опція є неявною.

--init

Перед оновленням ініціалізувати всі субмодулі, для яких до цього моменту не було виконано команду git submodule init. Ця опція діє лише для команди update.

--name=<name>

Встановити імʼя субмодуля на заданий рядок замість використання типового шляху. <name> має бути допустимим іменем теки і не може закінчуватися символом /.

--reference=<repository>

Під час клонування субмодуля передати локальний <репозиторій> як посилання. Ця опція діє лише для команд 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=<depth>

Створити поверхневий клон з історією, скороченою до <depth> ревізій. Ця опція доступна для команд add та update. Див. git-clone[1]

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

Рекомендувати чи ні поверхневе клонування субмодулів. Ця опція діє лише для команди update. Під час початкового клонування субмодуля зазвичай використовується рекомендований формат submodule.<name>.shallow, який стандартно вказано у файлі .gitmodules. Щоб проігнорувати ці рекомендації, скористайтеся опцією --no-recommend-shallow.

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

Клонувати нові субмодулі паралельно з якомога більшою кількістю завдань. Цей параметр дійсний лише для команди update. Зазвичай використовується параметр submodule.fetchJobs.

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

Під час оновлення клонувати лише одну гілку: HEAD або ту, що вказано за допомогою параметра --branch. Цей параметр діє лише для команди update.

<шлях>...

Шляхи до субмодуля(ів). Якщо вказано, це обмежить роботу команди лише субмодулями, знайденими за вказаними шляхами. (Цей аргумент обовʼязковий для add).

ФАЙЛИ

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

ДИВ. ТАКОЖ

gitsubmodules[7], gitmodules[5].

GIT

Частина набору git[1]