# graphviz.py - generate DOT language source to visualize changeset tree ############################################################################### # Copyright (C) 2007- FUJIWARA Katsunori(foozy@lares.dti.ne.jp) # # Permission is hereby granted, free of charge, to any person obtaining # a copy of this software and associated documentation files (the # "Software"), to deal in the Software without restriction, including # without limitation the rights to use, copy, modify, merge, publish, # distribute, sublicense, and/or sell copies of the Software, and to # permit persons to whom the Software is furnished to do so, subject to # the following conditions: # # The above copyright notice and this permission notice shall be # included in all copies or substantial portions of the Software. # # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. # IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY # CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, # TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE # SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ############################################################################### # # ChangeLog: # # 2008/02/19 # * [bugfix] use '_' instead of '-' as a part of the key to look opts up. # this allows 'graphviz-hook' to be invoked, but not 'graphviz'. # # 2007/09/29 # * [bugfix] hook returns 'False' to tell 'success' to Mercurial # * [bugfix] escape line breaking at logging hook information # # 2007/09/19 # * enhance options, and so on # * add 'hook' for Mercurial # * add 'graphviz-hook' to invoke hook manually # # 2007/08/11 # * first release # ############################################################################### '''This document explains detail of graphviz extension other than command help document. **** **** 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", this hook is (also) invoked for each branches other than "default". At invocation, "" is specified as date. With "group-by-date", this hook is invoked for each dates with branch name, which may be "default". Without "group-by-branch" nor "group-by-date", 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 ' tag') part of image map HTML file. prologue=
last updated at %(now)s by %(r)s/%(U)s
''' default_epilogue = '''last updated at %(now)s by %(r)s/%(U)s
''' configtable = { 'imagefile': None, 'dot_opts': '', 'prologue': default_prologue, 'epilogue': default_epilogue, 'imagemap': False, 'dot_source': False, } ######################################## def hook(ui, repo, hooktype, **args): #################### # get most recent changeset for value of some keywords: node = repo.lookup('tip') changes = repo.changelog.read(node) keywordmap = { 'U': cgi.escape(changes[1]), 'r': repo.changelog.rev(node), 's': short(node), 'h': hex(node), 'd': datetimestr(changes[2]), 't': cgi.escape(get_1stline(changes[4])), 'now': datetimestr([time.time(), None]), 'hgroot': repo.root, } if ui.verbose: for name, value in keywordmap.items(): ui.note(('keyword:%s=%s\n' % (name, value))) #################### # get properties from 'graphviz' section: section = 'graphviz' config = {} for name, default in configtable.items(): value = ui.config(section, name) if value is not None: config[name] = (default is False) or value elif default is None: raise util.Abort(_('"%s" is required in "%s" section') % (name, section)) else: config[name] = default ui.note(('config:%s=%s\n' % (name, config[name]))) key = 'limitspecs' limitspecs = (ui.config(section, key) or '') limits = filter(lambda s: 0 != len(s), string.split(limitspecs, ' ')) if ui.verbose: for limit in limits: ui.note(('limit:%s\n') % (limit)) opts = {} for c, opt, default, desc in graphviz_optlist: name = ('opt.%s' % opt) value = ui.config(section, name) key = opt.replace('-', '_') if value is not None: opts[key] = (default is None) or value else: opts[key] = default ui.note(('opt:%s=%s\n' % (opt, opts[key]))) opts['aliases'] = opts['aliases'] % keywordmap dirname, basename, suffix = split_path(config['imagefile']) #################### # invoke 'graphviz' extension ui.pushbuffer() graphviz(ui, repo, *limits, **opts) dot_source = ui.popbuffer() if config['dot_source']: dotfile = string.join([ basename, 'dot' ], '.') filename = (os.path.join(dirname, dotfile) % keywordmap) ui.note(('filename:%s\n') % (filename)) f = open(filename, 'wb') try: f.write(dot_source) f.flush() finally: f.close() #################### # invoke graphviz 'dot' command for image file cmd = string.join([ 'dot', ('-T%s' % suffix), config['dot_opts'] ], ' ') ui.note(('command:%s\n') % (cmd)) filename = (config['imagefile'] % keywordmap) ui.note(('filename:%s\n') % (filename)) filtercommand(ui, cmd, dot_source, filename) #################### # invoke graphviz 'dot' command for image map file if not config['imagemap']: return cmapfile = string.join([ basename, 'html' ], '.') imgtag = ('' % (string.join([ basename, suffix], '.'))) cmd = string.join([ 'dot', ('-T%s' % 'cmapx'), config['dot_opts'] ], ' ') ui.note(('command:%s\n') % (cmd)) filename = (os.path.join(dirname, cmapfile) % keywordmap) ui.note(('filename:%s\n') % (filename)) filtercommand(ui, cmd, dot_source, filename, o_prologue=((config['prologue'] % keywordmap) + imgtag), o_epilogue=(config['epilogue'] % keywordmap)) return False # tells 'success' to Mercurial ######################################## def graphviz_hook(ui, repo, **opts): '''invoke graphviz hook from command line. This is usefull to examine graphviz hook configuration. ''' hook(ui, repo, None, **{}) ######################################## graphviz_optlist = [ ('r', 'revision', None, _('use revision to limit targets(default)')), ('d', 'datetime', None, _('use datetime to limit targets')), ('i', 'interval', None, _('use interval from NOW to limit targets')), ('a', 'aliases', '', _('file with user name aliases')), ('', 'show-tags', None, _('show tags in graph')), ('u', 'urlbase', '', _('url base for client side image map')), ('', 'format-label', '%(r)s', _('format of changeset label')), ('', 'format-tooltip', '%(U)s/%(t)s', _('format of changeset tooltip')), ('', 'group-by-date', None, _('group changesets per date')), ('', 'group-by-branch', None, _('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')), ] cmdtable = { 'graphviz': (graphviz, graphviz_optlist, 'hg graphviz [limit-spec ...]'), 'graphviz-hook': (graphviz_hook, [ ], 'hg graphviz-hook'), } ########################################