このページは GraphvizExtension の翻訳です。

Graphviz 拡張

この拡張は、Mercurial と共には配布されません。

著者: Katsunori FUJIWARA

概要

この拡張は、 チェンジセットツリーを可視化するための (Graphviz の) DOT 言語ソースを生成します。

Graphviz は、 画像（例：*.jpg）ファイルだけでなく、 クライアントサイドのイメージマップも生成できますので、 hg serve と連携する HTML ページを得ることもできます。

Mercurial 0.9.3 ～ 0.9.5 上で動作確認済みの Graphviz 拡張は、 http://www.lares.dti.ne.jp/~foozy/fujiguruma/scm/graphviz.py から入手可能です (2008-02-19 に更新されました)。 描画例を http://www.lares.dti.ne.jp/~foozy/fujiguruma/scm/hg-visualize.html で見ることができます。

設定

graphviz.py を python が認識しているディレクトリ配下に配置した場合、 以下の行を設定ファイル(hgrc)に追加することで、 この拡張を有効にすることができます。 

[extensions]
graphviz =

それ以外の場合は: 

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

利用方法

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

limit-spec を指定しない場合、 graphviz は全てのチェンジセットを描画対象とみなします。

描画対象チェンジセットは、 リビジョン範囲(-r オプション参照) 、 日時範囲(-d オプション参照)ないし 間隔範囲(-i オプション参照)の何れかで制限できます。

リビジョン範囲に対しては、 'リビジョン番号'、'tip への相対番号'、 '短縮チェンジセットID'、'チェンジセットID' ないし'タグ名'のいずれも指定可能です。

日付範囲に対しては、 YYYY-MM-DDThh:mm:ss(中間の T は T そのものでなくてはなりません) として知られる XML Schema dateTime フォーマットを使用する必要があります。 しかし、それほど強い制約が掛けられているわけではありませんので、 例えば 2007-99-99T99:99:99 のような指定も可能です。

間隔範囲に対しては、 コマンド起動時刻からの間隔を秒で指定する必要があります。

limit-spec は３つの形式のうちのどれかでなければなりません。

  1. 'Start,End' 形式は対象チェンジセットを 'Start' から 'End' の間のものに限定します。

  2. 'Start,' 形式は対象チェンジセットを 'Start' 以後のものに限定します。

  3. ',End' 形式は対象チェンジセットを 'End' 以前のものに限定します。

注意: End は含むものとみなされますので、 例えば 2007 年より後に生成されたチェンジセットを無視する場合は、 2007-12-31T24:00:00 のようなものを指定する必要があります。

graphviz は以下のオプションを認識します。 

 -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

ユーザ名エイリアス

ユーザ名がラベルの一部として使用された際にラベル長を低減するために、 エイリアス設定ファイルを指定することができます。 このファイルは、以下の形式の行か、 # で始まるコメント行で構成されていなければなりません。 

AliasName=ActualName

ラベル/ツールチップのフォーマット

描画されるチェンジセットのラベルとツールチップ （例えば、クライアントサイドイメージマップで使用されます） のフォーマットの両方を指定することができます。

フォーマット文字列は、 Python スタイルのフォーマット形式で、 以下のキーワードを使用することができます。 全てのキーワードは文字列と置換されます。

例えば、'%(u)s|%(r)s' というフォーマット文字列は 'commiter|revision#' という結果になります。

グループ化

グループ化、とりわけ日付によるグループ化は、 感覚的に適切な位置にチェンジセットを描画するかもしれません。

group-by-date オプションを指定した場合、 graphviz 拡張はチェンジセットを日付ごとにグループ化します。 このグループ化により、日付ごとの矩形が描画されるようになります。

group-by-branch オプションを指定した場合、 graphviz 拡張はチェンジセットを、 'default' ブランチを除くブランチごとにグループ化します。 このグループ化により、ブランチごとの矩形が描画されるようになります。

