NAME¶
SVN::Web - Subversion repository web frontend
SYNOPSIS¶
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.
- 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: 'file:///path/to/repo'
"file:///path/to/repo" should be the URL for an existing
Subversion repository.
- 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/
<
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. It's features
include:
- •
- Viewing multiple Subversion repositories. SVN::Web is a
full Subversion client, so you can access repositories on the local disk
(with the "file:///" scheme) or that are remotely accessible
using the "http://" and "svn://" schemes.
- •
- 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.
- •
- Viewing the blame/annotation details of any file.
- •
- 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.
Version number¶
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.
version: 0.53
Repositories¶
Local and remote repositories
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.
Local repositories under a single root
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'
"repos" and "reposparent" are mutually exclusive.
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, and for
you to override specific templates of your choice.
For example, if an action is using a template called "view", and
"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".
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.
Localisation directories
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.
- 1.
- You wish to add support for a new language, and have placed
your localisation files in a different directory.
- 2.
- You wish to change the localisation for a language that
SVN::Web already supports, and don't wish to overwrite the localisation
file that SVN::Web ships with.
- 3.
- You have installed a third party SVN::Web::action, and this
action includes its own localisation files stored in a different
directory.
Use the "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.
Available languages
"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
"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.
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 "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 web server's local timezone (which may not be
the same timezone as the server that hosts the repository).
- 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 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
"SVN::Web::<Action>" package.
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 "action_menu" key.
A worked example may prove instructive. Here is the default entry for
SVN::Web::RSS. This shows all the valid keys under "action_menu".
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:
- show
- 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:
- file
- The action is acting on a single file. E.g., SVN::Web::View
or SVN::Web::Blame.
- directory
- The action is acting on a single directory. E.g.,
SVN::Web::Browse.
- revision
- 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.
- link_text
- The text that should appear in the action menu for this
item. This text is passed through the localisation system.
- head_only
- 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.
- icon
- 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.
The "action_menu" metadata is optional. Some actions might not merit a
menu option (e.g., "diff" or "revision"), so those actions
should not have "action_menu" metadata.
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>
or
.../apache-handler/<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:
- blame, SVN::Web::Blame
- 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.
- 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 Apache2::Request (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>
IIS¶
SVN::Web works as a CGI script with IIS and Subversion on Windows servers.
After following the instructions in "SYNOPSIS", ensure that IIS makes
the new
svnweb directory available either as a directory or a virtual
host.
Using IIS Manager:
- •
- Allow executable access to this directory (see Execute
Permissions in the Home Directory tab under
Properties).
- •
- Add index.cgi to the list of default content pages
under Documents.
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
<
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-2007 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>