Git is a powerful tool, sometimes hard to handle.

Gitgraph.js is a simple JavaScript library which is meant to help you visually presenting git branching stuff like a git workflow, a tricky git command or whatever git tree you'd have in mind.

We use canvas so you don't have to draw your branching illustrations into Photoshop nor Keynote to present something cool. Just code it directly in the browser.

One does not simply illustrate git branching models. This library is the one to draw them all.

This is very straightforward:

1. Download gitgraph.js

With git :

git clone http://github.com/nicoespeon/gitgraph.js.git

With Bower :

bower install gitgraph.js

With npm :

npm install --save gitgraph.js

With your browser : use the CDNjs hosted lib or download the zip / tar.gz source code

2. Prepare the HTML

Load the library:

<script src="js/gitgraph.min.js"></script>

Add the stylesheet:

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

Then, just add a canvas container:

<canvas id="gitGraph"></canvas>

3. Unleash the graph!

Now you're all set, ready to commit and draw a nice git graph in JavaScript \o/

Once files are loaded and canvas is created, you could use the GitGraph object.

var gitgraph = new GitGraph();

Eventually, you could add some options here:

• a specifictemplate: "blackarrow" or "metro" (default)
• the graph orientation:
  • "vertical-reverse"
  • "horizontal"
  • "horizontal-reverse"
  • "vertical" (default)
• the display mode: "compact" for a compact mode, or "extended" (default)
• the elementId: the canvas ID ("gitGraph" is the default)
• a default author for commits

For instance:

var gitgraph = new GitGraph({
  template: "blackarrow",
  reverseArrow: false,
  orientation: "horizontal",
  mode: "compact"
});

Or with another template:

var gitgraph = new GitGraph({
  template: "metro",
  orientation: "horizontal",
  mode: "compact"
});

Let's create our first branch. We give the branch name as a parameter.

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

Now, gitgraph.HEAD is set to master so we can add some commits on the fly and create a new branch:

gitgraph.commit().commit().commit();         // 3 commits upon HEAD
var develop = gitgraph.branch("develop");    // New branch from HEAD
var myfeature = develop.branch("myfeature"); // New branch from develop

// Well, if you need to go deeper…

var hotfix = gitgraph.branch({
  parentBranch: develop,
  name: "hotfix",
  column: 2             // which column index it should be displayed in
});

The develop branch is based from HEAD, which was on master.

It does exactly what you'd expect!

Let's do some custom commits.

Basically, define your commit message:

master.commit("This commit is mine"); // Add a commit on master branch

Or you may want to go a bit further:

develop.commit({
  dotColor: "white",
  dotSize: 10,
  dotStrokeWidth: 10,
  sha1: "666",
  message: "Pimp dat commit",
  author: "Jacky <prince@dutunning.com>",
  tag: "a-super-tag",
  onClick: function(commit) {
    console.log("Oh, you clicked my commit?!", commit);
  }
});

Note that I can choose either to commit on any existing branch, either on the HEAD with gitgraph.commit().

Even though it's not indispensable, we introduced the HEAD principle in Gitgraph.js. Except that our tag is just a reference to a branch for the library.

That way you could eventually checkout to another branch:

master.checkout();

And so create a feature-of-death from the develop branch that way:

develop.checkout();
var featureOfDeath = gitgraph.branch("feature-of-death");

You can merge a branch into another, that simply:

master.merge(develop); // Merge master into develop

But wait, there's more! Customize the merge commit, your way, just like any other commit:

master.merge(develop, "Epic merge commit");
// —> Custom merge message FTW \o/

master.merge(develop, { dotColor: "red" });
// —> The commit will be red, 'coz red is fashion!

master.merge(develop, { message: "New release", tag: "v1.0.0" });
// —> Let's tag this merge commit!

And you can delete a branch to create another one on the same column:

master.delete();

You can handle basic interactions with the generated graph:

gitGraph.canvas.addEventListener( "graph:render", function ( event ) {
  console.log( event.data.id, "graph has been rendered" );
} );

gitGraph.canvas.addEventListener( "commit:mouseover", function ( event ) {
  console.log( "You're over a commit.", event.data );
  this.style.cursor = "pointer";
} );

gitGraph.canvas.addEventListener("commit:mouseout", function (event) {
  console.log( "You just left this commit ->", event.data );
  this.style.cursor = "auto";
});

Or you can be define that per-commit, remember:

develop.commit({
  message: "Pimp dat commit",
  author: "Jacky <prince@dutunning.com>",
  onClick: function(commit) {
    console.log("Oh, you clicked my commit?!", commit);
  }
});

Feeling in control freak mood? Just define your very own template and use it right away:

var myTemplateConfig = {
  colors: [ "#F00", "#0F0", "#00F" ], // branches colors, 1 per column
  branch: {
    lineWidth: 8,
    spacingX: 50,
    showLabel: true,                  // display branch names on graph
  },
  commit: {
    spacingY: -80,
    dot: {
      size: 12
    },
    message: {
      displayAuthor: true,
      displayBranch: false,
      displayHash: false,
      font: "normal 12pt Arial"
    },
    shouldDisplayTooltipsInCompactMode: false, // default = true
    tooltipHTMLFormatter: function ( commit ) {
      return "" + commit.sha1 + "" + ": " + commit.message;
    }
  }
};
var myTemplate = new GitGraph.Template( myTemplateConfig );

Usage is straightforward:

var gitGraph = new GitGraph( {template: myTemplate} );

You get some fuckingood features ideas, or spotted some nasty bugs? Just come and open an issue or a Pull-Request on the project repo.

Looking for some technical documentation? Here you go!

The following use cases have been included for inspiration:

• a generic workflow example
• a gitflow example

You'll find the source code in the repository.

Well, you also can check the source code of this page ;)