SVN::Web(3pm)

📦
version 0.63 · 3 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

💖 SVN::Web 💖

okay bestie, so this is SVN::Web(3pm) from the User Contributed Perl Documentation, and it's literally the main character of "put my Subversion repo on the web". buckle up, it's a long one 🫶

✨ NAME ✨

SVN::Web — a web frontend for your Subversion repository. slay. 💅

🦋 SYNOPSIS 🦋

⚠️ real talk first: if you're upgrading an existing SVN::Web install, pls go read UPDATING.pod first. Installing a new SVN::Web version without properly updating and merging your config file, templates and localisations will very likely break your current installation. no cap. 😭

kk so to get started with SVN::Web:

  1. make a directory where SVN::Web's config files, templates, stylesheets and other data are gonna live.
mkdir svnweb
  1. run svnweb-install in that directory to configure the environment.
cd svnweb
svnweb-install
  1. open up the config.yaml file it just created and add these two lines:
repos:
  test: 'file:///path/to/repo'

that 'file:///path/to/repo' should be the URL of an actual existing Subversion repository, bestie.

  1. either set up your web server (peep WEB SERVERS) to use SVN::Web, or just vibe with plackup to spin up a simple test server:
plackup -Ilib/ ./SVN-Web.psgi
  1. point your browser at the right URL and go browse that repo 🎀 if you ran plackup the URL is http://localhost:5000/.

the SVN::Web source code lives at https://github.com/djzort/SVN-Web ✨

🌈 DESCRIPTION 🌈

