NAME
SVN::Friendly::Repos - user friendly Subversion API for the repository management
SYNOPSIS
use SVN::Friendly::Repos;
#--------------------------------------------------
# Create a repository
#--------------------------------------------------
$oRepos = create($sRootPath, $xConfig, $xConfigFs, $oUuid);
#--------------------------------------------------
# Get access to an existing repository
#--------------------------------------------------
$oRepos = SVN::Friendly::Repos->new($sRootPath);
#--------------------------------------------------
# About the repository
#--------------------------------------------------
#
# $iHook - may be any of the following constants
#
# $oRepos->PRE_COMMIT
# $oRepos->START_COMMIT
# $oRepos->PRE_REVPROP
# $oRepos->POST_REVPROP
# $oRepos->PRE_OBLITERATE
# $oRepos->POST_OBLITERATE
# $oRepos->PRE_LOCK
# $oRepos->POST_LOCK
# $oRepos->PRE_UNLOCK
# $oRepos->POST_UNLOCK
#
# $iAprTime microseconds since the epoch (Jan 1,1970,00:00:00 UTC)
$oRepos->getUUID();
$oRepos->getRoot();
$oRepos->getFormat();
$oRepos->getFileSystemType();
$oRepos->getHead();
$oRepos->getYoungestRevision($iAprTime);
$oRepos->getHookDir();
$oRepos->getHookFile($iHook);
$oRepos->getDbDir();
$oRepos->getLockDir();
$oRepos->getDbLogLockFile();
$oRepos->getConfDir();
$oRepos->getSvnserverConfFile();
#--------------------------------------------------
# Configuration management
#--------------------------------------------------
$oRepos->setUUID($sUUID);
$oRepos->setUUID($sUUID, $oPool);
$oRepos->enableRevProps();
$oRepos->enableRevProps($sScript);
#--------------------------------------------------
# Get the svn_repos_t object
#--------------------------------------------------
$oSvnRepos = $oRepos->getSvnRepos();
DESCRIPTION
The class provides user friendly access to API routines needed for configuring and retrieving information from the repository.
What is a repository?
A subversion repository stores the canonical or "official" copies of a set of documents as well as all the steps needed to reconstruct past official versions.
This cannonical set can be replicated on multiple machines or locations provided that all copies share the same UUID. The repository can also be moved. Working copies that checked out documents from the old location will still be able to access the new location provided the old and new locations have the same UUID.
The repository can be viewed as a composite of several different subsystems:
* a filesystem or database that stores the documents and all of their history. You can choose the particular implementation you want for the filesystem.
* an authorization system for determining who may make changes or extract data from the repository.
* a runtime system that monitors activity and injects custom functionality via hook scripts.
* a server management system that determines what protocols may be used to access the repository and configures them.
Methods not yet defined for this object
At present there is only a skeletal implementation of the class. If you need to use additional methods, for now, you will have to explore the unadorned Subversion SWIG bindings. You will also need to pass those methods a svn_repos_t
object. This can be retrieved via the getSvnRpos()
method.
For a list of C-API functions, see http://svn.collab.net/svn-doxygen/svn__repos_8h.html
The usual rules for converting the C-API to Perl bindings apply:
* callback + baton parameters are collapsed into a single callback parameter
* "OUT" parameters are returned as return values. if there are multiple such parameters the Perl function will return a list. The list members will be in the same order as the return values.
* the trailing pool parameter is optional. All other parameters must at least be represented by an actual parameter. Some methods allow undef
as a parameter; others require that an actual value be provided.
For further discussion see SVN::Friendly::Client.
USAGE
Creating a repository from scratch
# $sRootPath - local file system path to the root of the
# repository
#
# $xConfig - a SVN::Friendly::Config object, or a hash
# or directory path name suitable for creating
# one - see SVN::Friendly::Config
#
# $xConfigFs - hash storing option-value pairs describing
# the type of file system that will be used
# to build the repository. Keys are option
# names, values are option values. See below
# See below for details.
#
# $oUuid - the respositories Uuid. This should be left
# undefined except when creating a repository
# that is meant to be a mirror of an existing
# repository.
$oRepos = create($sRootPath, $xConfig, $xConfigFs, $oUuid);
Opening an existing repository
$oRepos = SVN::Friendly::Repos->new($sRootPath);
$oRepos = SVN::Friendly::Repos->new($oSvnRepos);
$oRepos = SVN::Friendly::Repos->new($oRepos);
The new
will reopen an existing repository or create an object wrapper around an already opened respository. You can pass it the local root of the reposiory, a SVN::Friendly::Repos
object or a svn_repos_t
object and it will "do the right thing". If a wrapper has already been created, it will use that, otherwise it will create a fresh one.
(Note: the list of already crated wrappers is stored using weak references so there is no need to worry that repository objects will stay live in memory forever.).
Configuration management
There is a great deal that can be done to expand this classes capabilities for programmatic repository management. At present there are just two methods:
$oRepos->setUUID($sUUID);
$oRepos->setUUID($sUUID, $oPool);
$oRepos->enableRevProps();
$oRepos->enableRevProps($sScript);
- setUUID
-
Sets the repository UUID after it has been created. This method should be used with extreme care, and only on a repository that is a meant to be a mirror or backup for the original repository assigned to
$sUUID
.Additionally, if there is any chance that there are outstanding working copies, the owners of those working copies should commit all changes. Once a UUID has changed on a repository, any working copies checked out with the old UUID will no longer be able to post to that repository. They will only be able to post to repositories that have the old UUID.
- enableRevProps
-
Revision properties cannot be edited unless the repository has installed a
PRE_REVPROP
hook script that exits with 0. If called without parameters, this method installs a skeletal version of such a script. If called with the$sScript
it installs the content of$sScript
in the revision property hook file.
VERSION COMPATIBILITY
See SVN::Friendly.
CAVEATS
None to date.
KNOWN BUGS
None to date.
TO DO/ROADMAP
See SVN::Friendly
VOLUNTEERS
If anyone would like to be involved in testing or expanding the user friendly interface, please contact the maintainer.
Feedback on the documentation, bugs, usability, or additional features desired is welcome. Time and person-power permitting the most commonly requested features will be implemented.
SEE ALSO
See SVN::Friendly
AUTHOR
Elizabeth Grace Frank-Backman
COPYRIGHT
Copyright (c) 2008-2011 Elizabeth Grace Frank-Backman. All rights reserved.
LICENSE
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.