git-draw.sh

#!/bin/sh
# 
# NAME
#   git-draw - draws nearly the full content of a tiny git repository as a graph
# 
# SYNOPSIS
#   git-draw [OPTION]...
#
# PREREQUISITES
#   You don't need graphviz or imagemagick if you use git-draw with certain
#   options.
#
#   - perl
#   - graphviz (http://www.graphviz.org/)
#   - imagemagick (http://www.imagemagick.org)
#
#   If you have apt you can install these with:
#
#     sudo apt-get install perl graphviz imagemagick
#
# DESCRIPTION
#   git-draw is composed of three main steps, where the 2nd and 3rd are just
#   for convenience and are not part of git-draw's core responsibility.
#
#   1) A .dot file describing the repository's content as a graph is created.
#   2) dot (see graphviz) is called to produce an image out of that .dot file.
#   3) display (see imagemagick) is called to display that image.
#
#   As long as you run git-draw from within a git repository, it will graph
#   the repository.   An alternate git repository can be chosen using the 
#   --git-dir and/or --work-dir flags.
#
#   The intention is to help learning Git's basic concepts (references, Git
#   objects, SHA-1 checksum over content as id). Virtually all information
#   concerning Git's basic concepts is contained in the drawing. Thus git-draw
#   is aimed at tiny toy Git repositories and at users with an engineer
#   background, i.e. users which are not scared off by terms like checksum,
#   references aka pointers and graphs.
#
# OPTIONS
#   -h, --help
#     Prints a help message and exits.
#
#   -p, --print-only
#     Only prints the .dot file to STDOUT. Mutually exclusive with
#     --image-only.
#
#   -i, --image-only
#     Only generates an image of the graph, and a .dot file beforehand.
#     Mutually exclusive with --print-only.
#
#   -g, --git-dir
#     Git repository directory to use
#
#   -w, --work-dir    
#     Top level git working directory
#
#   --dot-filename <filename>
#     Name of the dot file to generate
#
#   --image-filename <filename>
#     Name of the image file to generate
#
#   --display-cmd <command>
#     Command to use to display image
#
#   --sha1-length <length>
#     Number of sha1 digits to display in the graph. Must be a number between
#     4 and 40 inclusive.
#
#   --hide-legend
#     Don't display the legend
#
#   --hide-objects
#     Don't display git objects
#
#   --hide-refs
#     Don't display references
#
#   --hide-reflogs
#     Don't display reflogs
#
#   --hide-index
#     Don't display the index
#
#   --hide-commitcontent
#     Hide commit content
#
#   --hide-tagcontent
#     Hide tag content
#
#   --hide-treecontent
#     Hide tree content
#
#   --hide-blobcontent
#     Hide blob content
#
#   --color-scheme <color scheme>
#     Choose color scheme. <color scheme> can be one of: default, set312,
#     spectral11, blues9, brbg11, bupu9, dark28, paired12, pastel19, set19
#
#   --color-commit <color>
#     Set color for commit objects
#
#   --color-tag <color>
#     Set color for tag objects
#
#   --color-tree <color>
#     Set color for tree objects 
#
#   --color-blob <color>
#     Set color for blob objects
#
#   --color-default <color>
#     Set default color
#
#   --orientation <orientation>
#     Change the layout orientation of the graph. Must be one of the
#     following:
#       TB  top to bottom, the default
#       BT  bottom to top
#       LR  left to right
#       RL  right to left
#
# AUTHOR
#   Written by Florian Kaufmann <sensorflo@gmail.com>
#   Modifications by Nathan Doss <nathan.doss@gmail.com>
#
# COPYRIGHT
#   Florian Kaufmann 2014. License GPLv3+: GNU GPL version 3 or later
#   <http://gnu.org/licenses/gpl.html>. This is free software: you are free to
#   change and redistribute it. There is NO WARRANTY, to the extent permitted
#   by law.
# 
# SEE ALSO
#   git(1)

# define color schemes
color_scheme_default_commit="palegreen1"
color_scheme_default_tree="lightyellow"
color_scheme_default_blob="white"
color_scheme_default_tag="white"
color_scheme_default_default="white"

color_scheme_set312_commit="/set312/7"
color_scheme_set312_tree="/set312/6"
color_scheme_set312_blob="/set312/3"
color_scheme_set312_tag="/set312/12"
color_scheme_set312_default="white"

