NAME

chlog - a CVS frontend to generate ChangeLog files

SYNOPSIS

chlog [-a{+|-}] [-b{+|-}] [-ddirectory] [-f{file}] [-h] [-i#] [-l{+|-}] [-Nyyyy-mm-dd] [-Oyyyy-mm-dd] [-p'prefix'] [-r{+|-}] [-t#] [-w#] [name(s)]

DESCRIPTION

chlog is a frontend for cvs the ``Concurrent Versions System'' (see cvs(1)) to generate ChangeLog files based on the log-messages provided when file(s) are committed to a cvs repository.

OPTIONS

As of now chlog understands the following commandline arguments:

-a {+|-}
Add name of local host to author's name in changelog, default: -a+ (True), -a- disables hostname appending.
-b {+|-}
Only print information about the revisions on the default branch, default: -b- (False, i.e. list all revisions/branches).
-d directory
Name of working directory to create changelog for, default current directory. The cvs query is done in this directory which means it must be under ``CVS-control'' already. The worker-thread (see NOTES below) will change into this directory before actually calling the cvs executable, so it must be readable/searchable by the user running chlog in order to work.
-f {filename}
Name of output-file to write, default: ChangeLog; use -f- or -f (i.e. no filename at all) to write to StdOut instead of a file (e.g. for redirecting the output to somewhere else, see EXAMPLES below).
-h, --help
Show a short usage note
-i #
Number of spaces to use for identation, default: 4.
-l {+|-}
Run only local, i.e. not recursive, default: -l- (recursive incl. sub-dirs), -l+ enables local mode. ``local'' refers to the directory given with the -d option (see above) or the current directory when -d is omitted.
-N yyyy-mm-dd
The date (in ISO-format as shown above) of the newest log-message, default: none, i.e. all available log-messages are used. Note: Due to a bug in cvs you should give ``the day after'': if you want all entries up to (and including) the last day of 2001 you should give the argument -N2002-01-01.
-O yyyy-mm-dd
The date (in ISO-format as shown above) of the oldest log-message, default: none, i.e. all available log-messages are used. This can be used to limit the amount of data in the ngenerated ChangeLog file.
-p prefix
Character-prefix to put in front of each changelog entry; default: '* '; note that you need quotes if you're using shell meta-chars (like e.g. *?!) or whitespace.
-r {+|-}
Show CVS-revision for every file in changelog, default: -r+ (True), -r- disables output of file-revisions.
-t #
Number of spaces to use for TAB-characters, default: 4. If there are any TAB(ulator) characters within the log-messages chlog will replace them by this number of spaces to make the output independent of any TAB-setting of shell/printer/viewer.
-w #
Max. number of characters per line in changelog, default: 79. If the original log-messages are longer chlog tries to wrap them to generate a human readable and printable output that can be used without horizontally scrolling on text-mode terminals.
name(s)
Name of file(s) to generate changelog for, default: all files.

All options are optional i.e. chlog will use the builtin defaults if it's called without commandline arguments.

Several builtin defaults can be overridden by use of the CHANGELOG environment variable (see ENVIRONMENT below).

Note: There must be no space between the option-name and the option-value; but if you're using multiple options they must be seperated by spaces.

DIAGNOSTICS

There's a commandline switch -v not documented under OPTIONS above that prints all options as used by chlog to StdOut right before the actual CVS-query is done.

If you use -v more than once or use -vv chlog will terminate after printing the diagnostic output without performing the CVS-query.

The output will look like (assuming the builtin defaults are not altered using the CHANGELOG variable, see ENVIRONMENT below):

    # chlog -b+ -f -d~/kylix/src/DFG/Progs/cvs/ -l -a- -r- -vv

    Copyright (C) 2001-2002  DFG/M.Watermann, Berlin, FRG
    $ Id: chlog.dpr,v 1.5 2002/01/24 21:11:03 matthias Exp $
    using options:
            -a-
            -b+
            -d/home/staff/matthias/kylix/src/DFG/Progs/cvs/
            -f-
            -i4
            -l+
            -N
            -O
            -p'* '
            -r-
            -t4
            -w79
            {files:} ""

or, if called without any other commandline option:

    # chlog -vv

    Copyright (C) 2001-2002  DFG/M.Watermann, Berlin, FRG
    $ Id: chlog.dpr,v 1.5 2002/01/24 21:11:03 matthias Exp $
    using options:
            -a+
            -b-
            -d/home/staff/matthias/kylix/src/DFG/Progs/cvs
            -fChangeLog
            -i4
            -l-
            -N
            -O
            -p'* '
            -r+
            -t4
            -w79
            {files:} ""

The latter provides a way as well to see the current defaults (merged from builtin defaults and the CHANGELOG env-var setting; see ENVIRONMENT below).

EXAMPLES

Just to give you an idea how to use chlog here're some examples.

ENVIRONMENT

While cvs uses additional environment-variables (see cvs(1)), chlog uses only one for its own purposes:

CHANGELOG
The CHANGELOG environment-variable can be used to override the builtin default settings of most commandline-options. chlog on startup will first examine the CHANGELOG env-var (if set) and afterwards scan its commandline arguments. Thus, there are three possible states of an option:
  1. builtin default values
  2. setting(s) in CHANGELOG
  3. commandline arguments

The following options can be set via the CHANGELOG variable:

a{+|-}
add hostname
b{+|-}
default branch only
i#
indent width
l{+|-}
local only
Nyyyy-mm-dd
newest date
Oyyyy-mm-dd
oldest date
r{+|-}
show revisions
t#
TAB width
w#
line width

For details of their meaning refer to OPTIONS above.

How to setup such a variable depends on the shell you're using. In BaSH you'd type e.g.

    export CHANGELOG="a- b+ i8 r- t8 O2001-01-01"

to change the builtin defaults to those given in the env-var.

Note that there's no leading dash (-) in front of the options. The dash is only needed/used for the commandline arguments while the CHANGELOG variable holds just the ``key-character'' and the desired value. Note as well that there are spaces between the options.

FILES

Assuming an installation conforming to FHS there are this two files

/opt/bin/chlog
The chlog executable.
/opt/man/man1/chlog.1
The man-page you're probably reading right now ;-)

BUGS

None known as of yet ;-)

