Creating beautiful graphs for teaching git

Explaining git can be a challenging task. For instance, last week I wrote about moving commits to another branch.

To do that, I wanted some kind of visualization. While searching a tool for this job, I noticed that most of them are creating the graph out of some existing git repository. Not what I wanted.

Then I found gitgraph.js. On the first sight, it seemed like a good fit. But damn, why do they draw the arrow pointing in the wrong direction? Not helpful if you want to show some concept and your explaining graph shows the opposite.

Finally, I discovered neat looking graphs produced by a tool named gitDAGs. It is just a package for LaTeX, built on top of TikZ/PGF.

Installation

Since the official repository doesn’t provide installation instructions, I quickly explain how to install gitDAGs on OS X. Chris Freemans Tutorial for installing it on Ubuntu was pretty helpful for me.

First, if you don’t have it yet, install MacTex.

Afterwards, this command should tell you the path for custom packages.

$ kpsewhich -var-value=TEXMFHOME
/Users/<username>/Library/texmf

You need to create the folder structure for LaTeX packages yourself.

$ cd ~/Library
$ mkdir -p texmf/tex/latex
$ cd texmf/tex/latex

To install the needed packages xcolor-solarized and gitdags, simply clone their repositories into the created latex folder.

$ git clone https://github.com/Jubobs/xcolor-solarized.git
$ git clone https://github.com/Jubobs/gitdags.git

After cloning these packages, LaTeX should already be able to see them. You can test this by typing

$ kpsewhich gitdags.sty
/Users/<username>/Library/texmf/tex/latex/gitdags/gitdags.sty

When some path is shown, you are ready to generate beautiful git graphs.

Usage

Head over to the wiki page of gitdags and copy the example into some file. Then, compile with pdflatex and you get the example graph as a pdf file.

For an insight into my workflow, see the following post.

Stay tuned and Happy Easter!