Как работает двунаправленная синхронизация с Git

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

Мы написали о том, почему это происходит, в предыдущей статье. Эта идёт глубже в решение: как Valoryx реализует двунаправленную синхронизацию с использованием паттерна Content Ledger и почему этот подход справляется со сценариями, которые ломают другие инструменты.

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

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

В веб-редакторе сохранение происходит мгновенно и атомарно. Вы нажимаете «сохранить», контент сохраняется, и любой, загружающий страницу, видит вашу версию. Нет понятия «staging» или «commit» — запись и есть публикация.

В git изменения группируются в коммиты, коммиты пушатся в удалённый репозиторий, и удалённый репозиторий должен быть скачан и смёржен другими участниками. Между «я внёс изменение» и «все видят моё изменение» есть неизбежная задержка.

Когда вы объединяете обе модели — веб-редактор и git-репозиторий, указывающие на один контент — вы создаёте окно, в котором два человека могут вносить конфликтующие правки, не зная друг о друге. Человек А редактирует в браузере. Человек Б пушит коммит из VS Code. Ни один не знает о другом, пока не запустится синхронизация, и тогда что-то должно уступить.

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

Паттерн Content Ledger

Content Ledger — это журнал только для добавления, куда записывается каждая мутация контента, независимо от её происхождения. Представьте это как журнал упреждающей записи (write-ahead log) в базе данных, но для правок документации.

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

• Временная метка — когда было сделано изменение
• Источник — откуда оно пришло (web, git, api, mcp)
• Путь страницы — какая страница была затронута
• Операция — создание, обновление, перемещение, удаление
• Хеш контента — SHA-256 нового контента
• Родительский хеш — SHA-256 контента, на основе которого было сделано изменение

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

Как работает синхронизация: шаг за шагом

Вот что происходит во время цикла синхронизации. Valoryx запускает его автоматически с настраиваемым интервалом (по умолчанию: 30 секунд) или по требованию, когда пользователь запускает его вручную.

Шаг 1: Сбор ожидающих изменений

Движок синхронизации читает все записи реестра с момента последней успешной синхронизации. Это локальные изменения, ещё не запушенные в git.

Шаг 2: Получение удалённых изменений

Движок выполняет git fetch для получения новых коммитов из удалённого репозитория. Затем сравнивает удалённый HEAD с локальным указателем синхронизации для определения входящих изменений.

Шаг 3: Согласование

Для каждой страницы, имеющей изменения с обеих сторон (локальные записи реестра И удалённые git-коммиты), движок проверяет родительские хеши:

• Нет пересечения: Локальное изменение основано на той же версии, что и git. Fast-forward мёрж — применяются оба изменения по порядку.
• Разошлись, нет конфликта: Обе стороны изменили разные страницы. Оба набора изменений применяются независимо.
• Разошлись, та же страница: Обе стороны изменили одну и ту же страницу. Это настоящий конфликт.

Шаг 4: Разрешение конфликтов

Когда обнаруживается настоящий конфликт, Valoryx не выбирает победителя молча. Вместо этого:

1. Обе версии сохраняются в реестре
2. Страница отмечается как «конфликтная» в интерфейсе
3. Показывается дифф между двумя версиями
4. Человек выбирает, какую версию сохранить, или объединяет их вручную

Это та же модель, что и git merge с конфликтами — только через веб-интерфейс, чтобы нетехнические редакторы могли разрешать конфликты без изучения git-команд.

Шаг 5: Коммит и Push

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

Как это выглядит на практике

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

С инструментом односторонней синхронизации одна правка перезаписывает другую. С Content Ledger:

1. Push разработчика создаёт удалённое изменение (новый коммит на стороне git)
2. Сохранение писателя создаёт локальную запись в реестре (новая мутация на стороне веб)
3. Синхронизация запускается, обнаруживает, что оба изменения касаются одной страницы
4. Родительские хеши расходятся — это настоящий конфликт
5. Страница помечается, обе версии сохранены
6. Писатель видит уведомление: «У этой страницы конфликт синхронизации» с представлением диффа
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-синхронизации

Если вы хотите попробовать это с собственным репозиторием:

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

Руководство по интеграции с Git охватывает полную настройку, включая конфигурацию SSH-ключей, стратегии ветвления и настройку интервала синхронизации.

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