color_scheme_spectral11_commit="/spectral11/8"
color_scheme_spectral11_tree="/spectral11/4"
color_scheme_spectral11_blob="/spectral11/10"
color_scheme_spectral11_tag="/spectral11/5"
color_scheme_spectral11_default="white"

color_scheme_blues9_commit="/blues9/3"
color_scheme_blues9_tree="/blues9/5"
color_scheme_blues9_blob="/blues9/7"
color_scheme_blues9_tag="/blues9/2"
color_scheme_blues9_default="white"

color_scheme_brbg11_commit="/brbg11/3"
color_scheme_brbg11_tree="/brbg11/5"
color_scheme_brbg11_blob="/brbg11/7"
color_scheme_brbg11_tag="/brbg11/9"
color_scheme_brbg11_default="white"

color_scheme_bupu9_commit="/bupu9/2"
color_scheme_bupu9_tree="/bupu9/4"
color_scheme_bupu9_blob="/bupu9/6"
color_scheme_bupu9_tag="/bupu9/8"
color_scheme_bupu9_default="white"

color_scheme_dark28_commit="/dark28/5"
color_scheme_dark28_tree="/dark28/2"
color_scheme_dark28_blob="/dark28/3"
color_scheme_dark28_tag="/dark28/6"
color_scheme_dark28_default="white"

color_scheme_paired12_commit="/paired12/3"
color_scheme_paired12_tree="/paired12/1"
color_scheme_paired12_blob="/paired12/7"
color_scheme_paired12_tag="/paired12/11"
color_scheme_paired12_default="white"

color_scheme_pastel19_commit="/pastel19/3"
color_scheme_pastel19_tree="/pastel19/5"
color_scheme_pastel19_blob="/pastel19/4"
color_scheme_pastel19_tag="/pastel19/6"
color_scheme_pastel19_default="white"

color_scheme_set19_commit="/set19/3"
color_scheme_set19_tree="/set19/5"
color_scheme_set19_blob="/set19/2"
color_scheme_set19_tag="/set19/6"
color_scheme_set19_default="white"

# set defaults
dotfilename=git-draw.dot
imgfilename=git-draw.png
displaycmd=display
sha1length=4
showlegend=1
showobjects=1
showrefs=1
showreflogs=1
showindex=1
showcommitcontent=1
showtreecontent=1
showtagcontent=1
showblobcontent=1
orientation="TB"
export GIT_DIR=$(git rev-parse --git-dir)
export GIT_WORK_TREE=$(git rev-parse --show-toplevel)
colorscheme="default"

# set colors (hack ... got to be a better way)
color_commit=$(eval "echo \${color_scheme_${colorscheme}_commit}")
color_tag=$(eval "echo \${color_scheme_${colorscheme}_tag}")
color_tree=$(eval "echo \${color_scheme_${colorscheme}_tree}")
color_blob=$(eval "echo \${color_scheme_${colorscheme}_blob}")
color_default=$(eval "echo \${color_scheme_${colorscheme}_default}")

# $1 = exit code
print_usage_and_exit() {
  cat <<EOF
Usage: git-draw [options]
  -h|--help                      Print help message & exit
  -p|--print-only                Only print .dot to stdout
  -i|--image-only                Only create an image, and a .dot file beforehand
  -g|--git-dir                   Git repository directory to use
  -w|--work-dir                  Top level git working directory
  --dot-filename <filename>      Name of the dot file to generate
  --image-filename <filename>    Name of the image file to generate
  --display-cmd <command>        Command to use to display image
  --sha1-length <length>         Number of sha1 digits to display
  --hide-legend                  Don't display the legend
  --hide-objects                 Don't display git objects
  --hide-refs                    Don't display references
  --hide-reflogs                 Don't display reflogs
  --hide-index                   Don't display the index
  --hide-commitcontent           Don't display commit content
  --hide-tagcontent              Don't display tag content
  --hide-treecontent             Don't display tree content
  --hide-blobcontent             Don't display blob content
  --color-scheme <color scheme>  Choose color scheme. Can be one of: default,
                                 set312, spectral11, blues9, brbg11, bupu9,
                                 dark28, paired12, pastel19, set19
  --color-commit <color>         Set color for commit objects
  --color-tag <color>            Set color for tag objects
  --color-tree <color>           Set color for tree objects
  --color-blob <color>           Set color for blob objects
  --color-default <color>        Set default color
  --orientation <orientation>    Change the graph orientation.
                                 <orientation> must be one of the following:
                                 TB  top to bottom, the default
                                 BT  bottom to top
                                 LR  left to right
                                 RL  right to left

The primary documentation is at the top of the git-draw script itself.
EOF
  exit $1
}

