1cvsgraph.conf(5) CVS/RCS Utilities cvsgraph.conf(5)
2
6 cvsgraph.conf - CVS/RCS repository grapher configuration
7
9 The configuration file is a context free grammar where empty lines and
10 whitespace are ignored. Comments start with '#' and everything until
11 end of line is ignored.
12 A configuration parameter is written as:
13 <keyword> = <argument> ;
14 Keywords are defined in PARAMETERS. The argument can be either numeri‐
16 cal or string typed.
17 Numbers may be entered as octal, decimal or hex as in 0117, 79 and 0x4f
20 respectively. Floating point numbers contain a single '.', but must
21 start with a digit. Integer numbers are automagically converted to
22 floats if required.
23 Strings are C-style strings, enclosed in double quotes in which charac‐
26 ters may be escaped with '\' and written in octal and hex escapes. Note
27 that '\' must be escaped if it is to be entered as a character. Escapes
28 recognized are '\[abfnrtv]', '\[xX][0-9a-fA-F]{2}' and
29 '\[012][0-7]{0,2}'.
30 Some strings are expanded with printf like conversions which start with
31 '%'. Not all are applicable at all times, in which case they will
32 expand to nothing.
33 Note that expansions of paths are available with and without trailing
34 '/'. The distinction is required for path construction to ensure that
35 empty expansions will not redirect the path to root and no double '/'
36 in a path is generated.
37 %c CVS root including a trailing '/' if non-empty
39 %C CVS root without trailing '/', regardless of how it was entered
41 on the command line
42 %m CVS module including trailing '/' if non-empty
44 %M CVS module without trailing '/', regardless of how it was
46 entered on the command line
47 %f filename without path (basename <name> functionality)
49 %F filename without path and with ",v" stripped (basename <name> ,v
51 functionality)
52 %p path part of filename. This includes a trailing '/' if the path
54 is non-empty
55 %r number of revisions
57 %b number of branches
59 %% literal '%'
61 %R the revision number (e.g. '1.2.4.4')
63 %P previous revision number
65 %B the branch number (e.g. '1.2.4')
67 %d date of revision
69 %a author of revision
71 %s state of revision
73 %l The log entry of the revision. You need to enable parse_logs for
75 this to work. You may append an optional truncate length by
76 writing '[num]' (with num the maximum length) directly after %l.
77 If no truncation is specified, then all will be expanded. Speci‐
78 fying a negative truncation length means that newlines should be
79 replaced by spaces. If truncation occurs, then "..." will be
80 appended. The expansion is scanned for possible HTML entities
81 and are replaced by &#...; equivalents.
82 For example: "%l[25]" will expand up to 25 characters of the
83 log.
84 Note: This expansion is obsolete. Please use "%(%L%)"; see com‐
85 ment below.
86 %L Same as %l, but no HTML entity translations are performed.
88 %t current tag of branch or revision
90 %0..%9 command-line argument -0 .. -9
92 %(...%)
94 HTMLize the string withing the parenthesis. This is useful to
95 prevent a possible cross site scripting bug when expanding tags
96 into the map generation. For an exploit, you need to have an
97 attack on your CVS server, or you need to be a complete idiot to
98 enter a tag with '<', '>' or '"' characters.
99 Example: a string "%(%t%)", with tag ><script xxx="...">< will
100 expand to ><script xxx="...">< and not into
101 the execution of a script.
102 Note: This method is preferred to the %l expansion, because it
103 is more generic solution (i.e. use "%(%L%)" for log expansions).
104 Fonts are numbered 0..4 (as defined in libgd) where 0 = tiny, 1 =
107 small, 2 = medium (bold), 3 = large and 4 = giant.
108 Colors are strings, similar to HTML type colors in the form "#rrggbb"
111 with parts written in hex, where rr = red (00-ff), gg = green (00-ff)
112 and bb = blue (00-ff).
113 Colors and some strings can also be defined as conditional expressions
116 so that revision/branch conditions can be repesented visually:
117 color/string = [ "key" op "content" truecase falsecase ];
118 Operator 'op' can be one of:
119 =~ contained in regex
121 =* contained in regex, case insensitive
123 !~ not contained in regex
125 !* not contained in regex, case insensitive
127 < less than string, timestamp or rev/branch number
129 <= less or equal than string, timestamp or rev/branch number
131 > greater than string, timestamp or rev/branch number
133 >= greater or equal than string, timestamp or rev/branch number
135 == equal than string, timestamp or rev/branch number
137 != not equal than string, timestamp or rev/branch number
139 The 'content' is one of:
141 * POSIX 1003.2 extended regular expression
142 * timestamp in UTC format: YYYY[.MM[.DD[.hh[.mm[.ss]]]]]
143 * revision or branch number
144 The 'key' can be one of:
146 state State of the revision
148 author The auther of a revision
150 tag both revision- and branch-tags
152 date date of the revision
154 rev numeric revision- or branch-number
156 Both 'truecase' and 'falsecase' can be either a (color-)string, as
158 described above, or a new conditional expression. Examples:
159 rev_bgcolor = [ "state" =~ "dead" "#e08080" "#f0f0f0" ];
160 branch_color= [ "rev" < "2.1.2" "#000000" [ "tag" =~ "XyZ.*"
161 "#123456" "#654321" ] ];
162 rev_idtext = [ "state" == "dead" "Dead %R" "%R" ]
163 Note that not all colors can be changed on the fly. For example,
164 branch_color cannot be be changed based on revision identification
165 (i.e. author, date or state). The color_bg is always unique and fixed
166 (all expressions will evaluate to the false case). Also, only string
167 rev_text and rev_idtext can be conditional expressions as other do not
168 make much sense to be dynamic.
169 Booleans have three possible arguments: true, false and not. `Not'
172 means inverse of what it was (logical negation) and is represented by
173 the value -1. For the configuration file that means that the default
174 value is negated. However, the not possibility is a very handy tool
175 for command line overrides generated from (CGI) scripts.
176 There are several reserved words besides of the keywords. These addi‐
179 tional reserved words expand to numerical values:
180 Booleans:
181 false = 0
182 true = 1
183 not = -1
184 Alignment specifiers:
185 left = 0
186 center = 1
187 right = 2
188 Image specifiers:
189 gif = 0
190 png = 1
191 jpeg = 2
192 Font specifiers:
193 tiny = 0
194 small = 1
195 medium = 2
196 large = 3
197 giant = 4
198 HTML level specifiers:
199 HTML3 = 1
200 HTML4 = 2
201 XHTML = 3
202
205 cvsroot string
206 The absolute base directory where the CVS/RCS repository can be
207 found. A '/' will be appended to the string if it is not empty
208 and does not contain a trailing '/'.
209 Default is an empty string.
210 cvsmodule string
213 The module name in the CVS/RCS repository. This is converted
214 into a subdirectory name with a trailing '/'.
215 Default is an empty string.
216 color_bg color
219 The background color of the image.
220 Default is white ("#ffffff").
221 transparent_bg boolean
224 The background color of the image is to be the transparent
225 color. This is only useful for PNG images. Be sure to set
226 color_bg to something reasonable to make sure that the image is
227 viewable with programs that do not support transparency.
228 Default is false.
229 date_format string
232 The strftime(3) format string for date and time representation
233 in the '%d' expansion.
234 Default is "%d-%b-%Y %H:%M:%S".
235 box_shadow boolean
238 A boolean whether or not to draw a shadow for the boxes of revi‐
239 sions and branches.
240 Default is false.
241 upside_down boolean
244 Draw the entire tree upside down if set. I.e. highest revisions
245 are at the top of the image. See also cvsgraph(1) option '-u'.
246 Default is false.
247 left_right boolean
250 Draw the entire tree from left to right instead of top down if
251 set. I.e. highest revisions are at the right of the image. You
252 can also draw the tree right to left when upside_down is set
253 too.
254 Default is false.
255 strip_untagged boolean
258 Omit all revisions that do not have tags and are not a branch
259 point. This reduces the image-size, but can be confusing when
260 looking for a specific revision. See also cvsgraph(1) option
261 '-s'.
262 Default is false.
263 strip_first_rev boolean
266 Also omit the first revision in a branch if it does not have
267 tags and is not a branch point. This has only effect if
268 strip_untagged is set. See also cvsgraph(1) option '-S'.
269 Default is false.
270 auto_stretch boolean
273 Try to stretch the inter-revision spacing to move the trunks
274 more to the left, effectively reducing the image's size. See
275 also cvsgraph(1) option '-k'.
276 Default is false.
277 use_ttf boolean
280 Enable TrueType rendering of strings using the FreeType inter‐
281 face of libgd. Note that ttf rendering is significantly slower
282 than libgd's bitmap fonts.
283 Default is false.
284 anti_alias boolean
287 Enable antialias rendering of TrueType fonts. This has only
288 effect if use_ttf is set. Enabling anti_alias gives very nice
289 results. However, that is at the expense of 8-bit vs. 4-bit
290 colormap images, which can be a major drawback because the size
291 of 8-bit images is 3..4 times that of 4-bit images (with com‐
292 pressed PNG as output).
293 Default is true.
294 thick_lines number
297 Set the thickness of connector lines between boxes. Normally,
298 lines are drawn one pixel wide, but can look somewhat thin. Set‐
299 ting the thickness to anything over 5 would be plain ugly (but
300 hey, who is to debate taste :-). Values less than 1 and over 11
301 are clipped.
302 Default is 1.
303 parse_logs boolean
306 Enable the parsing of the entire ,v file to read the log-entries
307 between revisions. This is necessary for the %l expansion to
308 work, but slows down parsing by a very large factor. You've been
309 warned.
310 Default is false.
311 html_level number
314 Set the compliance to different types of HTML. The generated
315 image map is slightly different for version 3.x, 4.x and XHTML.
316 You can use the predefined identifiers (HTML3, HTML4 and XHTML)
317 to set this value. Command line option '-x' overrides the set‐
318 ting.
319 Default is HTML3 (3.x compatibility).
320 branch_ttfont string
323 branch_tag_ttfont string
325 rev_ttfont string
327 rev_text_ttfont string
329 tag_ttfont string
331 title_ttfont string
333 msg_ttfont string
335 Set the TrueType font face or filename for the individual ele‐
336 ments. Gd's bitmap fonts are used as a fallback if the font can‐
337 not be found or contains errors.
338 Default none.
339 branch_ttsize float
342 branch_tag_ttsize float
344 rev_ttsize float
346 rev_text_ttsize float
348 tag_ttsize float
350 title_ttsize float
352 msg_ttsize float
354 Set the TrueType font size for the individual elements. See also
355 *_ttfont.
356 Default 0.0.
357 tag_font number
360 The font used to draw tags in the revision boxes.
361 Default is tiny.
362 tag_color color
365 The color used to draw tags in the revision boxes.
366 Default is black ("#000000").
367 tag_ignore string
370 An extended regular expression as described in regex(7) to match
371 all tags that should not be displayed in the graph. Note that a
372 tag will always be displayed if it matches the
373 merge_from/merge_to expressions regardless to it being set to
374 ignore here.
375 Example: tag_ignore = "(test|alpha)_release.*";
376 Default is empty (no matching occurs).
377 tag_nocase boolean
380 Ignore the case in regex matching in tag_ignore.
381 Default is false.
382 tag_negate boolean
385 Negate the matching criteria of the tag_ignore setting. If set,
386 tags that match the tag_ignore will be shown, instead of matches
387 being ignored. In any case, tags that match merge_from/merge_to
388 expressions will never be suppressed.
389 Default is false.
390 tag_ignore_merge boolean
393 If set, then tags matched with tag_ignore will no longer be con‐
394 sidered for matching by merge_from and merge_to.
395 Default is false.
396 rev_font number
399 Default is tiny.
400 rev_color color
403 The color of revision boxes, including the revision number.
404 Default is black ("#000000").
405 rev_bgcolor color
408 Revision box background color. This is the interior fill of the
409 box.
410 Default is white ("#ffffff").
411 rev_separator number
414 Space between tags in revision boxes.
415 Default is 0.
416 rev_minline number
419 The minimum vertical distance between revision boxes.
420 Default is 0.
421 rev_maxline number
424 The maximum vertical distance between revision boxes. This has
425 only effect if auto_stretch is set to true (or option '-k' is
426 specified).
427 Default is 5 times rev_minline.
428 rev_lspace number
431 rev_rspace number
433 rev_tspace number
435 rev_bspace number
437 Interior spacing in revision boxes of left, right, top and bot‐
438 tom respectively. Note that the left right spacing is not used
439 separately because text is center aligned.
440 Default is 0.
441 rev_idtext conditional string
444 The revision ID or revision number in a revision box.
445 Default is "%R".
446 rev_text conditional string
449 The additional text in a revision box under the revision number.
450 Default is "%d".
451 rev_text_font number
454 The font of the additional text in a revision box under the
455 revision number.
456 Default is tiny.
457 rev_text_color color
460 The font color of the additional text in a revision box under
461 the revision number.
462 Default is black ("#000000").
463 rev_maxtags number
466 Limit the number of tags in a revision box. Old trees tend to
467 have some revisions with extremely many tags attached, which
468 would generate a huge revision box when drawn. Limiting the num‐
469 ber is a fair solution. Note that tag sorting is not specified
470 in the rcsfile(7), but cvs(1) will normally have the newest tags
471 located before older ones. Therefore, limiting the number of
472 tags would most likely only affect older tags to be stripped.
473 However, no guarantees are given that a specific tag is present
474 when the limit is imposed. An ellipsis (...) is shown in the
475 revision box when the number of tags got truncated.
476 Default is 0, meaning all tags shown.
477 rev_hidenumber boolean
480 If set, then no revision number is displayed in the revision‐
481 boxes. This reduces size for those graphs where the actual revi‐
482 sion-number is irrelevant.
483 Default is false.
484 msg_font number
487 The font used to draw error and warning messages at the bottom
488 of the graph.
489 Default is tiny.
490 msg_color color
493 The color used to draw error and warning messages.
494 Default is black ("#000000").
495 merge_color color
498 The color of the lines to show merges.
499 Default is black ("#000000").
500 merge_front boolean
503 The merge lines are drawn on top of the image if true. Other‐
504 wise, merge lines are drawn underneath.
505 Default is false.
506 merge_nocase boolean
509 Ignore the case in regex matching in merge_from and merge_to.
510 Default is false.
511 merge_from string
514 The merge_from is an extended regular expression as described in
515 regex(7) and POSIX 1003.2 (see also Single Unix Specification at
516 http://www.opengroup.com ). The matching tags describe source
517 revisions of merges. Each match is subsequently used in a search
518 for the destination tag as described by the merge_to parameter.
519 Note: normal string rules apply. Therefore, all backslashes '\'
520 must be escaped, e.g. "\." must be written as "\\.".
521 Example: merge_from = "^from_(.*)";
522 Default is empty (no matching occurs).
523 merge_to string
526 The merge_to is an extended regular expression with a twist. All
527 subexpressions from the merge_from are expanded into merge_to
528 using %[1-9] (in contrast to \[1-9] for backreferences). Care is
529 taken to escape the constructed expression. A '$' at the end of
530 the merge_to expression can be important to prevent 'near match'
531 references. Normally, you want the destination to be a good rep‐
532 resentation of the source. However, this depends on how well you
533 defined the tags in the first place.
534 Example: merge_to = "^merge_%1$";
535 Above example, combined with the merge_from example would match
536 a tag "from_BugFix_2002" to the merge-destination with tag
537 "merge_BugFix_2002".
538 Default is empty (no matching occurs).
539 merge_findall boolean
542 Normally, merge_from/merge_to will only find the first matching
543 tag-combination and draw a line between them, If merge_findall
544 is set, then all matching merge_tos will result in lines from
545 the from-tag to the to-tag.
546 Default is false.
547 merge_arrows boolean
550 Enable the use of arrows pointing to the merge destination.
551 Default is true.
552 merge_cvsnt boolean
555 Enable drawing of mergepoints as used by CVSNT.
556 Default is true.
557 merge_cvsnt_color color
560 The color of the lines to show merges from mergepoints.
561 Default is black ("#000000").
562 arrow_width number
565 arrow_length number
567 Specifies the size of the arrow pointing to the merge destina‐
568 tion.
569 Default is arrow_width=3, arrow_length=12.
570 branch_font number
573 The font of the number in a branch box.
574 Default is tiny.
575 branch_tag_font number
578 The font of the tags in a branch box.
579 Default is tiny.
580 branch_color color
583 All branch element's color excluding tags.
584 Default is black ("#000000").
585 branch_bgcolor color
588 Branch box background color. This is the interior fill of the
589 box.
590 Default is white ("#ffffff").
591 branch_tag_color color
594 All branch tags' color.
595 Default is black ("#000000").
596 branch_lspace number
599 branch_rspace number
601 branch_tspace number
603 branch_bspace number
605 Interior spacing of branch boxes.
606 Default is 0.
607 branch_margin number
610 Exterior spacing of branches. Each branch will be spaced with a
611 minimum of this value.
612 Default is 0.
613 branch_connect number
616 Length of the vertical connector from a revision to the branch
617 box.
618 Default is 0.
619 branch_dupbox boolean
622 Add an extra branch box at the end of the trunk. Useful for
623 upside down drawn trees. If there are no commits on a branch,
624 then no extra box is added, regardless of the setting of this
625 option.
626 Default is false.
627 branch_fold boolean
630 Fold branches that have no commits into one branch-box. This
631 helps to reduce the size of the overall image by a huge factor
632 (5..10 in most cases). Many applications of CVS use many
633 branches, but not all files in the repository change for each
634 branch. Especially stable files line .cvsignore or older code
635 tend to accumulate many empty branches at one and the same revi‐
636 sion. Folding these branches into one box reduces the width of
637 these images considerably.
638 Default is true.
639 branch_foldall boolean
642 Fold all empty branches that sprout from the save revision in
643 one box. If this option is not set, then multiple boxes will be
644 created if the empty branches are interspaced with ones that
645 have revisions attached. When this option is set, then all empty
646 branches will be collected and put into the box of the first
647 occurring empty branch on the revision's branch point. Setting
648 this option will reduce image size with interspaced commits to
649 the a maximum.
650 Default is false.
651 branch_resort boolean
654 Resort the branches according to the number of revisions they
655 have, where less revisions will stick closer to the sprouting
656 trunk. This will reduce image size under circumstances where
657 many branches have significant different number of revisions.
658 Default is false.
659 branch_subtree string
662 Reduce the tree only to include the subtree from the branch-num‐
663 ber given in the argument. If the argument is a revision which
664 is the root of branches, then all those branches will be shown.
665 The argument can also be a symbolic tag (either a branch- or
666 revision-tag). You normally would set this option from the com‐
667 mand line with the -O option for interactive flexibility.
668 Example: branch_subtree = "1.2.4";
669 Default is empty (all branches shown).
670 title string
673 The title of the image.
674 Default is empty string.
675 title_x number
678 title_y number
680 Position of title.
681 Default is 0.
682 title_font number
685 The font of the title.
686 Default is tiny.
687 title_align number
690 Horizontal alignment of the title.
691 Default is left.
692 title_color color
695 The color of the title.
696 Default is black ("#000000").
697 margin_top number
700 margin_bottom number
702 margin_left number
704 margin_right number
706 Margins of the image. Note: the title position is not affected
707 by the margin.
708 Default is 0.
709 image_type number
712 Image types are available if they can be found in the gd
713 library. Some versions of gd do not have gif, although newer
714 version have it implemented again. CvsGraph will automatically
715 generate png images if gif is not available.
716 Default is dependent on availability and is prioritized in the
717 order png, gif and jpeg.
718 image_quality number
721 The quality of a jpeg image (1..100)
722 Default is 100.
723 image_compress number
726 Set the compression level of png images (-1..9). Zero means no
727 compression. A higher number means higher compression. Minus one
728 selects the default library setting.
729 Default is -1.
730 image_interlace boolean
733 Write png and jpeg images in interlaced format. This enables
734 progressive loading in your browser (if supported).
735 Default is false.
736 map_name string
739 The name= attribute in <map name="mapname">...</map> in the gen‐
740 erated HTML map.
741 Default is "CvsGraphImageMap".
742 map_branch_href string
745 map_rev_href string
747 map_diff_href string
749 map_merge_href string
751 These are the href= attributes in the <area> tags of HTML.
752 Default are:
753 branch: "href=\"unset: conf.map_branch_href\""
754 revision: "href=\"unset: conf.map_rev_href\""
755 diff: "href=\"unset: conf.map_diff_href\""
756 merge: "href=\"unset: conf.map_merge_href\""
757 map_branch_alt string
760 map_rev_alt string
762 map_diff_alt string
764 map_merge_alt string
766 These are the alt= attributes in the <area> tags of HTML.
767 Default are "alt=\"%B\"", "alt=\"%R\"", "alt=\"%P <->
768 %R\"" and "alt=\"%P <-> %R\"" respectively.
769
772 CvsGraph is written and maintained by B. Stultiens.
773 Send comments and bug reports to cvsgraph@akhphd.au.dk (read the mail‐
774 note in the README file first) and visit the homepage at:
775 http://www.akhphd.au.dk/~bertho/cvsgraph/.
776
778 cvsgraph(1)
779B. Stultiens 1.6.1 cvsgraph.conf(5)