scripts/plotchangelog.1

   1 .TH PLOTCHANGELOG 1 "Debian Utilities" "DEBIAN" \" -*- nroff -*-
   2 .SH NAME
   3 plotchangelog \- graph debian changelogs
   4 .SH SYNOPSIS
   5 .B plotchangelog
   6 .I "[options] changelog ..."
   7 .SH "DESCRIPTION"
   8 .BR plotchangelog
   9 is a tool to aid in visualizing a Debian changelog. The changelogs are
  10 graphed with
  11 .BR gnuplot (1)
  12 , with the X axis of the graph denoting time of release and the Y axis
  13 denoting the debian version number of the package. Each individual release
  14 of the package is represented by a point, and the points are color coded to
  15 indicate who released that version of the package. The upstream version
  16 number of the package can also be labeled on the graph.
  17 .PP
  18 Alternatively, the Y axis can be configured to display the size of the
  19 changelog entry for each new version. Or it can be configured to display
  20 approximately how many bugs were fixed for each new version.
  21 .PP
  22 Note that if the package is a debian-specific package, the entire package
  23 version will be used for the Y axis. This does not always work perfectly.
  24 .PP
  25 .SH "READING THE GRAPH"
  26 The general outline of a package's
  27 graph is typically a series of peaks, starting at 1, going up to n, and then
  28 returning abruptly to 1. The higher the peaks, the more releases the
  29 maintainer made between new upstream versions of the package. If a package
  30 is debian-only, it's graph will just grow upwards without ever falling
  31 (although a bug in this program may cause it to fall sometimes, if the
  32 version number goes from say, 0.9 to say, 0.10 - this is interpreted wrong..)
  33 .PP
  34 If the graph dips below 1, someone made a NMU of the package and upgraded it
  35 to a new upstream version, thus setting the debian version to 0. NMU's in
  36 general appear as fractional points like 1.1, 2.1, etc. A NMU can also be
  37 easily detected by looking at the points that represent which maintainer
  38 uploaded the package -- a solitary point of a different type than the points
  39 before and after it is typically a NMU.
  40 .PP
  41 It's also easy to tell by looking at the points when a package changes
  42 maintainers.
  43 .SH OPTIONS
  44 .TP
  45 .B \-l, \-\-linecount
  46 Instead of using the debian version number as the Y axis, use the number of
  47 lines in the changelog entry for each version.  Cannot be used
  48 together with
  49 .BR \-\-bugcount .
  50 .TP
  51 .B \-b, \-\-bugcount
  52 Instead of using the debian version number as the Y axis, use the number of
  53 bugs that were closed by each changelog entry. Note that this number is
  54 obtained by searching for "#dddd" in the changelog, and so it may be
  55 inaccurate.  Cannot be used together with
  56 .BR \-\-linecount .
  57 .TP
  58 .B \-c, \-\-cumulative
  59 When used together with either
  60 .B \-\-bugcount
  61 or
  62 .BR \-\-linecount ,
  63 graphs the cumulative count rather than the count in each individual
  64 changelog entry.
  65 .TP
  66 .B \-v, \-\-no-version
  67 Do not show upstream version labels. Useful if the graph gets too crowded.
  68 .TP
  69 .B \-m, \-\-no-maint
  70 Do not differentiate between different maintainers of the package.
  71 .TP
  72 .B \-s file, \-\-save=file
  73 Save the graph to "file" in postscript format instead of immediately
  74 displaying it.
  75 .TP
  76 .B \-u, \-\-urgency
  77 Use larger points when displaying higher-urgency package uploads.
  78 .TP
  79 .B \-\-verbose
  80 Output the gnuplot script that is fed into gnuplot (for debugging purposes).
  81 .TP
  82 .BI \-g commands, \-\-gnuplot=" commands "
  83 This allows you to insert
  84 .BR gnuplot (1)
  85 commands into the gnuplot script that is used to generate the graph. The
  86 commands are placed after all initialization but before the final "plot"
  87 command. This can be used to override the default look provided by this
  88 program in arbitrary ways. You can also use things like
  89 "set terminal png color"
  90 to change the output file type, which is useful in conjunction with
  91 the \-s option.
  92 .TP
  93 .B \-\-help
  94 Show a usage summary.
  95 .TP
  96 .B \-\-version
  97 Display version, author and copyright information.
  98 .TP
  99 .B \-\-noconf, \-\-no-conf
 100 Do not read any configuration files (see below).
 101 .TP
 102 .B changelog ...
 103 The changelog files to graph. If multiple files are specified they will all
 104 be display on the same graph. The files may be compressed with gzip. Any
 105 text in them that is not in Debian changelog format will be ignored.
 106 .SH "CONFIGURATION VARIABLES"
 107 The two configuration files \fI/etc/devscripts.conf\fR and
 108 \fI~/.devscripts\fR are sourced by a shell in that order to set
 109 configuration variables.  The \fB\-\-no\-conf\fR option can be used to
 110 prevent reading these files.  Environment variable settings are
 111 ignored when these configuration files are read.  The currently
 112 recognised variables are:
 113 .TP
 114 .B PLOTCHANGELOG_OPTIONS
 115 This is a space-separated list of options to always use, for example
 116 "\-l \-b".  Do not include "\-g" or "\-\-gnuplot" among this list as it
 117 may be ignored; see the next variable instead.
 118 .TP
 119 .B PLOTCHANGELOG_GNUPLOT
 120 These are
 121 .B gnuplot
 122 commands which will be prepended to any such commands given on the
 123 command line.
 124 .SH "SEE ALSO"
 125 .BR devscripts.conf (5).
 126 .SH AUTHOR
 127 Joey Hess <joey@kitenet.net>