Create Your Own Git Diagrams

 

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:

---

How To Make Your Own

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 
      % HEAD reference 
      \gitHEAD 
        {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.

See also here for a StackOverflow discussion.

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

---

If you want to learn more about git, read my book Learn Git the Hard Way, available at $8:

---

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

---