Руководство по синтаксису диаграмм GitGraph в Mermaid.js

Диаграмма GitGraph — это специализированный компонент визуализации, используемый разработчиками, командами DevOps и техническими писателями для четкой передачи стратегий ветвления Git, управления выпусками и рабочих процессов разработки. Интегрированная нативно в Mermaid.js, gitGraphдвигатель использует декларативную последовательную модель временной шкалы. Это позволяет напрямую отображать реальные команды терминала на точную визуальную временную шкалу без необходимости ручной обработки изображений.

Понимание матрицы временной шкалы GitGraph

В отличие от свободных диаграмм потоков системы, диаграмма GitGraph следует строгой последовательной логике порядка возникновения, моделируя реальные рабочие пространства системы контроля версий:

• Автоматическое создание корневой ветки: Каждое рабочее пространство диаграммы при инициализации автоматически создает основную временную шкалу корневой ветки. По умолчанию эта шкала называется main, и все последующие действия отслеживаются относительно нее, если не создана чистая альтернативная ветвь.
• Приоритет порядка: Элементы отображаются по хронологической оси слева направо в зависимости от порядка вставки команд в файл исходного кода.

Базовая структура синтаксиса

Каждая временная шкала начинается с ключевого слова в формате camelCase gitGraph ключевое слово объявления. За ним следует последовательный столбец перечисления атомарных команд выполнения, таких как коммиты, переключения и слияния.

gitGraph
  commit
  commit
  branch feature-login
  checkout feature-login
  commit
  checkout main
  merge feature-login

Полное руководство по командам Git-действий

Движок компоновки интерпретирует конкретные команды действий в нижнем регистре для изменения толщины линий, разделения треков или сливания конечных точек по холсту рабочей области.

Расширенная функция: Типы коммитов и настройка тегов

Чтобы различать обычные патчи, откаты системы или крупные релизы, вы можете назначить явныйтип и тег строковый модификатор внутри блока аргументов с использованием свойств в формате json-подобных пар ключ-значение.

Поддерживаемые классификации форм коммитов:

• тип: ОБЫЧНЫЙ: По умолчанию. Отображается как заполненный сплошной круговой узел вдоль линии временной шкалы.
• тип: ОБРАТНЫЙ: Выделяет архитектурный или программный откат. Отображается как пересеченный сплошной круговой узел ($X$).
• тип: ВЫДЕЛЕНИЕ: Привлекает внимание к критическим структурным изменениям или исправлениям безопасности. Отображается как вытянутый заполненный прямоугольный блок.

gitGraph
  commit id: "Инициализация"
  commit type: HIGHLIGHT id: "Исправление-безопасности" tag: "v1.0.1"
  commit type: REVERSE id: "Откат-функции-X"

Расширенная функция: Логика выборки и строгие ограничения

Команда cherry-pick команда копирует конкретный изолированный узел с другой ветки временной шкалы на текущую активную ветку. Чтобы выполнить cherry-pick без ошибок компиляции, необходимо соблюдать следующие строгие требования к проверке рабочей среды:

• Ограничение исключения: Целевой идентификатор коммита, который вы выбираете, *не должен* уже существовать на ветке, которую вы в данный момент отслеживаете.
• Предварительная история: Текущая активная линия ветки должна содержать хотя бы один действительный узел коммита до вызова действия cherry-pick.
• Требование родительского узла слияния: Если вы выбираете узел слияния, вы должны явно передать строку идентификации непосредственного прямого родительского узла с помощью блока модификатора parent: "хэш" модификатора.

gitGraph
  commit id: "настройка"
  branch staging
  checkout staging
  commit id: "патч-функции"
  checkout main
  commit id: "базовая-версия"
  cherry-pick id: "патч-функции"

Расширенная функция: Конфигурации параметров заголовка

Вы можете точно настроить глобальные визуальные поведения (например, переключение меток ветвей, изменение индексов строк или стекирование временных шкал), объявив блок директивы конфигурации%%{init: { 'logLevel': 'debug', 'theme': 'default' , 'config': { 'gitGraph': { ... } } } }%% блок директивы конфигурации в самом начале вашего скрипта графика.

Матрица настраиваемых параметров

Реальный чертеж: производственная линия управления выпусками Git-Flow для корпоративного использования

Этот всесторонний корпоративный чертеж демонстрирует стандартную производственную линию выпуска. Он переопределяет параметры конфигурации для переименования основной полосы в trunk, устанавливает фиксированную иерархию порядка ветвей, использует несколько полос ветвей (develop и feature-auth), выполняет слияния, применяет пользовательские метки и развертывает коммиты с высоким приоритетом и выделенными формами.

%%{init: { 'gitGraph': { 'mainBranchName': 'trunk', 'showCommitLabel': true } } }%%
gitGraph
  commit id: "Initial-Core" tag: "v1.0.0"
  commit id: "Setup-CI"
  branch develop
  checkout develop
  commit id: "Sprint-1-Base"
  branch feature-auth
  checkout feature-auth
  commit id: "JWT-Logic"
  commit id: "MFA-Logic" type: HIGHLIGHT
  checkout develop
  merge feature-auth id: "Merge-Auth"
  commit id: "Beta-Compiled"
  checkout trunk
  merge develop id: "Release-Prod" tag: "v2.0.0"

Распространённые ошибки синтаксиса и системные ограничения

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

• Ошибки, связанные с регистром символов: Основное объявление инициализации должно быть написано в явном camelCase как gitGraph. Написание его полностью в нижнем регистре как gitgraph вызовет сбой компилятора при разборе.
• Идентификаторы без кавычек: При передаче пользовательских параметров коммита (например, id: core_init), значения, содержащие дефисы, пробелы или точки, *должны* быть заключены в двойные кавычки. Пропуск блоков кавычек приведёт к потере ошибок проверки при компиляции.
• Недопустимые цели перехода: Вызов перейти к ветке branch_name действие над строковым идентификатором, который не был инициализирован заранее с помощью ветка branch_name команда мгновенно нарушит построение графа.
• Коллизии порядка ветвей: При использовании порядок тег конфигурации на ветках, убедитесь, что несколько дорожек не сопоставляются одинаковым целым числам, если вы не хотите, чтобы дорожки на холсте перекрывались. Держите номера дорожек веток уникальными.
• Ошибки разделения пробелами: Убедитесь, что при разделении свойств внутри матриц параметров в скобках существуют четкие пробелы между аргументами (например, используйте id: "1", type: HIGHLIGHT). Пропуск недостающих запятых или пробелов может вызвать исключения при разборе.