українська мова ▾ Topics ▾ Latest version ▾ git-submodule last updated in 2.51.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 ідентичне обчисленню відносних каталогів).

Віддалений сервер за замовчуванням – це віддалений сервер гілки віддаленого відстеження поточної гілки. Якщо такої гілки віддаленого відстеження не існує або 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] [--] [<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-адреса є відносною, вона буде розпізнавана за допомогою віддаленого сервера за замовчуванням. Якщо віддаленого сервера за замовчуванням немає, поточний репозиторій вважатиметься розташовуваним у верхній частині репозиторію.

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

оформлення замовлення

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

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

лисиця

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

merge

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

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

користувацька команда

механізм для виконання довільних команд з ідентифікатором коміта як аргументом. Зокрема, якщо змінна конфігурації 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-адреси підмодулів змінюються в основній програмі, і вам потрібно відповідно оновити ваші локальні репозиторії.

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

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

абсорбувати_гірники

Якщо каталог git підмодуля знаходиться всередині підмодуля, перемістіть каталог git підмодуля до шляху $GIT_DIR/modules його суперпроекту, а потім з’єднайте каталог git та його робочий каталог, встановивши core.worktree та додавши файл .git, що вказує на каталог git, вбудований у каталог git суперпроектів.

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

Ця команда є рекурсивною за замовчуванням.

ОПЦІЇ

-q
--quiet

Друкувати лише повідомлення про помилки.

--progress

Цей параметр дійсний лише для команд додавання та оновлення. За замовчуванням статус виконання повідомляється у стандартному потоці помилок, коли він підключений до терміналу, якщо не вказано -q. Цей прапорець примусово встановлює статус виконання, навіть якщо стандартний потік помилок не спрямовано до терміналу.

--all

Ця опція дійсна лише для команди deinit. Скасувати реєстрацію всіх підмодулів у робочому дереві.

-b <branch>
--branch <branch>

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

-f
--force

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

--cached

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

--files

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

-n
--summary-limit

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

--remote

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

-N
--no-fetch

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

--checkout

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

--merge

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

--rebase

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

--init

Ця опція дійсна лише для команди оновлення. Ініціалізуйте всі підмодулі, для яких ще не було викликано "git submodule init", перед оновленням.

--name

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

--reference <repository>

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

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

--dissociate

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

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

--recursive

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

--depth

Ця опція дійсна для команд додавання та оновлення. Створіть «неглибокий» клон з історією, скороченою до вказаної кількості редакцій. Див. git-clone[1]

--[no-]recommend-shallow

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

-j <n>
--jobs <n>

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

--[no-]single-branch

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

<path>…​

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

ФАЙЛИ

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

ДИВ. ТАКОЖ

gitsubmodules[7], gitmodules[5].

GIT

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