Перевод для чтения человеком. Сверен с английским оригиналом ревизии 61e75e9 (на английском). Перевод не является новой редакцией нормативного контракта. Текущая английская страница.
okf setup --source DIR --target NEW_DIR [--files a.md,b/c.md] [--type Guide] [--json]
показывает план создания управляемой копии. --apply --plan-digest SHA256
публикует именно просмотренный план. Запись в источник и замена существующего
целевого каталога запрещены. Поведение init не меняется. Исходный и целевой
каталоги не должны пересекаться; родитель целевого каталога должен существовать.
Символические ссылки и специальные файлы в выбранном дереве блокируют операцию.
По умолчанию рекурсивно выбираются все файлы .md; --files — список точных
Markdown-путей относительно корня, разделённых запятыми, с / в качестве
разделителя каталогов. Повторы, отсутствующие пути, выход за корень,
зарезервированные index.md/log.md и имена транзакций блокируют подготовку.
Явный выбор полезен, когда существующий обычный index.md должен остаться в
источнике. Файлы других форматов не копируются. Локальные ссылки и изображения
должны указывать на выбранный Markdown или якоря; ресурсы других форматов,
каталоги, отсутствующие или невыбранные файлы, строки запроса, блоки и встроенный
HTML, неподдерживаемые схемы URI блокируют публикацию. Ссылки HTTPS/HTTP,
mailto и локальные якоря сохраняются побайтово. Ссылки не переписываются.
Существующие корректные метаданные и байты документа сохраняются точно.
При отсутствии type требуется явный непустой --type; заданный тип добавляется
как строка YAML в кавычках без изменения существующих байтов YAML, тела и
неизвестных метаданных. Существующий некорректный type блокирует операцию,
а не перезаписывается. Незакрытый или некорректный YAML и повторяющиеся ключи
блокируют операцию. Никакие метаданные, кроме типа, не выводятся автоматически;
происхождение, проверка, актуальность и статус не выдумываются. Индексы создаются
существующим генератором индекса набора с корневым объявлением
okf_version: "0.2". Общий разборщик и валидатор проверяют весь подготовленный набор.
Для просмотра и применения JSON представляет один и тот же версионируемый
объект: source и target — абсолютные пути; files — отсортированные пути с SHA256
исходных и выходных файлов; diagnostics — отсортированные объекты с устойчивыми
code/path/message; applicable показывает отсутствие блокирующих причин.
Контрольная сумма плана вычисляется по каноническому JSON параметров, файлов и
диагностики и связывает выбранные байты, пути, политику и целевой каталог.
При применении перечень и байты источника читаются заново. Любое несовпадение
контрольной суммы означает изменение источника или плана и блокирует публикацию.
Повтор после успеха считается коллизией: выберите новый каталог и снова
просмотрите план. JSON плана не принимается как доверенный источник данных.
Ограничения: 1 000 выбранных документов, 2 MiB на документ, 16 MiB суммарных
байтов исходных документов; молчаливого усечения нет. Отмена проверяется при
обходе, разборе, подготовке и непосредственно перед публикацией. Ошибки до
атомарного переименования без замены удаляют временный соседний каталог;
частично опубликованного набора нет. Отмена, обнаруженная после публикации,
не может отменить уже зафиксированный набор. Ошибка fsync родительского каталога
сообщает published: true вместе с ошибкой, чтобы вызывающий код не предполагал
откат. Файловый источник должен оставаться неизменным во время каждого чтения;
перед публикацией применение снова проверяет перечень. Ни один процесс не может
гарантировать защиту от параллельного изменения источника после последнего чтения.
Содержимое пассивно и никогда не исполняет команды.