українська мова ▾ Topics ▾ Latest version ▾ git-submodule last updated in 2.52.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-адреса репозиторію-джерела нового субмодуля. Це може бути або абсолютна 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» для цього 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). Процедури «оновлення», що підтримуються як з командного рядка, так і через конфігурацію 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>

Виконує довільну команду оболонки в кожному завантаженому субмодулі. Команда має доступ до змінних $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. Цей параметр примусово виводить інформацію про хід виконання, навіть якщо стандартний потік помилок не спрямований в термінал.

--all

Ця опція діє лише для команди 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

Ця опція діє лише для команд status та summary. Зазвичай ці команди використовують коміт, що міститься в HEAD субмодуля, але з цією опцією замість нього використовується коміт, збережений в індексі.

--files

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

-n
--summary-limit

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

--remote

Ця опція діє лише для команди update. Замість використання записаного SHA-1 суперпроєкту для оновлення субмодуля, використовується стан гілки віддаленого відстеження субмодуля. Використовується віддалена гілка (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

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

--checkout

Ця опція діє лише для команди update. Виконує checkout коміту, записаного в суперпроєкті, на відокремленому HEAD у субмодулі. Це стандартна поведінка; основне призначення цієї опції — замінити значення 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", перед оновленням.

--name

Ця опція діє лише для команди add. Вона встановлює імʼя субмодуля як заданий рядок замість стандартного шляху до нього. Ім’я повинно бути допустимим як ім’я теки і не може закінчуватися символом «/».

--reference <repository>

Цей параметр дійсний лише для команд add та update. Цим командам іноді потрібно клонувати віддалений репозиторій. У цьому випадку цей параметр буде передано команді git-clone[1].

ПРИМІТКА: Не використовуйте цю опцію, якщо ви уважно не прочитали примітку до опцій --reference, --shared та --dissociate у git-clone[1].

--dissociate

Цей параметр дійсний лише для команд add та update. Цим командам іноді потрібно клонувати віддалений репозиторій. У цьому випадку цей параметр буде передано команді git-clone[1].

ПРИМІТКА: див. ПРИМІТКУ щодо опції --reference.

--recursive

Ця опція дійсна лише для команд foreach, update, status та sync. Рекурсивний перехід між субмодулями. Операція виконується не лише в субмодулях поточного репозиторію, але й у будь-яких вкладених субмодулях всередині цих субмодулів (і так далі).

--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

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

<path>…​

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

ФАЙЛИ

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

ДИВ. ТАКОЖ

gitsubmodules[7], gitmodules[5].

GIT

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