NAME

SVN::Web - Subversion repository web frontend

SYNOPSIS

    > mkdir cgi-bin/svnweb
    > cd cgi-bin/svnweb
    > svnweb-install

Edit config.yaml to set the source repository, then point your browser to index.cgi/repos to browse it.

You will also need to make the svnweb directory writeable by the web server.

See http://jc.ngo.org.uk/~nik/cgi-bin/svnweb/index.cgi/jc/browse/nik/CPAN/SVN-Web/trunk/ for the SVN::Web source code, browsed using SVN::Web.

DESCRIPTION

SVN::Web provides a web interface to subversion repositories. You can browse the tree, view history of a directory or a file, see what's changed in a specific revision, track changes with RSS, and also view diff.

CONFIGURATION

Various aspects of SVN::Web's behaviour can be controlled through the configuration file config.yaml. See the YAML documentation for information about writing YAML format files.

Repositories

SVN::Web can show information from one or more Subversion repositories.

To specify them use repos or reposparent.

If you have a single Subversion repository, or multiple repositories that are not under a single parent directory then use repos.

  repos:
    first_repo: '/path/to/the/first/repo'
    second_repo: '/path/to/the/second/repo'

If you have multiple repositories that are all under a single parent directory then use reposparent.

  reposparent: '/path/to/parent/directory'

If you set reposparent then you can selectively block certain repositories from being browseable by specifying the block setting.

  block:
    - 'first_subdir_to_block'
    - 'second_subdir_to_block'

Diffs

When showing differences between files, SVN::Web can show a customisable amount of context around the changes.

The default number of lines to show is 3. To change this globally set diff_context.

  diff_context: 4

Templates

SVN::Web's output is entirely template driven. SVN::Web ships with a number of different template styles, installed in to the templates/ subdirectory of wherever you ran svnweb-install.