上記の矩形を隠蔽したい場合、 描画のカスタマイズを参照してください。

描画のカスタマイズ

グラフ描画を制御するフックオプションが３つあります。

それぞれのオプションは２つの形式を受け付けます。

フックが空文字列か None を返した場合、 graphviz 拡張は描画対象に対して属性を付加しません。

(1) ノード(node)属性フック

このフックは各ノードに属性を追加でき、 以下に示すシグネチャを持っている必要があります。 

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

各引数は:

例えば、以下のようなコードにより、 特定のユーザによるチェンジセットを強調することができます。 

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

(2) エッジ(edge)属性フック

このフックは各エッジに属性を追加でき、 以下に示すシグネチャを持っている必要があります。 

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

各引数は:

parent および child は共に (rev, node, changes) というタプルなので、 エッジ属性フックを以下のように定義することもできます。 

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

(3) クラスタ(cluster)属性フック

このフックは各クラスタ（＝グループ化矩形）に属性を追加でき、 以下に示すシグネチャを持っている必要があります。 

def hook(repo, branch, date)

各引数は:

group-by-branch オプションを指定した場合、 'default' 以外の各ブランチごとにこのフックが起動されます。 起動時には、"" が日付として指定されます。

group-by-date オプションを指定した場合、 各日付ごとにブランチ名付き （'default' の場合も）でこのフックが起動されます。

'group-by-date' と 'group-by-branch' のいずれのオプションも指定されない場合、 このフックは起動されません。

例えば、以下のようなコードにより、 全てのグループ化矩形を非表示にすることができます。 

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

あるいは、ブランチのグループ化矩形のみを表示するには: 

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

Graphviz DOT 言語仕様に適合するために、 他のフックが ',' で区切られた値を返すのと異なり、 このフックは ';' で区切られた値を返す必要があります。

Mercurial 向けフック

画像ファイルを自動的に更新するために、 graphviz 拡張は hook 関数も提供しています。 このフックはフック種別に依存した引数を使用していないので、 任意のフックに指定することができます。 しかし、 最も有用なのは changegroup/commit フックに使用した場合でしょう。 

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

hgrc ファイルの graphviz セクションによって、 フックの挙動を制御できます。 

[graphviz]
# REQUIRED: 画像ファイル出力先
imagefile=%%(hgroot)s/.hg/revtree.jpg

# opt.* は対応するコマンドラインオプションの指定と等価です
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'

# 制限指定リスト
limitspecs=-50,

# Graphviz DOT コマンドのコマンドラインオプション
dot_opts=-Nfontsize=9 -Grankdir=BT

# 指定した場合、DOT 言語ソースを保存。
# 'imagefile' ファイルと同じ場所に '*.dot' サフィックスで保存
dot_source=

# 指定した場合、クライアントサイドイメージマップを生成。
# 'imagefile' と同じ場所に '*.html' サフィックスで保存
imagemap=

# イメージマップ HTML ファイルの導入(= '<img> タグ'の前)部分
prologue=<html><head><title>last updated by %%(r)s</title>....

# イメージマップ HTML ファイルの結び(= '<area> タグ'の後)部分
epilogue=....</html>

上記の例からわかるように、 幾つかの設定中にはキーワード置換を指定することができます。 しかし、 設定ファイル読み込みにおける Python ライブラリの自動置換を抑止するために、 通常の Python 記述における % の代わりに %% を用いる必要があります。

format-label および format-tooltip 向けの全てのキーワードが利用可能ですが、 それらの値は tip チェンジセットのものが使用されます。

それに加えて、以下のキーワードも使用可能です。

キーワード置換は以下のものに適用されます。

フックの手動起動

graphviz-hook コマンドにより、 graphviz 拡張のフックを手動で起動できます。

これにより、commit/pull すること無しに、 フック設定を確認することができます。

CategoryJapanese

JapaneseGraphvizExtension (last edited 2009-05-19 19:31:00 by localhost)