DragonFly On-Line Manual Pages
cvsgraph.conf(5) CVS/RCS Utilities cvsgraph.conf(5)
NAME
cvsgraph.conf - CVS/RCS repository grapher configuration
OVERVIEW
The configuration file is a context free grammar where empty lines and
whitespace are ignored. Comments start with '#' and everything until
end of line is ignored.
A configuration parameter is written as:
<keyword> = <argument> ;
Keywords are defined in PARAMETERS. The argument can be either
numerical or string typed.
Numbers may be entered as octal, decimal or hex as in 0117, 79 and 0x4f
respectively. Floating point numbers contain a single '.', but must
start with a digit. Integer numbers are automagically converted to
floats if required.
Strings are C-style strings, enclosed in double quotes in which
characters may be escaped with '\' and written in octal and hex
escapes. Note that '\' must be escaped if it is to be entered as a
character. Escapes recognized are '\[abfnrtv]', '\[xX][0-9a-fA-F]{2}'
and '\[012][0-7]{0,2}'.
Some strings are expanded with printf like conversions which start with
'%'. Not all are applicable at all times, in which case they will
expand to nothing.
Note that expansions of paths are available with and without trailing
'/'. The distinction is required for path construction to ensure that
empty expansions will not redirect the path to root and no double '/'
in a path is generated.
%c CVS root including a trailing '/' if non-empty
%C CVS root without trailing '/', regardless of how it was entered
on the command line
%m CVS module including trailing '/' if non-empty
%M CVS module without trailing '/', regardless of how it was
entered on the command line
%f filename without path (basename <name> functionality)
%F filename without path and with ",v" stripped (basename <name> ,v
functionality)
%p path part of filename. This includes a trailing '/' if the path
is non-empty
%r number of revisions
%b number of branches
%% literal '%'
%R the revision number (e.g. '1.2.4.4')
%P previous revision number
%B the branch number (e.g. '1.2.4')
%d date of revision
%a author of revision
%s state of revision
%l The log entry of the revision. You need to enable parse_logs for
this to work. You may append an optional truncate length by
writing '[num]' (with num the maximum length) directly after %l.
If no truncation is specified, then all will be expanded.
Specifying a negative truncation length means that newlines
should be replaced by spaces. If truncation occurs, then "..."
will be appended. The expansion is scanned for possible HTML
entities and are replaced by &#...; equivalents.
For example: "%l[25]" will expand up to 25 characters of the
log.
Note: This expansion is obsolete. Please use "%(%L%)"; see
comment below.
%L Same as %l, but no HTML entity translations are performed.
%t current tag of branch or revision
%0..%9 command-line argument -0 .. -9
%(...%)
HTMLize the string withing the parenthesis. This is useful to
prevent a possible cross site scripting bug when expanding tags
into the map generation. For an exploit, you need to have an
attack on your CVS server, or you need to be a complete idiot to
enter a tag with '<', '>' or '"' characters.
Example: a string "%(%t%)", with tag ><script xxx="...">< will
expand to ><script xxx="...">< and not into
the execution of a script.
Note: This method is preferred to the %l expansion, because it
is more generic solution (i.e. use "%(%L%)" for log expansions).
Fonts are numbered 0..4 (as defined in libgd) where 0 = tiny, 1 =
small, 2 = medium (bold), 3 = large and 4 = giant.
Colors are strings, similar to HTML type colors in the form "#rrggbb"
with parts written in hex, where rr = red (00-ff), gg = green (00-ff)
and bb = blue (00-ff).
Colors and some strings can also be defined as conditional expressions
so that revision/branch conditions can be repesented visually:
color/string = [ "key" op "content" truecase falsecase ];
Operator 'op' can be one of:
=~ contained in regex
=* contained in regex, case insensitive
!~ not contained in regex
!* not contained in regex, case insensitive
< less than string, timestamp or rev/branch number
<= less or equal than string, timestamp or rev/branch number
> greater than string, timestamp or rev/branch number
>= greater or equal than string, timestamp or rev/branch number
== equal than string, timestamp or rev/branch number
!= not equal than string, timestamp or rev/branch number
The 'content' is one of:
* POSIX 1003.2 extended regular expression
* timestamp in UTC format: YYYY[.MM[.DD[.hh[.mm[.ss]]]]]
* revision or branch number
The 'key' can be one of:
state State of the revision
author The auther of a revision
tag both revision- and branch-tags
date date of the revision
rev numeric revision- or branch-number
Both 'truecase' and 'falsecase' can be either a (color-)string, as
described above, or a new conditional expression. Examples:
rev_bgcolor = [ "state" =~ "dead" "#e08080" "#f0f0f0" ];
branch_color= [ "rev" < "2.1.2" "#000000" [ "tag" =~ "XyZ.*"
"#123456" "#654321" ] ];
rev_idtext = [ "state" == "dead" "Dead %R" "%R" ]
Note that not all colors can be changed on the fly. For example,
branch_color cannot be be changed based on revision identification
(i.e. author, date or state). The color_bg is always unique and fixed
(all expressions will evaluate to the false case). Also, only string
rev_text and rev_idtext can be conditional expressions as other do not
make much sense to be dynamic.
Booleans have three possible arguments: true, false and not. `Not'
means inverse of what it was (logical negation) and is represented by
the value -1. For the configuration file that means that the default
value is negated. However, the not possibility is a very handy tool
for command line overrides generated from (CGI) scripts.
There are several reserved words besides of the keywords. These
additional reserved words expand to numerical values:
Booleans:
false = 0
true = 1
not = -1
Alignment specifiers:
left = 0
center = 1
right = 2
Image specifiers:
gif = 0
png = 1
jpeg = 2
Font specifiers:
tiny = 0
small = 1
medium = 2
large = 3
giant = 4
HTML level specifiers:
HTML3 = 1
HTML4 = 2
XHTML = 3
PARAMETERS
cvsroot string
The absolute base directory where the CVS/RCS repository can be
found. A '/' will be appended to the string if it is not empty
and does not contain a trailing '/'.
Default is an empty string.
cvsmodule string
The module name in the CVS/RCS repository. This is converted
into a subdirectory name with a trailing '/'.
Default is an empty string.
color_bg color
The background color of the image.
Default is white ("#ffffff").
transparent_bg boolean
The background color of the image is to be the transparent
color. This is only useful for PNG images. Be sure to set
color_bg to something reasonable to make sure that the image is
viewable with programs that do not support transparency.
Default is false.
date_format string
The strftime(3) format string for date and time representation
in the '%d' expansion.
Default is "%d-%b-%Y %H:%M:%S".
box_shadow boolean
A boolean whether or not to draw a shadow for the boxes of
revisions and branches.
Default is false.
upside_down boolean
Draw the entire tree upside down if set. I.e. highest revisions
are at the top of the image. See also cvsgraph(1) option '-u'.
Default is false.
left_right boolean
Draw the entire tree from left to right instead of top down if
set. I.e. highest revisions are at the right of the image. You
can also draw the tree right to left when upside_down is set
too.
Default is false.
strip_untagged boolean
Omit all revisions that do not have tags and are not a branch
point. This reduces the image-size, but can be confusing when
looking for a specific revision. See also cvsgraph(1) option
'-s'.
Default is false.
strip_first_rev boolean
Also omit the first revision in a branch if it does not have
tags and is not a branch point. This has only effect if
strip_untagged is set. See also cvsgraph(1) option '-S'.
Default is false.
auto_stretch boolean
Try to stretch the inter-revision spacing to move the trunks
more to the left, effectively reducing the image's size. See
also cvsgraph(1) option '-k'.
Default is false.
use_ttf boolean
Enable TrueType rendering of strings using the FreeType
interface of libgd. Note that ttf rendering is significantly
slower than libgd's bitmap fonts.
Default is false.
anti_alias boolean
Enable antialias rendering of TrueType fonts. This has only
effect if use_ttf is set. Enabling anti_alias gives very nice
results. However, that is at the expense of 8-bit vs. 4-bit
colormap images, which can be a major drawback because the size
of 8-bit images is 3..4 times that of 4-bit images (with
compressed PNG as output).
Default is true.
thick_lines number
Set the thickness of connector lines between boxes. Normally,
lines are drawn one pixel wide, but can look somewhat thin.
Setting the thickness to anything over 5 would be plain ugly
(but hey, who is to debate taste :-). Values less than 1 and
over 11 are clipped.
Default is 1.
parse_logs boolean
Enable the parsing of the entire ,v file to read the log-entries
between revisions. This is necessary for the %l expansion to
work, but slows down parsing by a very large factor. You've been
warned.
Default is false.
html_level number
Set the compliance to different types of HTML. The generated
image map is slightly different for version 3.x, 4.x and XHTML.
You can use the predefined identifiers (HTML3, HTML4 and XHTML)
to set this value. Command line option '-x' overrides the
setting.
Default is HTML3 (3.x compatibility).
branch_ttfont string
branch_tag_ttfont string
rev_ttfont string
rev_text_ttfont string
tag_ttfont string
title_ttfont string
msg_ttfont string
Set the TrueType font face or filename for the individual
elements. Gd's bitmap fonts are used as a fallback if the font
cannot be found or contains errors.
Default none.
branch_ttsize float
branch_tag_ttsize float
rev_ttsize float
rev_text_ttsize float
tag_ttsize float
title_ttsize float
msg_ttsize float
Set the TrueType font size for the individual elements. See also
*_ttfont.
Default 0.0.
tag_font number
The font used to draw tags in the revision boxes.
Default is tiny.
tag_color color
The color used to draw tags in the revision boxes.
Default is black ("#000000").
tag_ignore string
An extended regular expression as described in regex(7) to match
all tags that should not be displayed in the graph. Note that a
tag will always be displayed if it matches the
merge_from/merge_to expressions regardless to it being set to
ignore here.
Example: tag_ignore = "(test|alpha)_release.*";
Default is empty (no matching occurs).
tag_nocase boolean
Ignore the case in regex matching in tag_ignore.
Default is false.
tag_negate boolean
Negate the matching criteria of the tag_ignore setting. If set,
tags that match the tag_ignore will be shown, instead of matches
being ignored. In any case, tags that match merge_from/merge_to
expressions will never be suppressed.
Default is false.
tag_ignore_merge boolean
If set, then tags matched with tag_ignore will no longer be
considered for matching by merge_from and merge_to.
Default is false.
rev_font number
Default is tiny.
rev_color color
The color of revision boxes, including the revision number.
Default is black ("#000000").
rev_bgcolor color
Revision box background color. This is the interior fill of the
box.
Default is white ("#ffffff").
rev_separator number
Space between tags in revision boxes.
Default is 0.
rev_minline number
The minimum vertical distance between revision boxes.
Default is 0.
rev_maxline number
The maximum vertical distance between revision boxes. This has
only effect if auto_stretch is set to true (or option '-k' is
specified).
Default is 5 times rev_minline.
rev_lspace number
rev_rspace number
rev_tspace number
rev_bspace number
Interior spacing in revision boxes of left, right, top and
bottom respectively. Note that the left right spacing is not
used separately because text is center aligned.
Default is 0.
rev_idtext conditional string
The revision ID or revision number in a revision box.
Default is "%R".
rev_text conditional string
The additional text in a revision box under the revision number.
Default is "%d".
rev_text_font number
The font of the additional text in a revision box under the
revision number.
Default is tiny.
rev_text_color color
The font color of the additional text in a revision box under
the revision number.
Default is black ("#000000").
rev_maxtags number
Limit the number of tags in a revision box. Old trees tend to
have some revisions with extremely many tags attached, which
would generate a huge revision box when drawn. Limiting the
number is a fair solution. Note that tag sorting is not
specified in the rcsfile(7), but cvs(1) will normally have the
newest tags located before older ones. Therefore, limiting the
number of tags would most likely only affect older tags to be
stripped. However, no guarantees are given that a specific tag
is present when the limit is imposed. An ellipsis (...) is shown
in the revision box when the number of tags got truncated.
Default is 0, meaning all tags shown.
rev_hidenumber boolean
If set, then no revision number is displayed in the
revisionboxes. This reduces size for those graphs where the
actual revision-number is irrelevant.
Default is false.
msg_font number
The font used to draw error and warning messages at the bottom
of the graph.
Default is tiny.
msg_color color
The color used to draw error and warning messages.
Default is black ("#000000").
merge_color color
The color of the lines to show merges.
Default is black ("#000000").
merge_front boolean
The merge lines are drawn on top of the image if true.
Otherwise, merge lines are drawn underneath.
Default is false.
merge_nocase boolean
Ignore the case in regex matching in merge_from and merge_to.
Default is false.
merge_from string
The merge_from is an extended regular expression as described in
regex(7) and POSIX 1003.2 (see also Single Unix Specification).
The matching tags describe source revisions of merges. Each
match is subsequently used in a search for the destination tag
as described by the merge_to parameter.
Note: normal string rules apply. Therefore, all backslashes '\'
must be escaped, e.g. "\." must be written as "\\.".
Example: merge_from = "^from_(.*)";
Default is empty (no matching occurs).
merge_to string
The merge_to is an extended regular expression with a twist. All
subexpressions from the merge_from are expanded into merge_to
using %[1-9] (in contrast to \[1-9] for backreferences). Care is
taken to escape the constructed expression. A '$' at the end of
the merge_to expression can be important to prevent 'near match'
references. Normally, you want the destination to be a good
representation of the source. However, this depends on how well
you defined the tags in the first place.
Example: merge_to = "^merge_%1$";
Above example, combined with the merge_from example would match
a tag "from_BugFix_2002" to the merge-destination with tag
"merge_BugFix_2002".
Default is empty (no matching occurs).
merge_findall boolean
Normally, merge_from/merge_to will only find the first matching
tag-combination and draw a line between them, If merge_findall
is set, then all matching merge_tos will result in lines from
the from-tag to the to-tag.
Default is false.
merge_arrows boolean
Enable the use of arrows pointing to the merge destination.
Default is true.
merge_on_tag boolean
Draw merge lines originating from/to the actual tags that are
matched when left_right is enabled. This improves the usability
of the lines drawn but can under circumstances be difficult to
visualize without revision boxes overlapping the lines and
arrows.
Default is false.
merge_cvsnt boolean
Enable drawing of mergepoints as used by CVSNT.
Default is true.
merge_cvsnt_color color
The color of the lines to show merges from mergepoints.
Default is black ("#000000").
arrow_width number
arrow_length number
Specifies the size of the arrow pointing to the merge
destination.
Default is arrow_width=3, arrow_length=12.
branch_font number
The font of the number in a branch box.
Default is tiny.
branch_tag_font number
The font of the tags in a branch box.
Default is tiny.
branch_color color
All branch element's color excluding tags.
Default is black ("#000000").
branch_bgcolor color
Branch box background color. This is the interior fill of the
box.
Default is white ("#ffffff").
branch_tag_color color
All branch tags' color.
Default is black ("#000000").
branch_lspace number
branch_rspace number
branch_tspace number
branch_bspace number
Interior spacing of branch boxes.
Default is 0.
branch_margin number
Exterior spacing of branches. Each branch will be spaced with a
minimum of this value.
Default is 0.
branch_connect number
Length of the vertical connector from a revision to the branch
box.
Default is 0.
branch_dupbox boolean
Add an extra branch box at the end of the trunk. Useful for
upside down drawn trees. If there are no commits on a branch,
then no extra box is added, regardless of the setting of this
option.
Default is false.
branch_fold boolean
Fold branches that have no commits into one branch-box. This
helps to reduce the size of the overall image by a huge factor
(5..10 in most cases). Many applications of CVS use many
branches, but not all files in the repository change for each
branch. Especially stable files line .cvsignore or older code
tend to accumulate many empty branches at one and the same
revision. Folding these branches into one box reduces the width
of these images considerably.
Default is true.
branch_foldall boolean
Fold all empty branches that sprout from the save revision in
one box. If this option is not set, then multiple boxes will be
created if the empty branches are interspaced with ones that
have revisions attached. When this option is set, then all empty
branches will be collected and put into the box of the first
occurring empty branch on the revision's branch point. Setting
this option will reduce image size with interspaced commits to
the a maximum.
Default is false.
branch_resort boolean
Resort the branches according to the number of revisions they
have, where less revisions will stick closer to the sprouting
trunk. This will reduce image size under circumstances where
many branches have significant different number of revisions.
Default is false.
branch_subtree string
Reduce the tree only to include the subtree from the branch-
number given in the argument. If the argument is a revision
which is the root of branches, then all those branches will be
shown. The argument can also be a symbolic tag (either a branch-
or revision-tag). You normally would set this option from the
command line with the -O option for interactive flexibility.
Example: branch_subtree = "1.2.4";
Default is empty (all branches shown).
title string
The title of the image.
Default is empty string.
title_x number
title_y number
Position of title.
Default is 0.
title_font number
The font of the title.
Default is tiny.
title_align number
Horizontal alignment of the title.
Default is left.
title_color color
The color of the title.
Default is black ("#000000").
margin_top number
margin_bottom number
margin_left number
margin_right number
Margins of the image. Note: the title position is not affected
by the margin.
Default is 0.
image_type number
Image types are available if they can be found in the gd
library. Some versions of gd do not have gif, although newer
version have it implemented again. CvsGraph will automatically
generate png images if gif is not available.
Default is dependent on availability and is prioritized in the
order png, gif and jpeg.
image_quality number
The quality of a jpeg image (1..100)
Default is 100.
image_compress number
Set the compression level of png images (-1..9). Zero means no
compression. A higher number means higher compression. Minus one
selects the default library setting.
Default is -1.
image_interlace boolean
Write png and jpeg images in interlaced format. This enables
progressive loading in your browser (if supported).
Default is false.
map_name string
The name= attribute in <map name="mapname">...</map> in the
generated HTML map.
Default is "CvsGraphImageMap".
map_branch_href string
map_rev_href string
map_diff_href string
map_merge_href string
These are the href= attributes in the <area> tags of HTML.
Default are:
branch: "href=\"unset: conf.map_branch_href\""
revision: "href=\"unset: conf.map_rev_href\""
diff: "href=\"unset: conf.map_diff_href\""
merge: "href=\"unset: conf.map_merge_href\""
map_branch_alt string
map_rev_alt string
map_diff_alt string
map_merge_alt string
These are the alt= attributes in the <area> tags of HTML.
Default are "alt=\"%B\"", "alt=\"%R\"", "alt=\"%P <->
%R\"" and "alt=\"%P <-> %R\"" respectively.
AUTHOR
CvsGraph is written and maintained by B. Stultiens.
Send comments and bug reports to cvsgraph@vagrearg.org (read the
mailnote in the README file first) and visit the homepage at:
https://www.vagrearg.org/content/cvsgraph/.
SEE ALSO
cvsgraph(1)
B. Stultiens 1.7.2 cvsgraph.conf(5)