Gitgraph.js

(03 November, 2013)

A JavaScript library, git trees, workflows modelisation... and a bit of Georges Michael.

The problem

Few time ago I was writing a post about git workflows. I wish I could use some illustration to explicit my thoughts at this time.

The git-flow already provided a nice illustration of the big picture for this workflow. But the GitHub flow didn’t.

Hopefully, @nvie gave its Keynote source and, hopefully, I’ve got Keynote. Therefore I designed the second illustration myself, exported it and then get an image to insert in my post.

It was not a difficult operation, as long as you get the correct tools. But this is frustrating:

  • what if I want to do a little update?
  • what if I want to change the whole design?
  • what if I want to add some interaction?
  • what if I want to learn saxophone?

The solution

I wish I could find a nice little JavaScript library to design on-the-go graphs to illustrate my git worflows.

But, as we didn’t find anything convincing enough, @fabien0102 and I decided to develop our own solution : GitGraph.js !

Our guidelines are the following :

  • simple and intuitive API
  • flexibility and robustness of the result output
  • customisable design

The project reached a convincing state, stable enough to meet our first requirements. And so we released v1.0.0 and we’ll scrupulously follow Semver, promise!.

Installation

Different solutions are available:

Setting up

The set up process is dead easy.

Start adding the JavaScript (preferably before </body>) :

<script type="text/javascript" src="js/gitgraph.min.js"></script>

Then add the CSS (preferably before </head>) :

<link rel="stylesheet" type="text/css" href="css/gitgraph.css" />

Then, prepare some <canvas>, identified for GitGraph.js use :

<canvas id="my-first-gitgraph"></canvas>
<!-- some HTML here (...) -->
<canvas id="another-graph-here"></canvas>

Here we go!

Usage - Some examples

Using the library is straightforward : you just need to create a new GitGraph for each canvas, then to draw the desired graph.

Some parameters are customisable when you create your graph:

  • the desired template: "blackarrow" or "metro" (default)
  • the graph orientation: "vertical-reverse", "horizontal", "horizontal-reverse" or even "vertical" (default)
  • the display mode: "compact" to hide commit messages, or "extended" (default, only with a "vertical" display for now)
  • the targetted canvas ID ("gitGraph" is the default)
  • A default author for commits messages

And so we create our very first graph this way:

var myGitGraph = new GitGraph({
  elementId: "my-canvas"
});

Then we add some branches:

var master = myGitGraph.branch("master");

A bunch of commits:

myGitGraph.commit().commit().commit(); // 3 commits upon HEAD

Let’s create a new branch and add few commits:

var develop = myGitGraph.branch("develop");
develop.commit(); // This commit will be on `develop`

Let’s do whatever we want:

// A new `feature` branch from `develop`
var myFeature = develop.branch("myFeature");

// A custom commit
myFeature.commit({
  dotColor: "white",
  dotSize: 10,
  dotStrokeWidth: 10,
  sha1: "666",
  message: "Pimp dat commit",
  author: "Jacky <prince@dutunning.com>"
});

// Merge our feature branch back into `develop`
myFeature.merge(develop, "Epic merge commit");

// Well we don't want to use it again, let's delete the old feature branch now
myFeature.delete();

The idea is to adapt the library to your needs so it could be intuitive.

There is still a lot of features to implement and bugs to correct. Please give us some feedbacks if you try it, that would be awesome =)

Usage - The result

Here are some basic use cases that could already be answered with the library.

This JavaScript:

  var blackarrowSolution = new GitGraph( {
    elementId: "blackarrow-solution",
    orientation: "vertical",
    template: "blackarrow",
    author: "Nicolas Carlo <nicolascarlo.espeon@gmail.com>"
  } );

  var master = blackarrowSolution.branch( "master" );
  blackarrowSolution.commit( "This is a commit" )
    .commit( "And here's another one!" )
    .commit( );

  var develop = master.branch( "develop" );
  develop.commit( "My first commit on develop." );

  var feature = develop.branch( "feature" );
  feature.commit( "This is a mandatory feature" )
    .commit( )
    .commit( );
  develop.commit( "Meawhile, we commit on develop..." );
  feature.merge( develop, "Merged into develop" );
  feature.delete( );

  develop.commit( "Add some commit here..." ).commit( );
  develop.merge( master, "Here we merge!" );
  master.commit( ).commit( );

Will produce the following output:

While this code:

  var metroSolution = new GitGraph( {
    elementId: "metro-solution",
    orientation: "horizontal"
  } );

  var master = metroSolution.branch( "master" );
  metroSolution.commit( ).commit( ).commit( );

  var develop = master.branch( "develop" );
  develop.commit( ).commit( );

  develop.merge( master, "Here we merge!" );
  master.commit( ).commit( );

Will output this graph:

The project

  Our project is open-source, available on GitHub : https://github.com/nicoespeon/gitgraph.js

Feel free to add an issue for any remark / suggestion / correction you’d have to do, or even to contribute more deeply. A technical documentation for the source code is available. A much more functional one is already considered, with concrete examples and use cases.

The project use the MIT license, which is simple and permissive.

  Let's have a look to the website for more information about the library: gitgraphjs.com.

Hey and what about sax?

I was afraid you wouldn’t ask. Thereupon I leave you with some Georges Michael tune \o/