Version number

  version: 0.53

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

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

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

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

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

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.

Time and date formatting

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

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.

Action menu configuration

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:

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

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

  cgi_class: 'My::CGI::Subclass'

plackup

  plackup SVN-Web.psgi

See "perldoc plackup" for details about additional options you can use.

Apache as CGI (not recommended)

Apache with mod_perl or mod_perl2

Apache with FastCGI

IIS