# TODO
#   -  Layout graph so commit DAG is top-down and on the left, probably using
#      graphviz's ranks.
#   -  Auto-number output files so user can see / compare the different states
#      of the repository was in.
#   -  Optionally use temporary files which the user does not directly see
#   -  Optionally omit drawing the content of all/certain objects/refs so a
#      bit larger than tiny repositories still draw usefully.
#   -  tree objects / reflogs shall fan out graph edges at corresponding line
#      in content
#   -  Amend type cell (top left) and id cell (top right) with the prefix
#      'type=' and 'id=' to be very clear. Optionally turn off with options.
#   -  add a graph title / caption which tells the git command(s) since the
#      last version of the repository content.
#   -  Provide options to choose the tool to display the image outputted by
#      dot.
#   -  Read gitrepository-layou(1) to find out more things which could be
#      displayed
#   -  Draw multiple repos in one image. Usefull to demonstrate distributed git.
#   -  Draw packed objects and refs in a subgraph respectively.
#   -  Allow that the current working directory can be any subdirectory of a
#      git project. Similarly, allow to specify the git repository via command
#      line arguments.

abbreviate_sha1() {
  # BUG: in a blob or commit-msg, would also replace what looks like a sha1
  perl -pe 's/([0-9a-f]{40})/substr(`git rev-parse --short='$sha1length' $1`,0,-1)/eg'
}

ls_all_objects() {
  # unpacked objects
  find $GIT_DIR/objects/ -type f |
    perl -ne 'print "$1$2\n" if m@^.*/([a-f0-9]{2})/([a-f0-9]{38})@' 

  # packed objects
  # note that the .idx is not always present
  find $GIT_DIR/objects/pack/ -iname '*.idx' | while read idxfile; do
    cat $idxfile | git show-index |
      perl -pe 's@^.*?([a-f0-9]{40}).*$@$1@'
  done
}

ls_all_refs() {
  # todo: refs like MERGE_HEAD are still not printed
  git show-ref --abbrev=$sha1length
  cat $GIT_DIR/HEAD | perl -ne '
    m/^(?:ref: )?(.*?)$/;
    if ($1 =~ m/([a-f0-9]{40})/) {
      $idshort = substr(`git rev-parse --short='$sha1length' $1`,0,-1);
    }
    else { $idshort = $1 }
    print $idshort . " HEAD\n";'
}

ls_all_objects_short() {
  ls_all_objects | while read sha1; do
    git rev-parse --short=$sha1length $sha1
  done
}

print_dot_objects() {
  ls_all_objects_short | while read id; do
    dotid="_$id"
    object_type=$(git cat-file -t $id)
    objcontent=$(git cat-file -p $id | abbreviate_sha1 |
      perl -pe 's/([^a-zA-Z0-9\n\r])/\\$1/g; s/(\r?\n)?$/\\l/;')

    case $object_type in
    commit)
      fillcolor="$color_commit"
      if [ $showcommitcontent != 1 ]; then
        objcontent=""
      fi
      ;;
    tag)
      fillcolor="$color_tag"
      if [ $showtagcontent != 1 ]; then
        objcontent=""
      fi
      ;;
    tree)
      fillcolor="$color_tree"
      if [ $showtreecontent != 1 ]; then
        objcontent=""
      fi
      ;;
    blob)
      fillcolor="$color_blob"
      if [ $showblobcontent != 1 ]; then
        objcontent=""
      fi
      ;;
    *)
      fillcolor="$color_default"
      ;;
    esac

    printf %s "  $dotid [fillcolor=\"$fillcolor\", style=\"filled,rounded\", "\
      "label=\"{{obj:$object_type|$id}|$objcontent}\"]"

    # todo: use git's commands to extract the object references
    # BUG: must escape stuff that .dot interprets (\n,\l,\l,|,{},...)
    # BUG(obsolete when using git's cmds): cannot deal with multiple sha1 on one line
    # BUG(obsolete when using git's cmds): in a blob or commit-msg, would also
    #   replace what looks like a sha1
    git cat-file -p $id |
      perl -ne 'print "  '$dotid' -> _" .
        `git rev-parse --short='$sha1length' $1` if /([a-f0-9]{40})/'
  done

  git fsck --cache --unreachable --dangling 2>/dev/null |
   perl -ne 'print "  _" . substr(`git rev-parse --short='$sha1length' $1`,0,-1) .
     " [style=dotted]\n" if /^(?:dangling|unreachable)\b.*?([a-f0-9]{40})/'
}

