SVN::Web(3)

NAME
SVN::Web - Subversion repository web frontend

SYNOPSIS
To get started with SVN::Web.

1.  Create a directory for SVN::Web's configuration files, templates, stylesheets, and other data.

      mkdir svnweb

2.  Run "svnweb-install" in this directory to configure the environment.

      cd svnweb
      svnweb-install

3.  Edit the file config.yaml that's been created, and add the following two lines:

      repos:
        test: '/path/to/repo'

    "/path/to/repo" should be the path to an existing Subversion repository on the local disk.

4.  Either configure your web server (see "WEB SERVERS") to use SVN::Web, or run "svnweb-server" to start a simple web server for testing.

      svnweb-server

    Note: "svnweb-server" requires HTTP::Server::Simple to run, which is not a requirement of SVN::Web. You may have to install HTTP::Server::Simple first.

5.  Point your web browser at the correct URL to browse your repository. If you've run "svnweb-server" then this is <http://localhost:8080/>.

See <http://jc.ngo.org.uk/svnweb/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. SVN::Web's features include:

•   Viewing multiple Subversion repositories.

•   Browsing every revision of the repository.

•   Viewing the contents of files in the repository at any revision.

•   Viewing diffs of arbitrary revisions of any file. Diffs can be viewed as plain unified diffs, or HTML diffs that use colour to more easily show what's changed.

•   Viewing the revision log of files and directories, see what was changed when, by who.

•   Generating RSS feeds of commits, down to the granularity of individual files. The RSS feeds are auto-discoverable in modern web browsers.

•   Viewing everything that was changed in a revision, and step through revisions one at a time, viewing the history of the repository.

•   Viewing the interface in a number of different languages. SVN::Web's interface is fully templated and localised, allowing you to change the look-and-feel without writing any code; all strings in the interface are stored in a separate file, to make localising to different languages easier.

•   Rich log message linking. You can configure SVN::Web to recognise patterns in your log messages and automatically generate links to other web based systems. For example, if your log messages often refer to tickets in your request tracking system:

      Reported in: t#1234

    then SVN::Web can turn "t#1234" in to a link to that ticket. SVN::Web can also be configured to recognise e-mail addresses, URLs, and anything else you wish to make clickable.

•   Caching. Internally, SVN::Web caches most of the data it gets from the repository, helping to speed up repeated visits to the same page, and reducing the impact on your repository server.

•   As SVK repositories are also Subversion repositories, you can do all of the above with those too.

Additional actions can easily be added to the base set supported by the core of SVN::Web.

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".

  Languages
SVN::Web's interface is fully localised and ships with a number of translations. The default web interface allows the user to choose from the available localisations at will, and the user's choice is saved in a cookie.

Two options control SVN::Web's localisations.

The first, "languages", specifies the localisations that are considered available. This is a hash. The keys are the basenames of available localisation files, the values are the language name as it should appear in the interface. "svnweb-install" will have set this to a default value.

To find the available localisation files look in the po/ directory that was created in the directory in which you ran "svnweb-install". For example, the default (as of SVN::Web 0.48) is:

  languages:
    en: English
    fr: Fran&ccedil;ais
    zh_cn: Chinese (Simplified)
    zh_tw: Chinese (Traditional)

The second, "default_language", specifies the language to use if the user has not selected one. The value for this option should be one of the keys defined in "languages". For example;

  default_language: fr

  Data cache
SVN::Web can use any module implementing the Cache::Cache interface to cache the data it retrieves from the repository. Since this data does not normally change this reduces the time it takes SVN::Web to generate results.

This cache is not enabled by default.

To enable the cache you must specify a class that implements a Cache::Cache interface. Cache::SizeAwareFileCache is a good choice.

  cache:
    class: Cache::SizeAwareFileCache

The class' constructor may take various options. Specify those under the "opts" key.

For example, Cache::SizeAwareFileCache supports (among others) options called "max_size", "cache_root", and "directory_umask". These could be configured like so:

  # Use the SizeAwareFileCache.  Place it under /var/tmp instead of
  # the default (/tmp), use a custom umask, and limit the cache size to
  # 1MB
  cache:
    class: Cache::SizeAwareFileCache
    opts:
      max_size: 1000000
      cache_root: /var/tmp/svn-web-cache
      directory_umask: 077

Note: The "namespace" option, if specified, is ignored, and is always set to the name of the repository being accessed.

  Template cache
Template Toolkit can cache the results of template processing to make future processing faster.

