~tardypad/git-dot

Output internal Git graph to Graphviz's DOT language

#3 Output local HEAD

~tardypad commented on git-dot todo

a day ago

60deb04 Introduce GlobalId functions

~tardypad pushed to ~tardypad/git-dot git

a day ago
View project feed  RSS 

#git-dot

Output Git content in Graphviz's DOT language.

#Design

The usage of the DOT output is left to external tools supporting the language, for example:

  • visualize the graph in an image using Graphviz tools
  • display animated graphs in a web browser using d3-graphviz
  • further process the graph object using pydot

example

This tool is mostly meant for educational purpose:

  • In case you're giving a training, the trainees should be able to use their regular development platform of choice. Installing must then be super easy, just by using a binary file.

  • To explain the Git internals, it's necessary to show the trees and blobs. Thus, all types of Git objects should be allowed to be displayed.

  • Explaining Git is better done visualizing smaller and simpler repositories. The tool is then not intended to be used on big repositories with many objects and references. No effort is done on optimizations for such use case.

See the alternatives file for similar tools with their limitations and extras.

#Setup

Runtime dependencies:

  • git
    Version equal or newer than 2.6.0 (released in 2015).
    This is when "git cat-file" learned the "--batch-all-objects" option.

Build dependencies:

  • go
  • scdoc (optional, used for man pages)
# build all
make

# build executable only
make git-dot

# build documentation only
make doc

# run test suite
make check

#Default display

Objects: squarish and cold color
References: roundish and warm color

type representation
annotated-tag annotated-tag
blob blob
branch branch
commit commit
lightweight-tag lightweight-tag
tree tree

#Tips

  • Depending on the background, you may want to change the colors with --theme
  • To further process the graph, better use the --bare option to not include any styling in the output
  • By default all types of nodes are in the output, select only the ones you want with --nodes
  • If you cannot easily recognize what each node is, use --annotate to add the type of node in the display
  • By default unreachable objects are not in the output, use --unreachable to include them. They get displayed with a dashed border by default.
  • The tests contain interesting cases to look at

See the full information of options in the documentation.