Ever wondered how to create your own git diagrams?

You know, the ones that look like this?

I’ve created a Docker image to allow you to easily create your own.

$docker pull imiell/gitdags The git repo is here. How To Run The examples folder is a good place to start. A good way to get started is to run this: $ git clone https://github.com/ianmiell/gitdags
$cd gitdags/examples$ docker run -v $(pwd):/files imiell/gitdags /convert_files.sh It will convert the *.tex (LaTeX) files into example .png images more or less complex than the one at the top. If you want to learn more about git, read my book Learn Git the Hard Way, available at$8:

To show you how to make your own images, let’s break down this example:

\documentclass[preview]{standalone}
\usepackage{subcaption}
\usepackage{gitdags}
\begin{document}
\begin{figure}
\begin{subfigure}[b]{\textwidth}
\centering
\begin{tikzpicture}
% Commit DAG
\gitDAG[grow right sep = 2em]{
A -- {
C,
B,
}
};
% Branch
\gitbranch
{experimental} % node name and text
{above=of C} % node placement
{C} % target
\gitbranch
{master} % node name and text
{below=of B} % node placement
{B} % target
{below=of master} % node placement
{master} % target
\end{tikzpicture}
\end{subfigure}
\end{figure}
\end{document}

Breaking it down into chunks, the content is framed by what is more or less boilerplate:

\documentclass[preview]{standalone}
\usepackage{subcaption}
\usepackage{gitdags}
\begin{document}
\begin{figure}
\begin{subfigure}[b]{\textwidth}
\centering
\begin{tikzpicture}
[...]
\end{tikzpicture}
\end{subfigure}
\end{figure}
\end{document}

The subcaption package might be used by a more advanced diagram, but is not necessary to this particular one.

Next, the nodes and their links are specified in a \gitDAG section:

\gitDAG[grow right sep = 2em]{
A -- {
C,
B,
}
};

The nodes are linked by a simple pair of dashes. The arrows are put in for you.

The curlies indicate a division into branches, where each line represents one line of development.

If you want to merge two branches together, then you can give them the same name, like this:

A -- {
C -- D,
B -- D,
}

You can ‘grow’ the graph down, up, or left (as well as right, above), and make the separation larger or smaller by changing the value of 2em.

You can also ‘fade them out’ by marking them as ‘unreachable’:

[nodes=unreachable] D -- E

There are four main types of ‘external pointer’ node:

\gittag
\gitremotebranch
\gitbranch
\gitHEAD

The comments on the \gittag example here are mostly self-explanatory, and apply to all four (apart from for \gitHEAD – see below):

\gittag
[v0p1]       % node name
{v0.1}       % node text
{above=of A} % node placement
{A}          % target

The ‘target’ line refers to where the arrow points, and the ‘node placement’ line refers to where the ‘arrow node’ is positioned – it can be above=of or below=of as well as left=of or right=of.

gitHEAD ignores the node text, and just puts HEAD as the text.

Other types of node are available, but there’s no documentation on them that I can find, and literally no mention of them on GitHub anywhere outside the original source. I may try and figure them out later.

Credit

This work is based on the great work of Chris Freeman here.

And of course the original gitdags work here.

Without the above I’d have been floundering in a sea of LaTeX ignorance.

If you liked this post, you might also like these:

Five Key Git Concepts Explained the Hard Way

Ten More Things I Wish I’d Known About bash

Project Management as Code with Graphviz

A Non-Cloud Serverless Application Pattern Using Git and Docker

Power ‘git log’ graphing

8 thoughts on “Create Your Own Git Diagrams”

1. W says:

so you’ve over-engineered (docker) to describe something no one ever does (git diagrams)

what’s the point?

1. I did it for a book, and doing it this way saved me a whole lot of time and hassle, since I could run it easily on multiple servers and save time by using Makefiles. I also train people to use git. To say ‘no one ever does’ this seems a little ignorant.

2. Dear Ian,

You have made my day – I was looking for an easy way to create git diagrams for a while. I didn’t find anything suitable and eventually I gave up.

I used to use LaTeX but never thought about using it for diagrams. Thanks for sharing it!

For my jekyll-powered blog, I ended up creating VM (just Vagrant+VirtualBox based) as well – as setting it up on each machine I have became tedious.