SVN::Web gives you a whole web interface for Subversion repositories, and honestly? the feature list ate. here's what it does:

  • Viewing multiple Subversion repositories. SVN::Web is a full Subversion client, so you can hit repos on your local disk (using the file:/// scheme) or remote ones via the http:// and svn:// schemes. multi-repo queen 👑
  • Browsing every revision of the repository. every single one.
  • Viewing the contents of files in the repository at any revision. yes, any revision.
  • Viewing diffs of arbitrary revisions of any file. Diffs can be plain unified diffs, or HTML diffs that use colour to make it way easier to see what changed. iconic.
  • Viewing the revision log of files and directories — see what was changed, when, and by who.
  • Viewing the blame/annotation details of any file. 👀
  • Generating RSS feeds of commits, right down to the granularity of individual files. and these RSS feeds are auto-discoverable in modern web browsers, which is lowkey so convenient.
  • Viewing everything that was changed in a revision, and stepping through revisions one at a time to view the history of the repository. one at a time bestie, we're taking it slow.
  • Viewing the interface in a number of different languages. SVN::Web's interface is fully templated and localised — you can change the whole look-and-feel without writing any code. every string in the interface lives in a separate file, which makes translating to different languages way easier. periodt.
  • Rich log message linking. you can configure SVN::Web to spot patterns in your log messages and auto-generate links to other web based systems. like, if your log messages often refer to tickets in your request tracking system:
Reported in: t#1234

then SVN::Web can turn t#1234 into a link to that ticket. it can also be configured to recognise e-mail addresses, URLs, and literally anything else you want to make clickable. 🔥

  • Caching. internally, SVN::Web caches most of the data it pulls from the repository, which speeds up repeat visits to the same page and reduces the load on your repository server. we love a considerate icon.
  • SVK repositories count too — since SVK repositories are also Subversion repositories, you can do all of the above with those as well.

and bestie, extra actions can easily be added on top of the base set supported by SVN::Web's core. sky's the limit 💫

💜 CONFIGURATION 💜

lots of SVN::Web's behaviour can be controlled through the config file config.yaml. if you need info about how to actually write YAML format files, go check the YAML documentation. 📝

Version number 🎀

SVN::Web's config file must contain a version number. if it's missing, or if it doesn't match the version number of the SVN::Web you're running, you get a fatal error. dramatic but fair.

version: 0.53

Repositories 🌸

Local and remote repositories

SVN::Web can show info from one or more Subversion repositories, and they do not have to live on the same server. geographically distributed queen 👑

Repositories are specified as hash items under the repos key. each key is the repository name (you get to define it), and the value is the repository's URL.

the three types of repository look like this:

repos:
  my_local_repo: 'file:///path/to/local/repo'
  my_http_repo: 'http://hostname/path'
  my_svn_repo: 'svn://hostname/path'

list as many repositories as you need, bestie.

for backwards compatibility: if a repository URL is specified with no scheme and it starts with a /, then the file:/// scheme is assumed. so this:

repos:
  my_local_repo: /path/to/local/repo

is also valid ✨

Local repositories under a single root

if you've got a bunch of repositories that all live under a single parent directory, use reposparent.

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

and if you set reposparent, you can selectively block certain repositories from being browseable with the block setting:

block:
  - 'first_subdir_to_block'
  - 'second_subdir_to_block'
⚠️ repos and reposparent are mutually exclusive. pick one, bestie, you can't have both.

Templates 🦋

SVN::Web's output is entirely template driven. it ships with a bunch of different template styles, installed into 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 switch to another set, use the templatedirs configuration directive.

for example, to use a set of templates with a much plainer look and feel:

templatedirs:
  - 'template/plain'

alternatively, if your own templates live somewhere else entirely, you can give a full path to them:

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

you can list more than one directory here, and templates get searched for in each directory in turn. this means actions that aren't part of SVN::Web's core can ship their own templates, and you can override specific templates of your choice. so much freedom 💅

for example, if an action is using a template called view, and templatedirs is configured like this:

templatedirs:
  - '/my/local/templates'
  - '/templates/that/ship/with/svn-web'

then /my/local/templates/view gets checked first. if it exists, the search stops right there and it's used. if it doesn't exist, the search carries on into /templates/that/ship/with/svn-web.

if you wanna write your own templates, go read ACTIONS, SUBCLASSES, AND URLS. 🎨

Languages 🌍

SVN::Web's interface is fully localised and ships with a bunch of translations. the default web interface lets the user pick from the available localisations whenever they want, and their choice gets saved in a cookie. cute right 🍪

Localisation directories

SVN::Web's localisation info lives in files named like language.po. it ships with a bunch of localisations that get installed automatically with SVN::Web.

you can also configure SVN::Web to search additional directories for localisation files. there are typically three reasons you'd wanna do this:

  1. you want to add support for a new language, and you've put your localisation files in a different directory.
  2. you want to change the localisation for a language SVN::Web already supports, and you don't wanna overwrite the localisation file SVN::Web ships with.
  3. you installed a third party SVN::Web::action, and that action includes its own localisation files stored in a different directory.

use the language_dirs config to list all the extra directories SVN::Web should search. like:

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 listed last in this directive wins.

Available languages

languages specifies which localisations are considered available. it's a hash — the keys are the basenames of available localisation files, and the values are the language name as it should show up in the interface. svnweb-install will have set this to a default value for you.

to find the available localisation files, look in the po/ directory created in the directory where you ran svnweb-install, and in the directories listed in the language_dirs directive (if you set 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 when the user hasn't picked one. its value should be one of the keys defined in languages. for example:

default_language: fr

Data cache 💾

SVN::Web can use any module that implements the Cache::Cache interface to cache the data it grabs from the repository. since that data doesn't normally change, this cuts down the time it takes SVN::Web to generate results. speed demon energy ⚡

⚠️ this cache is not enabled by default, bestie.

to enable it you've gotta specify a class that implements a Cache::Cache interface. Cache::SizeAwareFileCache is a solid 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. those 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 you specify it, is ignored — it's always set to the name of the repository being accessed.

Template cache 🧚

Template Toolkit can cache the results of template processing so future processing is faster. ✨

by default the cache is not enabled. use tt_compile_dir to turn it on — set this directive to the name of a directory where the UID that SVN::Web is running as can create files.

for example:

tt_compile_dir: /var/tmp/tt-cache

(bestie this page is long, so there's more coming — don't go anywhere 💖)

A literal . and the UID of the process running SVN::Web get appended to that string to build the final directory name. So bestie, if SVN::Web is being run under UID 80, the final directory name comes out as /var/tmp/tt-cache.80. And because the cached templates are always created with mode 0600, this means different users running SVN::Web literally can not overwrite one another's cached templates. 💅

This directive has no default value. If it's not defined, then no caching will take place. that's the whole rule, no cap 🫶

📨 Log message filters

Okay so like, a bunch of the templates that ship with SVN::Web include log messages from the repository. And those messages? They're likely to contain e-mail addresses, links to other web sites, and other rich information. it's giving content.

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

In SVN::Web this is done using a Template::Toolkit MACRO called log_msg. The trac templates define this in a template called _log_msg, which gets 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. And as a MACRO it also has access to the template's variables, which means you can easily specify different filters depending on the values of different variables (maybe per-repository filtering, or per-author filtering 👀). See the _log_msg template included with this distribution for more details.

🕰️ 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 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's provided, which changes 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
Heads up bestie 📢: 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. do not assume, fr fr.

🎬 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. main character energy, honestly 👑

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'd like to prevent people from retrieving an RSS feed of changes, just delete the - rss entry from the list. bye felicia 👋

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

And please, feel free to submit any classes that implement additional functionality back to the maintainers, so that they can be included in the distribution. share the slay 🫶✨

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. cute little auto-detect moment 💅

🧭 Action menu configuration

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 might prove instructive 👀. Here's 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's not listed as a valid context. logic ✨

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's 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. know when to sit it out, bestie 🙈

🐚 CGI class

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

And 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 🎀

okay bestie so SVN::Web URLs are literally built out of four components and u just gotta know the formula:

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

or

.../apache-handler/<repo>/<action>/<path>?<arguments>
  • repo — the repository the action gets performed on 💖 SVN::Web can be configured to work on multiple Subversion repositories, so this is how u tell it which one.
  • action — the action that's gonna run ✨
  • path — the path inside the <repository> that the action does its thing on 🦋
  • arguments — whatever arguments control how the action behaves 🌸

Each action is implemented as a Perl module. By convention, each module does whatever processing the action needs, and hands back a reference to a hash of data — and that hash fills out a Template::Toolkit template that displays the action's results. so iconic of them tbh 👑

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

  • blame, SVN::Web::Blame — shows the blame (also called annotation) info for a file 💅 on a per-line basis it shows the revision where that line was last changed, plus the user who 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 info (commit messages) for a given repository path 📝
  • revision, SVN::Web::Revision — shows info 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 info about the data they hand to each template, and for info about customising the templates used for each module. iykyk 🌸

🧚 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 u ran svnweb-install in, and it 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 👋 By doing that, Plack now connects SVN::Web to all of the above, plus PSGI, nginx_perl and anything else cooked up in the future. no cap, the future-proofing is real 💅

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 🙏 bestie contributions are always welcome.

plackup

plackups is a simple web server that can run SVN::Web stand alone, and it's included and installed by Plack 🌈 It may genuinely be all u need to productively use SVN::Web without installing a bigger server. To use it, run:

plackup SVN-Web.psgi

See perldoc plackup for details about additional options u can use 💖

See Plack::Handler::CGI

okay so heads up — this one is not recommended 🙈 the manpage literally says so, so don't come for me.

Apache with mod_perl or mod_perl2

See Plack::Handler::Apache1 or Plack::Handler::Apache2 respectively ✨

Apache with FastCGI

See Plack::Handler::FCGI 🦋

IIS

For now this is probably broken 💀

🌈 SEE ALSO 🌈

💀 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 🔔 so like, the loop closes, ur not screaming into the void.

👑 AUTHORS 👑

  • Chia-liang Kao <clkao@clkao.org>
  • Nik Clayton <nik@FreeBSD.org>
  • Dean Hamstead <dean@fragfest.com.au>

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

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

Copyright 2012 by Dean Hamstead <dean@fragfest.com.au>.

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>

and that's the whole page bestie, we ate and left no crumbs 🫶 this lil gem is from perl v5.40.1, dated 2025-04-09, and it lives on the SVN::Web(3pm) page — go forth and browse some repos 💅✨

📦 where this page comes from