cvsgraph.conf(5)

📦 version 1.7.0, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

🎀 cvsgraph.conf — CVS/RCS repository grapher configuration 🎀

okay bestie, so this is cvsgraph.conf(5), from the CVS/RCS Utilities section of the manual. it's the config file for cvsgraph, and it's genuinely a whole vibe. let's get into it 💅

✨ OVERVIEW ✨

so the config file is a context free grammar, which sounds scary but fr fr it's chill: empty lines and whitespace are just ignored, they mean nothing, they're not the moment. comments start with # and everything from that # to the end of the line is ignored too 🫶

a configuration parameter is written like this:

<keyword> = <argument> ;

Keywords are defined down in PARAMETERS. and the argument can be either numerical or string typed — pick your fighter 🦋

🔢 numbers, numbers, numbers

Numbers can be octal, decimal or hex, like 0117, 79 and 0x4f respectively ✨ Floating point numbers contain a single ., but they must start with a digit (no starting with a lil dot, okay?). and integer numbers are automagically converted to floats if required. love that for them 💖

🎀 strings

Strings are C-style strings, enclosed in double quotes, and inside them characters may be escaped with \ and written in octal and hex escapes. note that \ must be escaped if it's meant to be an actual character, okay bestie? don't forget 😭

Escapes recognized are \[abfnrtv], \[xX][0-9a-fA-F]{2} and \[012][0-7]{0,2}.

Some strings get expanded with printf-like conversions that start with %. Not all of them are applicable at all times — in which case they just expand to nothing. so chill 🧚

Also note that expansions of paths are available with and without a trailing /. that distinction is required for path construction, to make sure that empty expansions won't redirect the path to root, and so no double / gets generated in a path. iconic attention to detail, honestly 👑

  • %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 &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).
🚨 bestie listen — the %l expansion is obsolete, and the %(...%) method is the preferred one. noted. periodt.

🔤 fonts

Fonts are numbered 0..4 (as defined in libgd) where:

  • 0 = tiny
  • 1 = small
  • 2 = medium (bold)
  • 3 = large
  • 4 = giant

🌈 colors

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). so cute, so hex 💜

🧠 conditional expressions

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, look at her go 😭✨

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

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 👑

okay here's the main character section. every single one, no skips, we don't do that here 🫶

  • 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.
🌸 okay so parse_logs is the "you've been warned" one. she's slow. she's worth it if you need %l. your call bestie.
  • html_level number — tells cvsgraph which flavour of HTML it's serving, bestie, because the generated image map is slightly different for version 3.x, 4.x and XHTML. You can just use the predefined identifiers (HTML3, HTML4 and XHTML) to set this value, no math required. The command line option -x overrides whatever you set here. Default is HTML3 (3.x compatibility). iconic, retro, we love her 💅
  • 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 — one option per element, so yes you can absolutely give your branch labels a different vibe than your error messages. Gd's bitmap fonts are used as a fallback if the font cannot be found or contains errors. (she's got a backup plan, periodt) 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 above, they're besties fr fr. 💖 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. Heads up: a tag will always be displayed if it matches the merge_from/merge_to expressions, regardless of it being set to ignore here. merge business wins, always ✨ 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. flip the whole thing, why not 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. (center aligned text said "i don't need two margins") 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. she's doing her best, ok 🫶 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. (lowkey freeing, the numbers were doing too much) 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 at http://www.opengroup.com). 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 "\\.". do NOT forget this, bestie, she will not warn you twice 💀

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. the twist is the whole plot, iykyk 🦋 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. collect them ALL Default is false.
  • merge_arrows boolean — enable the use of arrows pointing to the merge destination. arrows >>> no arrows 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. pretty but chaotic, main character energy tbh 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. personal space but for branches 🧚 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 like .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. size reduction arc, we stan 🌈 Default is true.
  • branch_foldall boolean — fold all empty branches that sprout from the same 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. maximum slayage 👑 Default is false.
  • branch_resort boolean — bestie, this one resorts the branches by how many revisions they have, where less revisions stick closer to the sprouting trunk 🌱. This reduces image size under circumstances where many branches have significantly 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. Defaults 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. Defaults are "alt=\"%B\"", "alt=\"%R\"", "alt=\"%P &lt;-&gt; %R\"" and "alt=\"%P &lt;-&gt; %R\"" respectively.

👑 AUTHOR 👑

CvsGraph is written and maintained by B. Stultiens. Send comments and bug reports to cvsgraph@akhphd.au.dk (read the mailnote in the README file first) and visit the homepage at: http://www.akhphd.au.dk/~bertho/cvsgraph/.

🌈 SEE ALSO 🌈

cvsgraph(1)

and that's the whole cvsgraph.conf(5) situation, bestie 💖 this page is from version 1.7.0, by B. Stultiens, and the footer didn't give a date — just iconic energy ✨

📦 where this page comes from