Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SVN::Web(3)	      User Contributed Perl Documentation	   SVN::Web(3)

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 with "plackup" to start a simple web server	for
	   testing.

	     plackup -Ilib/ ./SVN-Web.psgi

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

       See <https://github.com/djzort/SVN-Web> for the SVN::Web	source code.

DESCRIPTION
       SVN::Web	provides a web interface to subversion repositories. It's
       features	include:

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

       o   Browsing every revision of the repository.

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

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

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

       o   Viewing the blame/annotation	details	of any file.

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

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

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

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

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

       o   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&ccedil;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.

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

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

       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.

   plackup
       "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:

	 plackup SVN-Web.psgi

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

   Apache as CGI (not recommended)
       See Plack::Handler::CGI

   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
       SVN::Web::action, svnweb-install(1), plackup(1),	Plack

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

       Dean Hamstead "<dean@fragfest.com.au>"

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

perl v5.24.1			  2012-10-17			   SVN::Web(3)

NAME | SYNOPSIS | DESCRIPTION | CONFIGURATION | ACTIONS, SUBCLASSES, AND URLS | WEB SERVERS | SEE ALSO | BUGS | AUTHORS | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=SVN::Web&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help