Войти
Начать бесплатно

Gitgraph Diagrams (диаграммы Gitgraph)

  • Git Graph - графическое представление коммитов git и действий (команд) git в различных ветвях.
  • Данные диаграммы удобны разработчикам и командам DevOps для обмена своими стратегиями ветвления Git. Например, это облегчает визуализацию того, как работает git flow.



  • В Mermaid поддерживаются основные операции git, такие как:
    1. commit : Представляет новую фиксацию в текущей ветке.
    2. branch : Для создания и переключения на новую ветку, устанавливается в качестве текущей ветки.
    3. checkout : Для проверки существующей ветки и установки ее в качестве текущей ветки.
    4. merge : Для объединения существующей ветки с текущей веткой.
  • Имена сущностей часто пишутся с заглавной буквы. хотя общепринятого стандарта не существует, и в Mermaid этого не требуется.

Синтаксис диаграммы
  • Синтаксис диаграммы следует декларативному подходу, при котором каждая фиксация отображается на временной шкале на диаграмме в порядке ее появления/присутствия в коде. По сути, он следует порядку вставки ветви для каждой команды.
  • Первоначально, необходимо установить тип диаграммы, используя ключевое слово gitgraph. Оно сообщает, что необходимо сделать gitgraph и соответствующим образом проанализировать код диаграммы.
  • Каждая диаграмма инициализируется основной ветвью. Поэтому, если другая ветка не будет создана, по умолчанию коммиты будут отправляться в основную ветку. Это связано с работой git, где в начале всегда создается основная ветвь (ранее называлась главная ветвь).
  • По умолчанию основная ветвь устанавливается как текущая ветвь.
  • Для регистрации фиксации в текущей ветке используется ключевое слово commit. В примере ниже показано, как это работает:
  • Обратите внимание на предложенный пример, где можно заметить основную ветку по умолчанию вместе с тремя коммитами.
  • Кроме того, по умолчанию, каждой фиксации присвоен уникальный и случайный идентификатор. В Mermaid можно изменить случайный идентификатор на необходимый.



Добавление пользовательского идентификатора фиксации



  • Для данного коммита можно указать пользовательский идентификатор во время его объявления, используя атрибут id, за которым следует двоеточие : и ваше пользовательское значение в кавычках ““. Например, идентификатор фиксации your_custom_id.

Изменение типа фиксации
  • В Mermaid фиксация может быть трех типов, которые немного отличаются на диаграмме:
    1. NORMAL: Тип фиксации по умолчанию. Представлен сплошным кругом на диаграмме.
    2. REVERSE : Для того, чтобы подчеркнуть фиксацию как обратную фиксацию. Представлен на диаграмме пересеченным сплошным кругом.
    3. HIGHLIGHT : Для того, чтобы выделить конкретную фиксацию на диаграмме. Представлен заполненным прямоугольником на диаграмме.
  • Для данного коммита можно указать его тип во время введения, используя атрибут type, за которым следует двоеточие : и параметр требуемого типа, описанный выше.

Если тип фиксации не указан, по умолчанию выбирается NORMAL

  • В примере представлено использование различных вариантов фиксации:



Добавление тегов



  • Для данного коммита существует возможность оформления в виде тега, аналогично концепции тегов или версии выпуска в git world.
  • Также можно прикрепить пользовательский тег во время установления фиксации, используя атрибут tag, за которым следует двоеточие : и пользовательское значение в кавычках ““. Например: тег фиксации your_custom_tag.

Создание новой ветки



  • В Mermaid, для создания новой ветки, необходимо использовать ключевое слово branch. Также необходимо указать название новой ветки. Имя должно быть уникальным и не должно принадлежать существующей ветке.
  • Когда Mermaid считывает ключевое слово branch, то создается новая ветвь и устанавливается в качестве текущей ветви. Эквивалентно созданию новой ветки и проверки ее в Git world.
  • Обратите внимание, в этом примере, как диаграмма начата с основной ветки по умолчанию и добавления к ней двух коммитов. Затем создана ветка разработки, и все последующие коммиты помещаются в ветку разработки, поскольку она стала текущей веткой.

