== Graphviz extension ==

/!\ '''This third-party extension does not appear to be actively maintained.'''

'''This extension is not distributed with Mercurial.'''

''Author: Katsunori FUJIWARA''

Source code: http://www.lares.dti.ne.jp/~foozy/fujiguruma/scm/graphviz.py

=== Overview ===

This extension generates DOT language
(of [[http://www.graphviz.org/|Graphviz]]) source 
to visualize changeset tree.

Graphviz allows you to get not only image(e.g. {{{*.jpg}}}) files, 
but also client side image map.
So you can get HTML page which cooperates with {{{hg serve}}}.

This extension, which is tested on Mercurial 0.9.3 - 0.9.5,
can be found at http://www.lares.dti.ne.jp/~foozy/fujiguruma/scm/graphviz.py 
(this is updated at 2008-02-19).
You can see renderring example at
http://www.lares.dti.ne.jp/~foozy/fujiguruma/scm/hg-visualize.en.html .

=== Questions ===
 * can this be used with jquery [[http://people.iola.dk/olau/flot/examples/|flot]] library?
    * No, flot is charts; as in bar-chars, not graphs; as in networks

=== Configuration ===

This extension is enabled  by adding the following lines 
to your configuration file ({{{hgrc}}}),
if you place {{{graphviz.py}}} in the directory where your python knows:

{{{
[extensions]
graphviz = 
}}}

Otherwise:

{{{
[extensions]
graphviz = /path/to/graphviz.py
}}}

=== Usage ===

{{{
hg graphviz [OPTIONS] [limit-spec ...]
}}}

Without '''{{{limit-spec}}}''',
{{{graphviz}}} recognizes all changesets as renderring target.

You can limit target changesets by '''revision range'''
(see ''-r'' option),
'''datetime range'''(see ''-d'' option) or
'''interval range'''
(see ''-i'' option).

For '''revision range''',
you can use any of 'revision number', 'relative number to tip',
'short changeset ID', 'long changeset ID'
or 'tag name'.

For '''datetime range''',
you should use XML Schema dateTime format,
known as ''YYYY-MM-DDThh:mm:ss''(middle '''T''' should be exactly '''T''').
But it is not so strongly restricted 
that you can specify {{{2007-99-99T99:99:99}}}, for example.

For '''interval range''',
you should specify interval value from invocation time in '''second'''.

{{{limit-spec}}} should be in one of three format.

  1. '{{{Start,End}}}' format limits target changesets to ones
  between '{{{Start}}}' and '{{{End}}}'.

  1. '{{{Start,}}}' format limits target changesets to ones
  after '{{{Start}}}'.

  1. '{{{,End}}}' format limits target changesets to ones
  before '{{{End}}}'.

'''ATTENTION:''' {{{End}}} is treated as '''inclusive''',
so you should specify {{{2007-12-31T24:00:00}}}(or such one)
to ignore changesets created after 2007, for example.

{{{graphviz}}} recognizes following options.

{{{
 -r --revision           use revision to limit targets(default)
 -d --datetime           use datetime to limit targets
 -i --interval           use interval from NOW to limit targets
 -a --aliases            file with user name aliases
    --show-tags          show tags in graph
 -u --urlbase            url base for client side image map
    --format-label       format of changeset label (default: %(r)s)
    --format-tooltip     format of changeset tooltip (default: %(U)s/%(t)s)
    --group-by-date      group changesets per date
    --group-by-branch    group changesets per branch
    --node-attr-hook     hook to render node attribute
    --edge-attr-hook     hook to render edge attribute
    --cluster-attr-hook  hook to render cluster attribute
}}}

=== User name aliasing ===

To reduce label length when username is used as part of it, you can
specify alias configuration file. This file should consists lines in
the following format, or lines which start with ''#'' as comment.

{{{
AliasName=ActualName
}}}


=== Label/Tooltip formatting ===

You can specify format of both label and tooltip(shown in client side
image map, for example) for renderred changesets.

You can use keywords shown below in format string, which should be in
Python style formatting. All keywords will be substituted by STRING.

    * u: username(may be aliased)
    * U: username(not aliased)
    * r: changeset revision number
    * s: short-form changeset hash (12 digits of hexadecimal)
    * h: changeset hash (40 digits of hexadecimal)
    * d: datetime of changeset
    * t: first line of changeset description text

For example, '{{{%(u)s|%(r)s}}}' causes '{{{commiter|revision#}}}'.


=== Grouping ===

Grouping, especially of ''by-date'', may render changesets at
appropriate location for your sense.

With {{{group-by-date}}} option, graphviz extension groups changesets per
date. This grouping causes renderring rectangle per date.

With {{{group-by-branch}}} option, graphviz extension groups changesets
per branch, except for '{{{default}}}' one. This grouping causes renderring
rectangle per branche.

Please see '''Renderring customization''', if you want to hide such rectangles.


=== Renderring customization ===

There are three hook options to control graph renderring.

Each option can accept two format:

    * string, which starts with '{{{lambda }}}', as instant definition

    * fully qualified Python function name to load *.py file
      (e.g.: {{{module.name.function}}})

When hook returns empty string or None, graphviz extension does not
append attribute to renderring target object.

==== (1) node attribute hook ====

This hook can append attributes to each nodes, and should have
signature shown below:

{{{
def hook(repository, revision, node, changes, getalias):
}}}

Arguments are:

    * repo     : to which target revision belongs
    * rev      : revision number
    * node     : gotten by '{{{repo.lookup(rev)}}}'
    * changes  : gotten by '{{{repo.changelog.rev(node)}}}'
    * getalias : '{{{lambda name:}}}' to get alias name for given name

For example, you can highlight changesets, which certain user
made, by code shown below:

{{{
def hook(repo, rev, node, changes, getalias):
    return ((getalias(changes[1]) == 'someone')
            and 'style = "filled", fontcolor = "white"'
            or None)
}}}

==== (2) edge attribute hook ====

This hook can append attributes to each edges, and should have
signature shown below:

{{{
def hook(repo, parent, child, first, getalias):
}}}

Arguments are:

    * repo     : to which target revision belongs
    * parent   : form which edge is drawn
    * child    : to which edge is drawn
    * first    : whether parent is 1st one for child or not
    * getalias : '{{{lambda name:}}}' to get alias name for given name

Both {{{parent}}} and {{{child}}} are {{{(rev, node, changes)}}}, so you can
also define edge attribute hook as:

{{{
def hook(repo, (pr, pn, pc), (cr, cn, cc), first, getalias):
}}}

==== (3) cluster attribute hook ====

This hook can append attributes to each clusters(= grouping
rectangles), and should have signature shown below:

{{{
def hook(repo, branch, date)
}}}

Arguments are:

    * repo     : to which target revision belongs
    * branch   : branch name
    * date     : date string({{{YYYYMMDD}}} format) or {{{""}}}

With {{{group-by-branch}}} option, this hook is invoked for each branches
other than '{{{default}}}'. At invocation, {{{""}}} is specified as
date.

With {{{group-by-date}}} option, this hook is invoked for each dates with
branch name, which may be '{{{default}}}'.

Without {{{group-by-date}}} nor {{{group-by-branch}}} options, this hook is
never invoked.

For example, you can hide all rectangles by code shown below:

{{{
def hook(repo, branch, date):
    return 'style=invis'
}}}

Or to show rectangles only for branch grouping:

{{{
def hook(repo, branch, date):
    return (date and 'style=invis')
}}}

To fit for Graphviz DOT language specification, this hook should
return '{{{;}}}' separated values differently from other hooks, which
should return '{{{,}}}' separated values.


=== Hook for Mercurial ===

To update image file automatically, graphviz extension also provides
{{{hook}}} function. You can specify this for any hook configurations,
because it does not use any hook type depend arguments. But it may
be useful mostly as {{{changegroup}}}/{{{commit}}} hook.

{{{
[hooks]
changegroup = python:graphviz.hook
commit = python:graphviz.hook
}}}

You can control hook behavior by {{{graphviz}}} section in your 
{{{hgrc}}} file(s).

{{{
[graphviz]
# REQUIRED: image file output location
imagefile=%%(hgroot)s/.hg/revtree.jpg

# opt.* is equivalent to corresponded option appearance in command line
opt.revision=
#opt.datetime=
#opt.interval=
opt.aliases=%%(hgroot)s/aliases
opt.show-tags=
opt.urlbase=http://localhsot:8000
opt.format-label=%%(r)s
opt.format-tooltip=%%(U)s/%%(t)s
opt.group-by-date=
opt.group-by-branch=
#opt.node-attr-hook=
opt.edge-attr-hook=fully.qualified.python.function
opt.cluster-attr-hook=lambda repo, branch, date: 'style=invis'

# limit-spec list
limitspecs=-50,

# command line option of Graphviz DOT command.
dot_opts=-Nfontsize=9 -Grankdir=BT

# intermediate DOT language source will be saved, if this is given.
# it is saved in same location of 'imagefile', with '*.dot' suffix.
dot_source=

# client side image map file will be created, if this is given.
# it is saved in same location of 'imagefile', with '*.html' suffix.
imagemap=

# prologue(= before '<img> tag') part of image map HTML file.
prologue=<html><head><title>last updated by %%(r)s</title>....

# epilogue(= after '<area> tag') part of image map HTML file.
epilogue=....</html>
}}}

As you know from above example, you can specify some keyword
substitution in configuration. But you should use {{{%%}}} 
instead of {{{%}}}
in normal Python notation, to prevent Python library from auto
substitution at configuration file reading.

All keywords for {{{format-label}}} and {{{format-tooltip}}} are available,
and values for them are from tip changeset.

In addtion, keywords shown below are also available.

  * now: datetime at hook invocation
  * hgroot: root of target repository

Keyword substitution is applied for:

  * imagefile
  * opt.aliases
  * prologue
  * epilogue


=== Manual hook invocation ===

By {{{graphviz-hook}}} command, you can invoke graphviz extension hook
manually.

This allows you to examine hook configuration without commit/pull.

----

translated in: [[JapaneseGraphvizExtension|Japanese]]
----
CategoryExtensionsByOthers