The default templates are installed in templates/trac. These implement a look and feel similar to the Trac (http://www.edgewall.com/trac/) output.

To change to another set, use the templatedirs configuration directive.

For example, to use a set of templates that implement a much plainer look and feel:

  templatedirs:
    - 'template/plain'

Alternatively, if you have your own templates elsewhere you can specify a full path to the templates.

  templatedirs:
    - '/full/path/to/template/directory'

You can specify more than one directory in this list, and templates will be searched for in each directory in turn. This makes it possible for actions that are not part of the core SVN::Web to ship their own templates. The documentation for these actions should explain how to adjust templatedirs so their templates are found.

For more information about writing your own templates see "ACTIONS, SUBCLASSES, AND URLS".

Log message filters

Many of the templates shipped with SVN::Web include log messages from the repository. It's likely that these log messages contain e-mail addresses, links to other web sites, and other rich information.

The Template::Toolkit makes it possible to filter these messages through one or more plugins and/or filters that can recognise these and insert additional markup to make them active.

There are two drawbacks with this approach:

1. For consistency you need to make sure that all log messages are passed through the same filters in the same order in all the templates that display log messages.

2. If you move the templates from a machine that has a particular filter installed to a machine that doesn't have that filter installed you need to remove it from the template, otherwise you will receive a run-time error.

SVN::Web provides a special Template::Toolkit filter called log_msg. Use it like so (assume msg contains the SVN log message).

  [% msg | log_msg %]

The filters to run for log_msg, their order, and any options, are specified in the log_msg_filters configuration directive. This contains a list of filters and key,value pairs.

name

Specifies the name of the class of the filtering object or plugin. If the object is in the Template::Plugin::* namespace then you can omit the leading Template::Plugin::.

If the name is standard then filters from the standard Template::Filters collection can be used.

filter

The name of the filter to run. This is taken from whatever the plugin's documentation says would go in the [% FILTER ... %] directive.

For example, the Template::Plugin::Clickable documentation gives this example;

  [% USE Clickable %]
  [% FILTER clickable %]
  ...

So the correct value for name is Clickable, and the correct value for filter is clickable.

opts

Any options can be passed to the filter using opts. This specifies a list of hash key,value pairs.

  ...
  opts:
    first_opt: first_value
    second_opt: second_value
  ...

Filters are run in the order they are listed. Any filters that do not exist on the system are ignored.

The configuration file includes a suggested list of default filters.

You can write your own plugins to recognise certain information in your local log messages and automatically turn them in to links. For example, if you have a web-based issue tracking system, you might write a plugin that recognises text of the form t#1234 and turns it in to a link to ticket #1234 in your ticketing system.

Actions, action classes, and action options

Each action that SVN::Web can carry out is implemented as a class (see "ACTIONS, SUBCLASSES, AND URLS" for more). You can specify your own class for a particular action. This lets you implement your own actions, or override the behaviour of existing actions.

The complete list of actions is listed in the actions configuration directive.

If you delete items from this list then the corresponding action becomes unavailable. For example, if you would like to prevent people from retrieving an RSS feed of changes, just delete the - RSS entry from the list.

To provide your own behaviour for standard actions just specify a different value for the class key. For example, to specify your own class that implements the view action;

  actions:
    ...
    view:
      class: My::View::Class
    ...

If you wish to implement your own action, give the action a name, add it to the actions list, and then specify the class that carries out the action.

For example, SVN::Web currently provides no equivalent to the Subversion annotate command. If you implement this, you would write:

  actions:
    ...
    annotate:
      class: My::Class::That::Implements::Annotate
    ...

Please feel free to submit any classes that implement additional functionality back to the maintainers, so that they can be included in the distribution.

Actions may have configurable options specified in config.yaml under the opts key. Continuing the annotate example, the action may be written to provide basic output by default, but feature a verbose flag that you can enable globally. That would be configured like so:

  actions:
    ...
    annotate:
      class: My::Class::That::Implements::Annotate
      opts:
        verbose: 1
    ...

The documentation for each action should explain in more detail how it should be configured. See SVN::Web::action for more information about writing actions.

If an action is listed in actions and there is no corresponding class directive then SVN::Web takes the action name, converts the first character to uppercase, and then looks for an <SVN::Web::<Action >> package.

CGI class

SVN::Web can use a custom CGI class. By default SVN::Web will use CGI::Fast if it is installed, and fallback to using CGI otherwise.

If you have your own CGI subclass you can specify it here.

   cgi_class: 'My::CGI::Subclass'

This option is somewhat specialised.

ACTIONS, SUBCLASSES, AND URLS

SVN::Web URLs are broken down in to four components.

  .../index.cgi/<repo>/<action>/<path>?<arguments>

repo

The repository the action will be performed on. SVN::Web can be configured to operate on multiple Subversion repositories.

action

The action that will be run.

path

The path within the <repository> that the action is performed on.

arguments

Any arguments that control the behaviour of the action.

Each action is implemented as a Perl module. By convention, each module carries out whatever processing is required by the action, and returns a reference to a hash of data that is used to fill out a Template::Toolkit template that displays the action's results.

The standard actions, and the Perl modules that implement them, are:

browse, SVN::Web::Browse

Shows the files and directories in a given repository path. This is the default command if no path is specified in the URL.

checkout, SVN::Web::Checkout

Returns the raw data for the file at a given repository path and revision.

diff, SVN::Web::Diff

Shows the difference between two revisions of the same file.

list, SVN::Web::List

Lists the available Subversion repositories. This is the default command if no repository is specified in the URL.

log, SVN::Web::Log

Shows log information (commit messages) for a given repository path.

revision, SVN::Web::Revision

Shows information about a specific repository revision.

rss, SVN::Web::RSS

Generates an RSS feed of changes to the repository path.

view, SVN::Web::View

Shows the commit message and file contents for a specific repository path and revision.

See the documentation for each of these modules for more information about the data that they provide to each template, and for information about customising the templates used for each module.

MOD_PERL

You can enable mod_perl support of SVN::Web with the following in the apache configuration:

    Alias /svnweb /path/to/svnweb
    <Directory /path/to/svnweb/>
      AllowOverride None
      Options None
      SetHandler perl-script
      PerlHandler SVN::Web
    </Directory>

SEE ALSO

SVN::Web::action

BUGS

Please report any bugs or feature requests to bug-svn-web@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=SVN-Web. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

AUTHORS

Chia-liang Kao <clkao@clkao.org>

Nik Clayton <nik@FreeBSD.org>

COPYRIGHT

Copyright 2003-2004 by Chia-liang Kao <clkao@clkao.org>.

Copyright 2005 by Nik Clayton <nik@FreeBSD.org>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html

cpanm SVN::Web

perl -MCPAN -e shell
install SVN::Web