Контроль существующей ветки
  • В Mermaid, чтобы переключиться на существующую ветку, используется ключевое слово checkout. Также необходимо указать название существующей ветви. Если ветвь с заданным именем не найдена, это приведет к ошибке консоли.
  • Когда Mermaid считывает ключевое слово checkout, он находит данную ветвь и устанавливает ее в качестве текущей ветви. Это эквивалентно проверке ветки в Git world.
  • Пример использования: разработка оформления заказа.
  • В этом примере, посмотрите как работа начата с основной ветки по умолчанию и добавления к ней двух коммитов. Затем создана ветка разработки, поскольку она стала текущей веткой. После этого использовалось ключевое слово checkout, чтобы установить текущую ветку в качестве основной, и все последующие коммиты регистрируются в текущей ветке, т.е. main.


Слияние двух ветвей
  • В Mermaid, для объединения или присоединения к существующей ветке, необходимо использовать ключевое слово merge. Также необходимо указать имя существующей ветки для слияния.
  • Если ветвь с заданным именем не найдена, это приведет к ошибке консоли. Кроме того, можно объединить только две отдельные ветви и нельзя объединить ветку саму с собой. В таком случае выдается сообщение об ошибке.
  • Когда Mermaid считывает ключевое слово merge, то находит данную ветвь и ее головную фиксацию (последнюю фиксацию в этой ветви) и соединяет ее с головной фиксацией в текущей ветви. Каждое слияние приводит к фиксации слияния, представленной заполненным двойным кругом.
  • В этом примере посмотрите, как начата диаграмма с основной ветки по умолчанию и добавления к ней двух коммитов. Затем создана ветка разработки, и все три коммита впоследствии помещаются в ветку разработки, поскольку она стала текущей веткой.
  • После этого использовано ключевое слово checkout, для установления текущей ветки в качестве основной, и все последующие коммиты регистрируются в текущей ветке, т.е. main.
  • Затем, объединяется ветка разработки с текущей основной веткой, что приводит к фиксации слияния. Поскольку текущая ветвь на данный момент все еще является основной, последние два коммита регистрируются на ней.



Cherry Pick коммита из другой ветки
  • Подобно тому, как git позволяет выбирать фиксацию из другой ветки в текущую ветку, Mermaid также поддерживает эту функциональность. Существует возможность выбрать фиксацию из другой ветки, используя ключевое слово cherry-pick.



  • Для использования ключевого слова cherry-pick, необходимо указать идентификатор с помощью атрибута id, за которым следует двоеточие : и желаемый идентификатор фиксации в кавычках ””. Например: cherry-pick id: "your_custom_id".
  • Новый коммит, создается в текущей ветке и визуально выделяется на диаграмме вишенкой и тегом, отображающим идентификатор коммита, из которого он был выбран.
  • Здесь следует отметить несколько важных правил:
  1. Необходимо указать идентификатор для существующего коммита, который будет выбран из списка. Если указанный идентификатор фиксации не существует, это приведет к ошибке. Для этого используйте формат commit id:$value для объявления коммитов.
  2. Данная фиксация не должна существовать в текущей ветке. Выбранная cherry pick фиксация всегда должна быть ветвью, отличной от текущей ветви.
  3. Текущая ветвь должна иметь хотя бы одну фиксацию, прежде чем появится возможность выбрать cherry, в противном случае - это вызовет ошибку сброса.

Параметры конфигурации, специфичные для Gitgraph
  • В Mermaid существует возможность настроить следующие параметры:
  • showBranches: логическое значение, по умолчанию - true (истина). Если установлено значение false (ложь), ветви не отображаются на диаграмме.
  • showCommitLabel: логическое значение, по умолчанию - false, метки фиксации не отображаются на диаграмме.
  • mainBranchName: строка, по умолчанию - ismain. Имя ветви по умолчанию - default/root.
  • mainBranchOrder: позиция главной ветки в списке веток, значение по умолчанию = 0, что означает, что по умолчанию основная ветвь является первой в порядке.
  • Ниже, рассмотрим их более подробно.

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

Скрытие названий ветвей и строк (параметр showBranches)
  • В некоторых случаях, требуется скрыть названия ветвей и линий на диаграмме. Это можно сделать, используя ключевое слово showBranches. По умолчанию, его значение равно true, но возможно установление для него значения false с помощью директив.



  • На диаграмме применение этого параметра будет выглядеть, так как показано на изображении ниже.



