GitGraph.js

A JavaScript library
to draw pretty git graphs.

Use ⬅️ and ➡️ keys to navigate

Why this library? 🤔

  • To draw git graphs examples that are easy to maintain
  • For presentations, blog posts…
  • … or any use case that implies to render a git graph!

📦 Install GitGraph.js

  • For JS (README): npm i @gitgraph/js
  • For React (README): npm i @gitgraph/react

Importing the JS library

<!-- Somewhere in the DOM -->
<div id="gitgraph"></div>

import { createGitgraph } from "@gitgraph/js";

const graphContainer = document.getElementById("gitgraph");
const gitgraph = createGitgraph(graphContainer);

Importing the React library

import { Gitgraph } from "@gitgraph/react";

// Now you can use the component =>
<Gitgraph>{(gitgraph) => {}}</Gitgraph>;

👾 Start using gitgraph

const master = gitgraph.branch("master");
master.commit("Init the project");
master
  .commit("Add README")
  .commit("Add tests")
  .commit("Implement feature");
master.tag("v1.0");
const newFeature = gitgraph.branch("new-feature");
newFeature.commit("Implement an awesome feature");
master.commit("Hotfix a bug");
newFeature.commit("Fix tests");
// Merge `newFeature` into `master`
master.merge(newFeature, "Release new version");

The result

👈 👏 🎉

Advanced usage

You can customize the graph with options

// @gitgraph/js − Pass `options` as second param
const gitgraph = createGitgraph(graphContainer, options);

// @gitgraph/react − Provide `options` as props
<Gitgraph options={options}>{(gitgraph) => {}}</Gitgraph>

options.orientation

Default is vertical

options.orientation

With "vertical-reverse"

options.orientation

With "horizontal"

You also have "horizontal-reverse"

options.template

Default is "metro"

options.template

With "blackarrow"

options.template

You can create your own with templateExtend():

const options = {
  template: templateExtend("metro", {
    colors: ["red", "blue", "orange"],
    // …
  }),
};

options.mode

You can opt-in "compact"

It renders commit messages in tooltips

Create branch with options

gitgraph.branch({
  name: "develop",
  style: {
    // Specific style for this branch
  },
});

Create commit with options

master.commit({
  subject: "Add feature",
  body: "More details about the feature…",
  dotText: "❤️",
  tag: "v1.2",
  style: {
    // Specific style for this commit
  },
});

Merge branch with options

master.merge({
  branch: develop,
  fastForward: true,
  commitOptions: {
    // Every valid `options` for a commit
  },
});

Add event listeners on commits

master.commit({
  subject: "Add tests",
  onMessageClick(commit) {
    alert(`Commit ${commit.hash} selected`);
  },
});

But also: onMouseOver, onMouseOut, etc.

Check detailed use-cases 🧐

Thank you 🤗

To our contributors:

List of contributors images

Chromatic QA for helping catching visual regressions.

Do you like George Michael? 🎷