print_dot_references() {
  ls_all_refs |
    perl -ne '
      if (m@(\S+)\s+(\S+?)$@) {
        $me = $2;
        $other = $1;
        $dotid_me = "_" . (($tmp = $me) =~ s@([^a-zA-Z0-9_])@___@g,$tmp);
        $dotid_other = "_" . (($tmp = $other) =~ s@([^a-zA-Z0-9_])@___@g,$tmp);
        ($otherquoted = $other) =~ s/([^a-zA-Z0-9\n])/\\$1/g;
        ($mequoted = $me) =~ s/([^a-zA-Z0-9\n])/\\$1/g;
        $reftype = "";
        $fillcolor = "gray";
        $configmetadata = "";
        if ($me =~ m@^refs/heads/@) {
          $reftype = ":local branch";
          ($me_short = $me) =~ s@^refs/heads/@@;
          $remote = substr(`git config --get branch\\.$me_short\\.remote`,0,-1);
          $merge = substr(`git config --get branch\\.$me_short\\.merge`,0,-1);
          if ($remote && $merge) {
            if ($remote eq ".") {
              $dotid_merge = "_" . (($tmp = $merge) =~ s@([^a-zA-Z0-9_])@___@g,$tmp);
            } else {
              $dotid_merge_core = $merge;
              $dotid_merge_core =~ s@^refs/heads/@@;
              $dotid_merge_core =~ s@([^a-zA-Z0-9_])@___@g;
              $dotid_remote = (($tmp = $remote) =~ s@([^a-zA-Z0-9_])@___@g,$tmp);
              $dotid_merge = "_refs___remotes___${dotid_remote}___${dotid_merge_core}";
            }
            print "  $dotid_me -> $dotid_merge [style=dotted, color=gray, fontcolor=gray, " .
              "label=\"upstream branch\"]\n";
            $tmp = "remote = $remote\nmerge = $merge\n";
            $tmp =~ s/([^a-zA-Z0-9\n])/\\$1/g; # quote for dot
            $tmp =~ s/\n/\\l/g;                # \l instead \n newline
            $configmetadata = "|$tmp"
          }
        }
        elsif ($me =~ m@^refs/remotes/@) {
          $reftype = ":remote tracking branch";
          $fillcolor = "yellow";
        }
        elsif ($me =~ m@^refs/tags/@) {
          $reftype = ":tag";
          $fillcolor = "lightyellow";
        }
        if ( ($other !~ m/^[a-f0-9]+$/) &&
             0!=system("git show-ref --verify --quiet -- $other") ) {
          print "  $dotid_me [style=filled, fillcolor=red, " .
            "label=\"{{ref$reftype|$mequoted}|" .
            "$otherquoted (referee does not exist)\\l$configmetadata}\"]\n";
        } else {
          if ($me eq "HEAD") {
             $fillcolor="gray30";
             $fontcolorelement = "fontcolor=white, ";
          }
          print "  $dotid_me [style=filled, fillcolor=$fillcolor, $fontcolorelement " .
            "label=\"{{ref$reftype|$mequoted}|$otherquoted\\l$configmetadata}\"]\n";
          print "  $dotid_me -> $dotid_other\n";
        }
      }' 
}

