Як працює двостороння синхронізація з Git

Кожна платформа документації зі сторінкою інтеграції з git дає ту саму обіцянку: ваша документація живе в git, ваша команда редагує в браузері, і все залишається синхронізованим. На практиці більшість із цих інтеграцій — це одностороннє дзеркало, що руйнується в момент, коли дві людини редагують з різних боків.

Ми писали про чому це відбувається у попередньому пості. Цей пост заглиблюється в рішення: як Valoryx реалізує двосторонню синхронізацію за допомогою патерну Content Ledger і чому цей підхід обробляє сценарії, що ламають інші інструменти.

Основна проблема

Веб-редактор і git-репозиторій мають фундаментально різні моделі узгодженості.

У веб-редакторі збереження є негайним і атомарним. Ви натискаєте «Зберегти», контент зберігається, і будь-хто, хто завантажує сторінку, бачить вашу версію. Немає концепції «стейджингу» чи «комітингу» — запис і є публікацією.

У git зміни групуються в коміти, коміти пушаться на віддалений сервер, і віддалений сервер потрібно зфетчити та змерджити іншим учасникам. Є вбудована затримка між «я зробив зміну» та «всі бачать мою зміну».

Коли ви об’єднуєте обидві моделі — веб-редактор і git-репозиторій, що вказують на той самий контент — ви створюєте вікно, де дві людини можуть вносити конфліктні зміни, не знаючи одна про одну. Особа А редагує в браузері. Особа Б пушить коміт із VS Code. Жодна не знає про іншу, поки не запуститься синхронізація, і тоді щось повинно поступитися.

Більшість платформ обробляють це, обираючи переможця: або база даних завжди виграє (Wiki.js), або git-репозиторій завжди виграє (більшість статичних генераторів). Обидва підходи непомітно втрачають дані.

Патерн Content Ledger

Content Ledger — це журнал із лише додаванням кожної мутації контенту, незалежно від її походження. Уявіть його як write-ahead log у базі даних, але для редагувань документації.

Кожна зміна — чи то з веб-редактора, API, виклику MCP-інструменту або git push — записується як запис у леджері перед застосуванням. Кожен запис містить:

• Позначка часу — коли було зроблено зміну
• Походження — звідки вона прийшла (web, git, api, mcp)
• Шлях сторінки — яка сторінка була змінена
• Операція — create, update, move, delete
• Хеш контенту — SHA-256 нового контенту
• Батьківський хеш — SHA-256 контенту, на основі якого зроблено зміну

Батьківський хеш — це ключова інновація. Він створює ланцюг причинності, подібний до того, як git-коміти посилаються на батьківські коміти. Коли дві зміни мають однаковий батьківський хеш, але різні хеші контенту, у вас конфлікт — і ви знаєте про нього до того, як будь-яка зміна буде застосована.

Як працює синхронізація: крок за кроком

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

Крок 1: Збір очікуваних змін

Рушій синхронізації читає всі записи леджера з моменту останньої успішної синхронізації. Це локальні зміни, що ще не були запушені в git.

Крок 2: Отримання віддалених змін

Рушій виконує git fetch, щоб отримати нові коміти з віддаленого репозиторію. Потім він порівнює віддалений HEAD із локальним покажчиком синхронізації для ідентифікації вхідних змін.

Крок 3: Узгодження

Для кожної сторінки, що має зміни з обох боків (локальні записи леджера ТА віддалені git-коміти), рушій перевіряє батьківські хеші:

• Немає перетину: Локальна зміна базувалася на тій самій версії, що має git. Fast-forward merge — застосувати обидві зміни по порядку.
• Розходження, без конфлікту: Обидві сторони змінили різні сторінки. Застосувати обидва набори змін незалежно.
• Розходження, та сама сторінка: Обидві сторони змінили одну й ту ж сторінку. Це справжній конфлікт.

Крок 4: Вирішення конфліктів

Коли виявлено справжній конфлікт, Valoryx не обирає переможця непомітно. Замість цього він:

1. Зберігає обидві версії в леджері
2. Позначає сторінку як «конфліктну» в інтерфейсі
3. Показує diff між двома версіями
4. Дозволяє людині обрати, яку версію зберегти, або змерджити їх вручну

Це та сама модель, що git merge з конфліктами — за винятком того, що вона працює через веб-інтерфейс, тому нетехнічні редактори можуть вирішувати конфлікти без вивчення git-команд.

Крок 5: Коміт і push

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

Як це виглядає на практиці

Розглянемо такий реальний сценарій. Розробник оновлює документацію з автентифікації API із VS Code і пушить у репозиторій. Тим часом технічний письменник редагує вступ тієї ж сторінки у веб-редакторі Valoryx.

З інструментом односторонньої синхронізації одне редагування перезаписує інше. З Content Ledger:

1. Push розробника створює віддалену зміну (новий коміт на стороні git)
2. Збереження письменника створює локальний запис леджера (нова мутація на стороні вебу)
3. Запускається синхронізація, виявляє, що обидві зміни стосуються тієї самої сторінки
4. Батьківські хеші розходяться — це справжній конфлікт
5. Сторінку позначено, обидві версії збережені
6. Письменник бачить сповіщення: «Ця сторінка має конфлікт синхронізації» з відображенням diff
7. Письменник зливає зміни (розробник виправив блок коду, письменник переписав вступ — обидва редагування валідні)
8. Злита версія комітиться і пушиться

Жодної втрати даних. Жодних непомітних перезаписів. Злиття відбулося через веб-інтерфейс, а не термінал.

Порівняння з одностороннім підходом

Останній рядок важливіший, ніж здається. Перейменування або переміщення сторінки у веб-інтерфейсі, поки хтось редагує старий шлях у git, — один із найскладніших крайніх випадків. Більшість інструментів здаються. Content Ledger відстежує операції переміщення явно, тому знає, що /docs/auth.md став /docs/authentication.md, і може застосувати вхідне git-редагування до правильного нового шляху.

Чому б не використовувати Git напряму?

Якщо git настільки центральний для цієї архітектури, чому б не пропустити веб-редактор і використовувати git напряму? Дві причини:

По-перше, не кожен у команді документації використовує git. Продакт-менеджери, інженери підтримки та технічні письменники часто віддають перевагу веб-редактору. Примушування їх до git-процесу створює тертя та зменшує внесок.

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

Content Ledger з’єднує ці два світи. Git-користувачі працюють у git. Веб-користувачі працюють у браузері. Обидва процеси є першокласними, і леджер підтримує їх узгодженість.

Налаштування Git Sync

Якщо ви хочете спробувати це з власним репозиторієм:

1. Встановіть Valoryx — один бінарний файл, без зовнішніх залежностей
2. Створіть workspace і підключіть його до git-репозиторію в налаштуваннях workspace
3. Налаштуйте URL віддаленого сервера, гілку та інтервал синхронізації
4. Починайте редагувати з обох боків

Посібник з інтеграції git охоплює повне налаштування, включаючи конфігурацію SSH-ключів, стратегії гілок та налаштування інтервалу синхронізації.

Для команд, що вже керують документацією в git-репозиторіях, це означає, що вам не потрібно обирати між зручним досвідом редагування та git-нативним процесом. Content Ledger робить обидва можливими без компромісів, які переслідують кожен інший підхід, який ми тестували.