Please feel free to submit any reports of anormalities you may observe to the EMail-address below (see AUTHOR).

NOTES

Well ...

Concurrent Versions System

The whole cvs support depends on a properly installed cvs executable. If chlog fails to find/call cvs via the $PATH there is simply no changelog generated. You should refer to the documentation that comes with cvs to learn how to setup and use cvs(1) properly.

chlog does not alter the original log-messages given to cvs in any way except when it tries to wrap log-lines longer than the width given with the -w# commandline option (see OPTIONS above). There's no spell-check or pretty-print or any other bells'n'whistles; chlog simply tries to present the cvs log-messages in a human readable form in chronological order.

Multi-threading

chlog is a multithreaded application. That means it does its job with the help of ``worker-threads''. All cvs queries are done actually by such a ``worker'' in the background without blocking the UI (well, you won't notice that anyway with a commandline tool, will you?). This said, there's nothing more left on this topic. If you like to know, how it's done, just read the source-code (which hold lots of comments).

RESTRICTIONS

chlog was written in Object Pascal using the Kylix 1 IDE provided by Borland (see http://www.borland.com/kylix/ ). Since Pascal is not yet the 'native' language of GNU/Linux it uses a couple of external libraries which need to be installed on your system in order to run chlog.

external libraries

The chlog executable is linked with the following libraries (where the => paths are those of a FHS-conformant installation):

    /lib/libNoVersion.so.1 => /lib/libNoVersion.so.1
    libpthread.so.0 => /lib/libpthread.so.0
    libdl.so.2 => /lib/libdl.so.2
    libc.so.6 => /lib/libc.so.6
    /lib/ld-linux.so.2 => /lib/ld-linux.so.2

All of this libraries should be available with a recent GNU/Linux distribution.

The following list shows, what packages/rmps provide those libraries (at the time of this writing):

    /lib/libNoVersion.so.1 => glibc-2.2.4-19.3
    libpthread.so.0 => glibc-2.2.4-19.3
    libdl.so.2 => glibc-2.2.4-19.3
    libc.so.6 => glibc-2.2.4-19.3
    /lib/ld-linux.so.2 => glibc-2.2.4-19.3

As you see this reduces to

    glibc-2.2.4

Due to changes in the GNU standard library chlog will not run with older versions (e.g. RH6.1 with glibc-2.1.3), but newer versions should be fine.

SEE ALSO

cvs(1), diff(1), kycvs(1)

http://www.cvshome.org/

For CVS updates, more information or documentation, software related to CVS, development of CVS, and more, see: http://www.cyclic.com/ and http://www.loria.fr/~molli/cvs-index.html

COPYRIGHT

kycvs & chlog incl. its documentation are

Copyright 2001-2002 DFG/M.Watermann, D-10247 Berlin, FRG

See the file COPYING included in the distribution for a complete license statement.

AUTHOR

kycvs & chlog incl. its documentation was written by

matthias(at)mwat.de

starting 2001-10-05.

    $Id: chlog.html,v 1.3 2016/02/19 17:52:21 matthias Exp $