print_dot_ref_logs() {
  firstiter="non-empty-string" # i.e. true
  git show-ref --abbrev=$sha1length |
    # The following code depends upon HEAD being the last in the list
    perl -pe 's@^.*?(\brefs/\S*)$@$1@; END { print "HEAD\n";}' |
    while read refname; do
      # work around the problem that 'git reflog show HEAD' results in an
      # error when HEAD contains refs/heads/master but refs/heads/master does
      # not exist, which is the case after 'git init'.
      if [ ! \( "$firstiter" -a \( "$refname" = HEAD \) \) ]; then
        # 8eb068f master@{11}: commit: tempo-ext: new version
        git reflog show $refname | perl -ne '
          BEGIN {
            $refname = "'$refname'";
            $dotid_reflog = "reflog_" . (($tmp = $refname) =~ s@([^a-zA-Z0-9_])@___@g,$tmp);
          }
          
          if (m/^([a-f0-9]+).*@\{\d+\}: (.*?)$/) { $id_any=$1; $msg=$2; }
          elsif (m/^([a-f0-9]+)/) { $id_any=$1; $msg="<lastentry>"; }
          $id_short = substr(`git rev-parse --short='$sha1length' $id_any`,0,-1);
          print "  $dotid_reflog -> _$id_short [color=gray90]\n";
          
          s/^[a-f0-9]+//;            # strip sha1; $id_short will be used instead
          s/([^a-zA-Z0-9\n])/\\$1/g; # quote for dot
          s/(\r?\n)?$/\\l/;          # \l instead \n newline, and ensure \l at
                                     # end of content
          $content = $content . $id_short . $_;
          
          END {
            $trailing = (substr($content,-2) eq "\\l") ? "" : "\\l"; 
            print "  $dotid_reflog [color=gray90, fontcolor=gray, " .
              "label=\"{{reflog|logs/$refname}|$content$trailing}\"]\n";
          }' 
      fi
    firstiter="" # empty stringt, i.e. false
  done
}

print_dot_index() {
  git ls-files --stage --abbrev=$sha1length | perl -ne '
    if (/^[0-9]+\s+([a-f0-9]+)/) {
      print "  index -> _$1\n";

      s/([^a-zA-Z0-9\r\n])/\\$1/g; # quote for dot
      s/(\r?\n)?$/\\l/;            # \l instead \n newline, and ensure \l at
                                   # end of content
      $content = $content . $_;
    }
    END {
      $trailing = (substr($content,-2) eq "\\l") ? "" : "\\l"; 
      print "  index [style=filled, fillcolor=lightcyan, " .
        "label=\"{{index}|$content$trailing}\"]\n";
    }'
}

print_dot() { 
  echo "digraph structs {"
  echo "  node [shape=record,fontsize=11];"
  echo "  rankdir=\"$orientation\";"

  if [ $showlegend = 1 ]; then
    echo "  subgraph cluster_0 {"
    echo "    color=gray80;"
    echo "    label = \"legend\\l\";"
    echo "    legend_node [label=\"{{type:subtype|id/name}|content\\l|metadata from config\\l}\"]"
    echo "  }"
  fi
  if [ $showobjects = 1 ]; then
    print_dot_objects
  fi
  if [ $showrefs = 1 ]; then
    print_dot_references
  fi
  if [ $showreflogs = 1 ]; then
    print_dot_ref_logs
  fi
  if [ $showindex = 1 ]; then
    print_dot_index
  fi
  echo "}"
}

