Man Linux: Main Page and Category List

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 &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
       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 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 "\\.".
              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_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  &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)