Git branching diagrams using PlantUML

Learning Microsoft Visio, then joining a diagrams.net company, then having to edit a legacy diagram in Lucidchart was the last straw. From now on, I would invest in diagrams as code and code my diagrams in a text editor.

Of course, this only works if the choice of tool is powerful enough to prevent the kind of switching from framework to framework that inspired the initial switch to code-based tools. So recently when I had to draw git branching diagrams, I ran into a limitation of PlantUML, my weapon of choice.

Unlike some other diagrams-as-code frameworks, PlantUML does not explicitly support git branching diagrams. My initial attempts to illustrate the benefits of a rebase before a squash-and-merge were disappointing:

@startuml
circle c0
circle c1
circle c2
circle c3
circle bob1
circle bob2
c2 -left> c1
c1 -left> c0
c3 -left> c2
bob1 -up> c0
bob2 -left> bob1
bob2 -down> c1
@enduml

The sad circles staring at me from the screen drove me to cast down my beloved PlantUML. Could I find solace in the arms of gitgraph.js?

var gitgraph = new GitGraph({
  template: "metro", 
  orientation: "vertical",
  author: "John Doe",
  mode: "extended"
});
var develop = gitgraph.branch("development"); 
develop.commit("ABBA-01: Add button");
var bob = gitgraph.branch("BOB-001");
bob.commit({
  message: "Touch file V",
  author: "Bob"
});
bob.commit({
  message: "Touch file W",
  author: "Bob"
});
develop.commit("AKKA-02: Add carousel");
var alice = develop.branch({
  name: "ALI-001",
  author: "Alice"
});
bob.commit({
  message: "Touch file X",
  author: "Bob"
});
bob.merge(develop, "BOB-001: My feature");
alice.commit({
  message: "Touch file Y",
  author: "Alice"
});
alice.commit({
  message: "Touch file X",
  author: "Alice"
});
alice.merge(
  develop, "ALI-001: Another feature"
);

Pretty good, but PlantUML was not far from my thoughts.

Using a sequence diagram

Turns out a sequence diagram can have participants that can be used to illustrate branches:

While we don’t get circles to represent commits like the heroic gitgraph, we can use `hnote` hexagons to achieve something similar. The PlantUML code is below:

@startuml

participant "development" as dev
participant "BOB-123" as bob
participant "ALI-123" as ali

hnote over dev : DAV-123 Darryl's feature
dev -> bob : bob branches off dev
activate bob
hnote over bob : Touch file W
hnote over bob : Touch file X
hnote over dev : CHA-123:Charlie's feature
dev -> ali : alice branches off dev
activate ali
bob -> dev : squash and merge
destroy bob
hnote over dev : BOB-123 Bob's feature
hnote over ali : Touch file X
hnote over ali : Touch file Y
ali -> dev : squash and merge
destroy ali
hnote over dev : ALI-123 Alice's feature

@enduml

Update for 2023

A user biAji has informed me that there is experimental PlantUML support for git branching diagrams. Following the instructions here, you can dump a log using:

git log --all --graph --decorate=short --abbrev-commit --oneline

And then enclose the output in @startgit and @endgit :

@startgit
* a0f65180 (origin/cds/issue700) Layered: Clarified code. #700
* 23a9f435 Layered: Fix wrong hierarchy handling. #700
| * 9037d534 (HEAD -> master, origin/master) Build: Properly sign Maven artifacts. #722
|/
* 91fc1c7b Build: Mount Jenkins home. #722
* 4fe6df1e Build: Add HOME env var to maven container. #722
@endgit

The generated diagram will look like this:

Reference:

https://forum.plantuml.net/5184/generate-git-graph