# process options
while test $# -gt 0
do
  case $1 in

    -h | --help)
      print_usage_and_exit 0
      ;;

    -p | --print-only)
      print_only=1
      ;;

    -i | --image-only)
      image_only=1
      ;;

    -g | --git-dir)
      GIT_DIR=$2
      shift
      ;;

    -w | --work-dir)
      GIT_WORK_TREE=$2
      shift
      ;;

    --dot-filename)
      dotfilename=$2
      shift
      ;;

    --image-filename)
      imgfilename=$2
      shift
      ;;

    --display-cmd)
      displaycmd=$2
      shift
      ;;

    --sha1-length)
      if ! perl -e 'if ($ARGV[0]=~m/\D/ || $ARGV[0]<4 || $ARGV[0]>40) { exit(1); }' "$2" ; then
        echo "ERROR: Argument to --sha1-lenght must be a number between 4 and 40 inclusive." >&2
        exit 1
      fi
      sha1length=$2
      shift
      ;;

    --hide-legend)
      showlegend=0
      ;;

    --hide-objects)
      showobjects=0
      ;;

    --hide-commitcontent)
      showcommitcontent=0
      ;;

    --hide-tagcontent)
      showtagcontent=0
      ;;

    --hide-treecontent)
      showtreecontent=0
      ;;

    --hide-blobcontent)
      showblobcontent=0
      ;;

    --hide-refs)
      showrefs=0
      ;;

    --hide-reflogs)
      showreflogs=0
      ;;

    --hide-index)
      showindex=0
      ;;

    --color-scheme)
      if ! perl -e 'if ($ARGV[0] !~ m/^(default|set312|spectral11|blues9|
          brbg11|bupu9|dark28|paired12|pastel19|set19)$/x) { exit(1); }' "$2" ; then
        echo "ERROR: Invalid color scheme ($2)." >&2
        print_usage_and_exit 1 >&2
      fi
      colorscheme=$2
      color_commit=$(eval "echo \${color_scheme_${colorscheme}_commit}")
      color_tag=$(eval "echo \${color_scheme_${colorscheme}_tag}")
      color_tree=$(eval "echo \${color_scheme_${colorscheme}_tree}")
      color_blob=$(eval "echo \${color_scheme_${colorscheme}_blob}")
      color_default=$(eval "echo \${color_scheme_${colorscheme}_default}")
      shift
      ;;

    --color-*)
      case "$1" in
      --color-commit) color_commit=$2;;
      --color-tag) color_tag=$2;;
      --color-tree) color_tree=$2;;
      --color-blob) color_blob=$2;;
      --color-default) color_default=$2;;
      *) echo "ERROR: unknown option ($1)" >&2;
         print_usage_and_exit 1 >&2;;
      esac
      # prevent the case that the user supplied color can have special meaning
      # in the dot script
      if ! perl -e 'if ($ARGV[0] =~ m/\\|"/) { exit(1); }' "$2" ; then
        echo "ERROR: Argument to $1 cannot contain \\ or \"" >&2
        exit 1
      fi
      shift
      ;;

    --orientation)
      if ! perl -e 'if ($ARGV[0] !~ m/^(TB|BT|LR|RL)$/) { exit(1); }' "$2" ; then
        echo "ERROR: Invalid orientation ($2)." >&2
        print_usage_and_exit 1 >&2
      fi
      orientation=$2
      shift
      ;;

    --* | -?)
      echo "ERROR: unknown option ($1)" >&2
      print_usage_and_exit 1 >&2
      ;;

    # Split apart combined short options
    -*)
      split=$1
      shift
      set -- $(echo "$split" | cut -c 2- | sed 's/./-& /g') "$@"
      continue
      ;;

    *)
      echo "ERROR: only options are accepted, no further arguments ($1)" >&2
      print_usage_and_exit 1 >&2
      ;;
  esac

  shift
done

# check that image_only & print_only aren't both selected
if [ "$image_only" -a "$print_only" ]; then
  echo "ERROR: --image_only and --print_only are mutualy exclusive options" >&2
  print_usage_and_exit 1 >&2
fi

# check preconditions
if [ ! -d $GIT_DIR/objects ]; then
  echo "Not a git repository" >&2
  exit 1
fi
if ! which perl >&2 >/dev/null; then
  cat >&2 <<EOF
perl not found. If you have apt-get, you can install it with 'sudo apt-get
install perl'.
EOF
  exit 1
fi

# generate .dot file
if [ "$print_only" = 1 ] ; then
  print_dot
  exit 0
fi
print_dot >"$dotfilename" || exit 1

# build and image out of the .dot file
if ! which dot >&2 >/dev/null; then
  cat >&2 <<EOF
dot (part of graphviz) not found. Either use the --print-only option, or
install graphviz. If you have apt-get, you can do that with 'sudo apt-get
install graphviz'.
EOF
  exit 1
fi
dot -Tpng "$dotfilename" > "$imgfilename" || exit 1

# display image
if [ "$image_only" = 1 ] ; then
  exit 0
fi

if ! which "$displaycmd" >&2 >/dev/null; then
  cat >&2 <<EOF
Command to display image not found ($displaycmd).
An image was generated, but I cannot display it. You might want to make use
the --image-only or the --display-cmd <command> option.
EOF
  if [ "$displaycmd" = "display" ]; then
  cat >&2 <<EOF
If you have apt-get, you can install the command 'display' (part of
imagemagick) with 'sudo apt-get install imagemagick'.
EOF
  fi
  exit 1
fi
"$displaycmd" "$imgfilename"