add git-repository-mirroring-with-local-gitmodules-dependencies-in-radicle.gmi

public/uk/git-repository-mirroring-with-local-gitmodules-dependencies-in-radicle.gmi

@@ -0,0 +1,184 @@
+# Дзеркалювання репозиторію Git з локальними залежностями .gitmodules в Radicle
+
+Створюючи дзеркала репозиторіїв, зокрема в локальних мережах типу Yggdrasil, майнтейнери часто забувають про дзеркалювання залежностей: наприклад, `.gitmodules`.
+
+З цієї причини, користувач, який розгортає середовище розробки для збірки програми, мусить звертатись на "зовнішні" URL. Якщо в нього відсутній Інтернет, це може спричинити незручності у вигляді ручного "розв'язання" таких адрес - проксуванням або копіюванням з оптичного драйву чи флешки.
+
+З іншого боку, дзеркала (на відміну від проксі) часто створюються на випадок "падіння" першоджерела, тому важливо подбати про повноцінну копію, щоб не загубити жодного пазлу, без якого збірка буде не можливою.
+
+Отже, розглянемо як правильно організувати дзеркало репозиторіїв в мережі Radicle, щоб залежності підтягувались автоматично. У прикладі будемо використовувати репозиторій Source engine 2017 року:
+=> https://github.com/nillerusr/source-engine
+
+## Публікація .gitmodules
+
+Спочатку потрібно забрати сорс з кореневого апстріму, з рекурсивним підвантаженням його модулів:
+
+``` bash
+git clone --recursive https://github.com/nillerusr/source-engine.git
+cd source-engine
+```
+
+Тепер шукаємо всі локальні файли `.gitmodules` - в `source-engine` таких два:
+
+``` bash
+$ find . -name ".gitmodules" -o -path .
+.
+./.gitmodules
+./thirdparty/freetype/.gitmodules
+```
+
+Заходимо в кожен знайдений файл `.gitmodules` і публікуємо окремі дзеркала для кожного `url`:
+1. виконуємо `git clone URL`
+2. з теки кожного модуля, ініціалізуємось з `rad init`
+3. замість URL в `.gitmodules` вказуємо згенерований RID
+
+``` .gitmodules
+[submodule "thirdparty"]
+	path = thirdparty
+	url = rad://z2v4ViM5Eyd7gRVcdXDYQXFZfw1CR
+	branch = rad
+[submodule "ivp"]
+	path = ivp
+	url = rad://z2wtznZZ8Q5VeoPXeieHPbk4uketL
+[submodule "lib"]
+	path = lib
+	url = rad://z2NfvnmPgsFpGg5abyvEbfmnjLAWb
+```
+* модуль `thirdparty` використовує гілку `rad`, в якій ми оголосили залежність `dlg`
+
+``` thirdparty/freetype/.gitmodules
+[submodule "dlg"]
+	path = subprojects/dlg
+	url = rad://z2eMXuSXHUCGHx1w8Hnsnep5VdhEx
+```
+
+Зверніть увагу, що в `url` потрібно вказувати саме схему `rad://` замість префіксу `rad:`!
+
+Відповідно, всі ці RID ініціюються окремо, у своїх теках, але приклади нижче для них спільні.
+
+### Канонічні посилання (crefs)
+
+Зміни я публікую окремою гілкою, щоб залишити оригінальний `master` для подальших апдейтів з `git pull`. Але перш, як створити її, потрібно спочатку ознайомитись з поняттям Canonical References:
+=> https://radicle.xyz/2025/08/12/canonical-references
+* інакше додану гілку не буде видно після клонування репозиторію користувачем
+
+Це важливо зробити саме до дії `push`, інакше доведеться вказувати залежності `.gitmodules` з прив'язкою до простору імен користувача (Radicle має децентралізоване дерево контрибуторів, які видно при перегляді стандартної гілки `master` зокрема у Web UI).
+
+В прикладах нижче, буде розглядатись гілка з назвою `rad`. Якщо з якихось причин таку гілку було створено раніше, її потрібно видалити (через баг синхронізації ноди, що заважатиме потім)
+
+``` bash
+git branch --delete rad
+git push rad --delete rad
+```
+
+Тепер відкриваємо профіль проєкту командою:
+
+``` bash
+rad id update --edit
+```
+
+І додаємо себе до `xyz.radicle.crefs`, що є дочірнім елементом `payload`:
+
+``` bash
+{
+  "payload": {
+    "xyz.radicle.crefs": {
+      "rules": {
+        "refs/heads/rad": {
+          "allow": [
+            "did:key:z6Mkh1AhzGE5H7CxeCMLYy4BdYjcsjRy3Do4yhQfigdVvwes"
+          ],
+          "threshold": 1
+        }
+      }
+    },
+    "xyz.radicle.project": {
+      "defaultBranch": "master",
+      "description": "Source third-party (mirror of https://github.com/nillerusr/source-thirdparty)",
+      "name": "source-thirdparty"
+    }
+  },
+  "delegates": [
+    "did:key:z6Mkh1AhzGE5H7CxeCMLYy4BdYjcsjRy3Do4yhQfigdVvwes"
+  ],
+  "threshold": 1
+}
+```
+* свій DID можна отримати командою `rad self --did`
+* зверніть увагу на відповідність вашій гілці `refs/heads/rad` бо з `refs/heads/*` в мене не вийшло
+
+Зберігаємо цей файл, і якщо він не містить помилок, буде запропоновано здійснити коміт. В опис коміту я пишу щось накшталт "update crefs".
+
+### Публікація гілки
+
+Виконавши оновлення політики Канонічних посилань:
+
+``` bash
+git checkout -b rad
+```
+
+Комітимо і публікуємо патч`.gitmodules`, в рамках створеної гілки `rad`:
+
+``` bash
+git add .gitmodules
+git commit -m 'init radicle mirror'
+git push --set-upstream rad rad
+```
+
+### Тестування гілки
+
+Оскільки поточний інтерфейс Web UI нічого не покаже, перевіряти потрібно командним рядком:
+
+``` bash
+git ls-remote rad://z2v4ViM5Eyd7gRVcdXDYQXFZfw1CR
+```
+* в результуючому списку має бути наявною гілка `refs/heads/rad`
+
+Також, можна переглянути наявність гілки `rad` командою:
+
+``` bash
+$ git branch -r
+  rad/master
+  rad/rad
+```
+
+Відповідно, тепер залежності `.gitmodules` зможуть підвантажитись, використовуючи окрему гілку `rad` стандартними засобами Git.
+
+## Отримання .gitmodules
+
+Щоб клієнт Git зміг отримати залежності `.gitmodules` виключно засобами налаштованої маршрутизації Radicle, йому потрібно додати виключення на протокол `rad://` (вказували в `url`). Робити виключення потрібно саме глобально (`--global`) оскільки ініціалізація модулів відбувається в просторі їх поточної теки:
+
+``` bash
+git config --global protocol.rad.allow always
+git config --global protocol.file.allow always
+```
+
+Для обробки протоколу `rad://`, клієнт повинен мати встановлений компонент `git-remote-rad`:
+
+``` bash
+$ which git-remote-rad
+~/.radicle/bin/git-remote-rad
+```
+* цей компонент є частиною стандартної ноди
+
+Виконавши вказані вимоги, можна розгорнути проєкт виключно засобами дзеркала в мережі Radicle:
+
+``` bash
+rad clone rad:z33AAz3Gvu2m8HEsncgPiwRRwRYu6 source-engine
+cd source-engine
+git checkout rad
+git submodule update --init --recursive
+```
+* далі виконується збірка, згідно інструкцій README
+
+## Посилання
+
+=> https://radicle.zulipchat.com/#narrow/channel/369277-heartwood/topic/git-remote-rad.20for.20URL.20remotes.2C.20is.20that.20possible.3F/with/478028049 Zulip: git-remote-rad for URL remotes, is that possible?
+=> https://radicle.zulipchat.com/#narrow/channel/369274-General/topic/How.20to.20make.20top.20level.20branch Zulip: How to make top level branch
+
+### Дивіться також
+
+=> radicle-is-decentralized-p2p-git-dvcs.gmi Radicle: децентралізований P2P хостинг Git/DVCS
+=> radicle-multi-network-seed-deployment.gmi Розгортання сіда Radicle в мульти-мережному середовищі
+=> radicle-web-service-deployment.gmi Розгортання Веб-інфраструктури Radicle на прикладі оверлейних мереж
+=> transfer-radicle-repository-to-another-git-upstream-while-preserving-rid.gmi Перенесення репозиторію Radicle на інший апстрім Git зі збереженням RID