By default the cache is not enabled. Use "tt_compile_dir" to enable it. Set this directive to the name of a directory where the UID that SVN::Web is being run as can create files.

For example:

   tt_compile_dir: /var/tmp/tt-cache

A literal "." and the UID of the process running SVN::Web will be appended to this string to generate the final directory name. For example, if SVN::Web is being run under UID 80 then the final directory name is /var/tmp/tt-cache.80. Since the cached templates are always created with mode 0600 this ensures that different users running SVN::Web can not overwrite one another's cached templates.

This directive has no default value. If it is not defined then no caching will take place.

  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. Template::Plugin::Subst might be helpful if you do this.

  Time and date formatting
There are a number of places in the web interface where SVN::Web will display a timestamp from Subversion.

Internally, Subversion stores times in UTC. You may wish to show them in your local timezone (or some other timezone). You may also wish to change the formatting of the timestamp.

To do this use the "timezone" and "timedate_format" configuration options.

"timezone" takes one of three settings.

1.  If not set, or set to the empty string, SVN::Web will show all times in UTC. This is the default behaviour.

2.  If set to the string "local" then SVN::Web will adjust all timestamps to the server's local timezone.

3.  If set to a timezone name, such as "BST" or "EST", then SVN::Web will adjust all timestamps to that timezone.

When displaying timestamps SVN::Web uses the POSIX "strftime()" function. You can change the format string that is provided, thereby changing how the timestamp is formatted. Use the "timedate_format" configuration directive for this.

The default value is:

  timedate_format: '%Y/%m/%d %H:%M:%S'

Using this format, a quarter past one in the afternoon on the 15th of May 2006 would appear as:

  2006/05/15 13:15:00

If instead that was:

  timedate_format: '%a. %b %d, %l:%M%p'

then the same timestamp would appear as:

  Mon. May 15, 1:15pm

Note that strftime(3) on different operating systems supports different format specifiers, so consult your system's strftime(3) manual page to see which specifiers are available.

  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.

Of course, if you have your own class that implements the CGI interface you may specify it here too.

  cgi_class: 'My::CGI::Subclass'

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.

WEB SERVERS
This section explains how to configure some common webservers to run SVN::Web. In all cases, "/path/to/svnweb" in the examples is the directory you ran "svnweb-install" in, and contains config.yaml.

If you've configured a web server that isn't listed here for SVN::Web, please send in the instructions so they can be included in a future release.

  svnweb-server
"svnweb-server" is a simple web server that runs SVN::Web, and is included and installed by this module. It may be all you need to productively use SVN::Web without needing to install a larger server. To use it, run:

  svnweb-server --root /path/to/svnweb

See "perldoc svnweb-server" for details about additional options you can use.

  Apache as CGI
Apache must be configured to support CGI scripts in the directory in which you ran "svnweb-install"

  <Directory /path/to/svnweb>
    Options All ExecCGI
  </Directory>

If /path/to/svnweb is not under your normal Apache web hosting root then you will need to alias a URL to that path too.

  Alias /svnweb /path/to/svnweb

With that configuration the full path to browse the repository would be:

  http://server/svnweb/index.cgi

  Apache with mod_perl or mod_perl2
You can use mod_perl or mod_perl2 with SVN::Web. You must install Apache::Request (for mod_perl) or Apache::Request2 (for mod_perl2) to enable this support.

The following Apache configuration is suitable.

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

    <Directory /path/to/svnweb/css>
      SetHandler default-handler
    </Directory>

If /path/to/svnweb is not under your normal Apache web hosting root then you will need to alias a URL to that path too.

  Alias /svnweb /path/to/svnweb

With that configuration the full path to browse the repository would be:

  http://server/svnweb/

  Apache with FastCGI
SVN::Web works with Apache and FastCGI. The following Apache configuration is suitable.

  FastCgiServer /path/to/svnweb/index.cgi
  ScriptAlias /svnweb /path/to/svnweb/index.cgi

  Alias /svnweb/css /path/to/svnweb/css
  <Directory /path/to/svnweb/css>
     SetHandler default-handler
  </Directory>

MAILING LIST
There is a mailing list for SVN::Web users and developers. The address is svnweb@ngo.org.uk. To subscribe please visit <http://jc.ngo.org.uk/mailman/listinfo/svnweb>.

SEE ALSO
SVN::Web::action, svnweb-install(1), svnweb-server(1)

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-2006 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>