Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
cvsgraph.conf(5)	       CVS/RCS Utilities	      cvsgraph.conf(5)

       cvsgraph.conf - CVS/RCS repository grapher configuration

       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 numeri-
       cal 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 charac-
       ters 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
       Some strings are	expanded with printf like conversions which start with
       '%'. Not	all are	applicable at all times, in which case they  will  ex-
       pand 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 en-
	      tered on the command line

       %f     filename without path (basename _name_ functionality)

       %F     filename without path and	with ",v" stripped (basename _name_ ,v

       %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.	'')

       %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.	Speci-
	      fying a negative truncation length means that newlines should be
	      replaced by spaces. If truncation	occurs,	then "..." will	be ap-
	      pended. 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
	      Note: This expansion is obsolete.	Please use "%(%L%)"; see  com-
	      ment 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	&gt;&lt;script xxx=&#34;...&#34;&gt;&lt; 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  de-
       scribed 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 addi-
       tional reserved words expand to numerical values:
	    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

       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 revi-
	      sions 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
	      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
	      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	inter-
	      face 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 ef-
	      fect if use_ttf is set. Enabling anti_alias gives	very nice  re-
	      sults.   However,	that is	at the expense of 8-bit	vs. 4-bit col-
	      ormap 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. Set-
	      ting 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
	      Default is false.

       html_level number
	      Set the compliance to different types of HTML. The generated im-
	      age 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  set-
	      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 ele-
	      ments. Gd's bitmap fonts are used	as a fallback if the font can-
	      not 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
	      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 con-
	      sidered 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
	      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
	      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 bot-
	      tom 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 re-
	      vision 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 num-
	      ber 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 re-
	      vision 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  revision-
	      boxes. This reduces size for those graphs	where the actual revi-
	      sion-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.	Other-
	      wise, 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 at ). 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 rep-
	      resentation 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
	      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  ar-
	      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 destina-
	      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
	      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
	      Default is 0.

       branch_dupbox boolean
	      Add  an extra branch box at the end of the trunk.	Useful for up-
	      side 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 revi-
	      sion.  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 oc-
	      curring  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-num-
	      ber  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 re-
	      vision-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  li-
	      brary.  Some versions of gd do not have gif, although newer ver-
	      sion 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 gen-
	      erated 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  &lt;-&gt;
	      %R\"" and	"alt=\"%P &lt;-&gt; %R\"" respectively.

       CvsGraph	is written and maintained by B.	Stultiens.
       Send  comments and bug reports to (read the mail-
       note in the README file first) and visit	the homepage at:


B. Stultiens			     1.7.0		      cvsgraph.conf(5)


Want to link to this manual page? Use this URL:

home | help