SVN::Web - Subversion repository web frontend
If you are upgrading an existing SVN::Web installation then please see UPDATING.pod. Installing new SVN::Web versions without making sure the configuration file, templates, and localisations are properly updated and merged will likely break your current installation.
To get started with SVN::Web.
svnweb-installin this directory to configure the environment.
cd svnweb svnweb-install
repos: test: 'file:///path/to/repo'
file:///path/to/repo should be the URL for an existing Subversion repository.
plackupto start a simple web server for testing.
plackup -Ilib/ ./SVN-Web.psgi
plackupthen this is http://localhost:5000/.
See https://github.com/djzort/SVN-Web for the SVN::Web source code.
SVN::Web provides a web interface to subversion repositories. It's features include:
file:///scheme) or that are remotely accessible using the
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.
Additional actions can easily be added to the base set supported by the core of SVN::Web.
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.
SVN::Web's configuration file must contain a version number. If this number is missing, or does not match the version number of the version of SVN::Web that is being used then a fatal error will occur.
SVN::Web can show information from one or more Subversion repositories. These repositories do not have to be located on the same server.
Repositories are specified as a hash items under the
repos key. Each key is the repository name (defined by you), the value is the repository's URL.
The three types of repository are specified like so.
repos: my_local_repo: 'file:///path/to/local/repo' my_http_repo: 'http://hostname/path' my_svn_repo: 'svn://hostname/path'
You may list as many repositories as you need.
For backwards compatibility, if a repository URL is specified without a scheme, and starts with a
/ then the
file:/// scheme is assumed. So
repos: my_local_repo: /path/to/local/repo
is also valid.
If you have multiple repositories that are all under a single parent directory then use
If you set
reposparent then you can selectively block certain repositories from being browseable by specifying the
block: - 'first_subdir_to_block' - 'second_subdir_to_block'
reposparent are mutually exclusive.
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
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, and for you to override specific templates of your choice.
For example, if an action is using a template called
templatedirs is configured like so:
templatedirs: - '/my/local/templates' - '/templates/that/ship/with/svn-web'
then /my/local/templates/view will first by checked. If it exists the search terminates and it's used. If it does not exist then the search continues in /templates/that/ship/with/svn-web.
For more information about writing your own templates see "ACTIONS, SUBCLASSES, AND URLS".
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.
SVN::Web's localisation information is stored in files with names that take the form
language.po. SVN::Web ships with a number of localisations that are automatically installed with SVN::Web.
You can configure SVN::Web to search in additional directories for localisation files. There are typically three reasons for this.
language_dirs configuration to specify all the additional directories that SVN::Web should search. For example:
language_dirs: - /path/to/my/local/translation - /path/to/third/party/action/localisation
If files in more than one directory contain the same localisation key for the same language then the file in the directory that is listed last in this directive will be used.
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, and in the directories listed in the
language_dirs directive (if any).
For example, the default (as of SVN::Web 0.48) is:
languages: en: English fr: Français zh_cn: Chinese (Simplified) zh_tw: Chinese (Traditional)
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;
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.
cache: class: Cache::SizeAwareFileCache
The class' constructor may take various options. Specify those under the
For example, Cache::SizeAwareFileCache supports (among others) options called
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
namespace option, if specified, is ignored, and is always set to the name of the repository being accessed.
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.
. 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.
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.
In SVN::Web this is accomplished using a Template::Toolkit MACRO called
log_msg. The trac templates define this in a template called _log_msg, which is included in the relevant templates by this line:
[% PROCESS _log_msg %]
You may redefine this macro yourself to filter log messages through additional plugins depending on your requirements. As a MACRO this also has access to the template's variables, allowing you to easily specify different filters depending on the values of different variables (perhaps per-repository, or per-author filtering). See the _log_msg template included with this distribution for more details.
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
timedate_format configuration options.
timezone takes one of three settings.
localthen SVN::Web will adjust all timestamps to the web server's local timezone (which may not be the same timezone as the server that hosts the repository).
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:
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.
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
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 action that generates ATOM feeds. If you implement this, you would write:
actions: ... atom: class: My::Class::That::Implements::Atom ...
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
In the user interface the
action menu is a list of actions that are valid in the current context. This menu is built up programmatically from additional metadata about each action included in the config file.
The metadata is written as a hash, with each key corresponding to a particular piece of metadata. The hash is rooted at the
A worked example may prove instructive. Here is the default entry for SVN::Web::RSS. This shows all the valid keys under
rss: class: SVN::Web::RSS action_menu: show: - file - directory link_text: (rss) head_only: 1 icon: /css/trac/feed-icon-16x16.png
The keys, and their meanings, are:
The contexts in which this action should appear in the action menu. Each SVN::Web action produces a result in a particular context. The valid contexts are:
The action is acting on a single directory. E.g., SVN::Web::Browse.
The action is acting on a single revision. E.g., SVN::Web::Revision.
Valid values are any of the three items above, plus the special value
global, indicating that the action should always appear in the action menu.
In this example, the
rss action is available when browsing directories and viewing files. It makes no sense to make the RSS action available when browsing an individual revision, so that is not listed as a valid context.
The text that should appear in the action menu for this item. This text is passed through the localisation system.
A boolean that indicates whether the action is always available in the listed contexts, or whether it should only appear when viewing the HEAD revision in a particular context.
In this example it makes no sense to clamp the RSS feed to a particular revision, so it is flagged as only being available when looking at the HEAD of a file or directory.
The (relative) path to the icon to use for this menu item (if any).
For comparison, this is the recommended setting for SVN::Web::Checkout.
checkout: class: SVN::Web::Checkout action_menu: show: - file link_text: (checkout)
This action is only valid when viewing files -- checking out a directory does not make sense. A file can be checked out at any revision, so
head_only can be omitted (
head_only: 0 would have the same effect). And there is no icon for this action.
For details of how this information is used see the template/trac/_action_menu template.
action_menu metadata is optional. Some actions might not merit a menu option (e.g.,
revision), so those actions should not have
Of course, if you have your own class that implements the CGI interface you may specify it here too.
SVN::Web URLs are broken down in to four components.
The repository the action will be performed on. SVN::Web can be configured to operate on multiple Subversion repositories.
The action that will be run.
The path within the <repository> that the action is performed on.
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:
Shows the blame (also called annotation) information for a file. On a per line basis it shows the revision in which that line was last changed and the user that committed the change.
Shows the files and directories in a given repository path. This is the default command if no path is specified in the URL.
Returns the raw data for the file at a given repository path and revision.
Shows the difference between two revisions of the same file.
Lists the available Subversion repositories. This is the default command if no repository is specified in the URL.
Shows log information (commit messages) for a given repository path.
Shows information about a specific repository revision.
Generates an RSS feed of changes to the repository path.
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.
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.
SVN::Web now uses Plack to provide connectivity to the web server. Previously a cgi, stand alone, fastcgi, mod_perl1 and a mod_perl2 interface was provided as part of this software. All of which have been removed and replaced by Plack. In doing so, Plack now will connect SVN::Web to all of the above, plus PSGI, nginx_perl and anything else cooked up in the future.
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.
plackups is a simple web server that can run SVN::Web stand alone, and is included and installed by Plack. It may be all you need to productively use SVN::Web without needing to install a larger server. To use it, run:
perldoc plackup for details about additional options you can use.
For now this is probably broken.
Please report any bugs or feature requests to
firstname.lastname@example.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.
Copyright 2003-2004 by Chia-liang Kao
Copyright 2005-2007 by Nik Clayton
Copyright 2012 by Dean Hamstead
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.