Расположение меток фиксации: повернутое и горизонтальное (параметр rotateCommitLabel)
  • Mermaid поддерживает два типа компоновки меток фиксации. Макет по умолчанию повернут, это означает, что метки размещаются ниже круга фиксации, повернутого на 45 градусов для лучшей читаемости. Это удобно для коммитов с длинными метками.
  • Другой вариант - горизонтальный, что означает, что метки размещаются ниже круга фиксации, центрированного по горизонтали, и не поворачиваются. Это удобно для коммитов с короткими метками.
  • Можно изменить расположение меток фиксации, используя ключевое слово rotateCommitLabel в директиве. По умолчанию установлено значение true, что означает поворот меток фиксации.



  • На диаграмме применение этого параметра будет выглядеть, так как показано на изображении.



  • Пример использования горизонтальной метки фиксации:



  • На диаграмме применение этого параметра будет выглядеть, так как показано на изображении ниже.



Скрытие меток фиксации (параметр showCommitLabel)
  • Иногда может потребоваться скрыть метки фиксации на диаграмме. Это можно выполнить, используя ключевое слово showCommitLabel. По умолчанию его значение равно true, но изменить значение на false с помощью директив.



  • На диаграмме применение этого параметра будет выглядеть, как изображено ниже.



Настройка названия основной ветви (параметр mainBranchName)
  • В некоторых случаях, необходима настройка имени основной ветви. Это можно сделать, используя ключевое слово mainBranchName. По умолчанию его значение равно main, но его можно изменить, установив его в любую строку, используя директивы.
%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showBranches': true, 'showCommitLabel':true,'mainBranchName': 'MetroLine1'}} }%%
      gitGraph
        commit id:"NewYork"
        commit id:"Dallas"
        branch MetroLine2
        commit id:"LosAngeles"
        commit id:"Chicago"
        commit id:"Houston"
        branch MetroLine3
        commit id:"Phoenix"
        commit type: HIGHLIGHT id:"Denver"
        commit id:"Boston"
        checkout MetroLine1
        commit id:"Atlanta"
        merge MetroLine3
        commit id:"Miami"
        commit id:"Washington"
        merge MetroLine2 tag:"MY JUNCTION"
        commit id:"Boston"
        commit id:"Detroit"
        commit type:REVERSE id:"SanFrancisco"
  • Применение этого параметра на диаграмме, изображено ниже.



Установление порядка ветвей (параметр order)
  • В Mermaid, по умолчанию, ветви отображаются в порядке их определения или появления в коде диаграммы.
  • Иногда может понадобиться настроить порядок расположения ветвей. Существует возможность выполнить это, используя ключевое слово order рядом с определением ветви. Установить его можно на положительное число.
  • Mermaid следует заданному порядку приоритета ключевого слова order:
  1. Основная ветвь всегда отображается первой, поскольку она имеет значение порядка по умолчанию 0. (если только ее порядок не изменен и не изменен с 0 с помощью ключевого слова mainBranchOrder в конфигурации).
  2. Далее все ветви без установленного порядка отображаются в порядке их появления в коде диаграммы.
  3. Затем, все ветви с настроенным параметром отображаются в порядке их написания.
  • Для полного контроля порядка всех ветвей, необходимо установить их порядок.
  • Обратите внимание на диаграмму: все ветви расположены в заданном порядке.



  • Обратите внимание на диаграмму, здесь все ветви без заданного порядка визуализированы в порядке их введения.
  • Затем изображается ветвь test4, так как порядок равен 1.
  • Затем изображается основная ветвь, так как порядок равен 2.
  • Наконец, test1 изображается, так как ее порядок равен 3.
%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showBranches': true, 'showCommitLabel':true,'mainBranchOrder': 2}} }%%
      gitGraph
      commit
      branch test1 order: 3
      branch test2
      branch test3
      branch test4 order: 1


Поскольку параметр mainBranchOrder бал изменен на 2, основная ветвь не визуализируется в начале, а следует по порядку.