public/uk/index.gmi

@@ -16,6 +16,7 @@
 
 ### Нотатки
 
+=> git-repository-mirroring-with-local-gitmodules-dependencies-in-radicle.gmi 2026-02-19 Дзеркалювання репозиторію Git з локальними залежностями .gitmodules в Radicle
 => transfer-radicle-repository-to-another-git-upstream-while-preserving-rid.gmi 2026-02-18 Перенесення репозиторію Radicle на інший апстрім Git зі збереженням RID
 => build-xash3d-fwgs-half-life-on-haiku-os.gmi 2026-02-17 Розвідка боєм: Xash3D (FWGS) / Half-Life в Haiku OS
 => radicle-web-service-deployment.gmi 2026-02-12 Розгортання Веб-інфраструктури Radicle на прикладі оверлейних мереж

public/uk/radicle-is-decentralized-p2p-git-dvcs.gmi

@@ -284,4 +284,5 @@ rad:z4FoMnoSve6Ku6gz4qiuSpzmGr1YE
 => radicle-multi-network-seed-deployment.gmi Розгортання сіда Radicle в мульти-мережному середовищі
 => radicle-web-service-deployment.gmi Розгортання Веб-інфраструктури Radicle на прикладі оверлейних мереж
 => transfer-radicle-repository-to-another-git-upstream-while-preserving-rid.gmi Перенесення репозиторію Radicle на інший апстрім Git зі збереженням RID
+=> git-repository-mirroring-with-local-gitmodules-dependencies-in-radicle.gmi Дзеркалювання репозиторію Git з локальними залежностями .gitmodules в Radicle
 => rust-cross-compilation-with-cross-crate.gmi Простий спосіб крос-компіляції Rust з cross