Темы
  • Mermaid поддерживает множество предопределенных тем, которые вы можете использовать, чтобы найти подходящую для вас.

 Вы можете изменить переменную существующей темы, чтобы запустить свою собственную пользовательскую тему. Подробнее о тематизации вашей диаграммы можно найти здесь.

  • Ниже приведены различные предопределенные параметры темы:
  1. base (базовая тема).
  2. forest (лесная тема).
  3. dark (темная тема).
  4. default (тема по умолчанию).
  5. neutral (нейтральная тема).

Примечание: Для изменения темы, можно использовать либо вызов инициализации, либо директивы. В примерах ниже, показано применение синтаксиса и его визуализация.

Базовая тема (base)



  • Так выглядит базовая тема при визуализации кода.



Forest Theme (лесная тема)



  • На изображении ниже показано применение forest theme.



Тема по умолчанию (Default theme)



  • Использование темы по умолчанию визуализируется, как показано на изображении ниже.




Темная тема (Dark theme)



  • На изображении представлена визуализация темной темы.




Нейтральная тема (Neutral theme)



  • Так выглядит визуализация кода при применении нейтральной темы.



Настройка диаграммы с помощью переменных темы
  • Mermaid позволяет настраивать диаграмму, используя переменные темы, которые определяют внешний вид различных элементов диаграммы.




  • Для наглядности, используется пример диаграммы, в котором значения переменных темы по умолчанию выбираются автоматически.
  • Обратите внимание, как тема по умолчанию используется для настройка цветов ветвей.

Mermaid поддерживает переменные темы для изменения значений по умолчанию до 8 ветвей, т.е. возможно установить цвет/стиль до 8 ветвей, используя переменные темы.

После этого порога, переменные темы повторно используются циклическим образом, т.е. 9-я ветвь будет использовать цвет/стиль 1-й ветви, или ветвь в позиции индекса 8 будет использовать цвет/стиль ветви в позиции индекса 0.

Настройка цветов ветвей
  • Существует возможность настройки цвета ветвей, используя переменные темы git0 - git7. Mermaid позволяет устанавливать цвета для 8 ветвей, где переменная будет определять значение второй ветви, и так далее.

Значения по умолчанию для этих переменных темы выбираются из выбранной темы. Если необходимо изменить значения по умолчанию, то можно использовать вызов initialize для добавления значений пользовательских переменных темы.

  •  В примере показано изменение значения по умолчанию для переменных git0 на git3.



Настройка цветов меток ветвей
  • Можно настроить цвета меток ветвей, используя переменные темы gitBranchLabel0 - gitBranchLabel7. Mermaid позволяет устанавливать цвета до 8 ветвей, где переменная gitBranchLabel0 будет определять значение метки первой ветви, а переменная gitBranchLabel1 будет определять значение метки второй ветви и так далее.
  • В примере ниже показано изменение значения по умолчанию для переменных gitBranchLabel0 на gitBranchLabel2.



  • Здесь можно видеть, что цвета и стили branch8 и branch9 выбираются из ветви в позиции индекса 0 (main) и 1(branch1) соответственно, т.е. переменные темы ветви повторяются циклически.



Настройка цветов фиксации
  •  Можно настроить фиксацию с помощью переменных темы commitLabelColor и commitLabelBackground для изменения цвета метки фиксации и цвета фона соответственно.



Настройки размера шрифта метки фиксации
  1. Также существует возможность настроить фиксацию, используя переменные темы commitLabelFontSize для изменения размера шрифта метки фиксации.
  2. Обратите внимание, как изменился размер шрифта метки фиксации.



Настройка размера шрифта метки тега
  • Можно настроить фиксацию с помощью переменных темы tagLabelFontSize для изменения размера шрифта метки тега.



Настройка цвета тегов
  • Помимо вышесказанного, можно настроить тег, используя переменные темы tagLabelColor, tagLabelBackground и tagLabelBorder для изменения цвета метки тега, цвета фона метки тега и границы метки тега соответственно.



Настройка цвета выделения фиксации
  • Также можно настроить цвета фиксации выделения в зависимости от ветки, в которой она находится, используя переменные темы gitInv0 - gitInv7.
  • Mermaid позволяет устанавливать цвета для фиксации выделения до 8 ветвей, где переменная gitInv0 будет определять значение фиксации выделения первой ветви, gitInv1 будет определять значение метки фиксации выделения второй ветви и так далее.