<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Creating and Configuring Your Repository</title><link rel="stylesheet" href="styles.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><link rel="start" href="index.html" title="Version Control with Subversion" /><link rel="up" href="svn.reposadmin.html" title="Chapter 5. Repository Administration" /><link rel="prev" href="svn.reposadmin.planning.html" title="Strategies for Repository Deployment" /><link rel="next" href="svn.reposadmin.maint.html" title="Repository Maintenance" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Creating and Configuring Your Repository</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="svn.reposadmin.planning.html">Prev</a> </td><th width="60%" align="center">Chapter 5. Repository Administration</th><td width="20%" align="right"> <a accesskey="n" href="svn.reposadmin.maint.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="svn.reposadmin.create"></a>Creating and Configuring Your Repository</h2></div></div></div><p>In <a class="xref" href="svn.reposadmin.planning.html" title="Strategies for Repository Deployment">the section called “Strategies for Repository Deployment”</a>, we looked at
some of the important decisions that should be made before
creating and configuring your Subversion repository. Now, we
finally get to get our hands dirty! In this section, we'll see
how to actually create a Subversion repository and configure it
to perform custom actions when special repository events
occur.</p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="svn.reposadmin.basics.creating"></a>Creating the Repository</h3></div></div></div><p>Subversion repository creation is an incredibly simple
task. The <span class="command"><strong>svnadmin</strong></span> utility that comes with
Subversion provides a subcommand (<code class="literal">create</code>)
for doing just that.</p><pre class="screen">
$ svnadmin create /var/svn/repos
</pre><p>This creates a new repository in the directory
<code class="filename">/var/svn/repos</code>, and with the default
filesystem data store. Prior to Subversion 1.2, the default
was to use Berkeley DB; the default is now FSFS. You can
explicitly choose the filesystem type using the
<code class="option">--fs-type</code> argument, which accepts as a
parameter either <code class="literal">fsfs</code> or
<code class="literal">bdb</code>.</p><pre class="screen">
$ # Create an FSFS-backed repository
$ svnadmin create --fs-type fsfs /var/svn/repos
$
</pre><pre class="screen">
# Create a Berkeley-DB-backed repository
$ svnadmin create --fs-type bdb /var/svn/repos
$
</pre><p>After running this simple command, you have a Subversion
repository.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>The path argument to <span class="command"><strong>svnadmin</strong></span> is just
a regular filesystem path and not a URL like the
<span class="command"><strong>svn</strong></span> client program uses when referring to
repositories. Both <span class="command"><strong>svnadmin</strong></span> and
<span class="command"><strong>svnlook</strong></span> are considered server-side
utilities—they are used on the machine where the
repository resides to examine or modify aspects of the
repository, and are in fact unable to perform tasks across a
network. A common mistake made by Subversion newcomers is
trying to pass URLs (even “<span class="quote">local</span>”
<code class="literal">file://</code> ones) to these two programs.</p></div><p>Present in the <code class="filename">db/</code> subdirectory of
your repository is the implementation of the versioned
filesystem. Your new repository's versioned filesystem begins
life at revision 0, which is defined to consist of nothing but
the top-level root (<code class="filename">/</code>) directory.
Initially, revision 0 also has a single revision property,
<code class="literal">svn:date</code>, set to the time at which the
repository was created.</p><p>Now that you have a repository, it's time to customize
it.</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>While some parts of a Subversion repository—such
as the configuration files and hook scripts—are meant
to be examined and modified manually, you shouldn't (and
shouldn't need to) tamper with the other parts of the
repository “<span class="quote">by hand</span>”. The
<span class="command"><strong>svnadmin</strong></span> tool should be sufficient for
any changes necessary to your repository, or you can look to
third-party tools (such as Berkeley DB's tool suite) for
tweaking relevant subsections of the repository. Do
<span class="emphasis"><em>not</em></span> attempt manual manipulation of your
version control history by poking and prodding around in
your repository's data store files!</p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="svn.reposadmin.create.hooks"></a>Implementing Repository Hooks</h3></div></div></div><p>A <em class="firstterm">hook</em> is a program triggered by
some repository event, such as the creation of a new revision
or the modification of an unversioned property. Some hooks
(the so-called “<span class="quote">pre hooks</span>”) run in advance of a
repository operation and provide a means by which to both
report what is about to happen and to prevent it from
happening at all. Other hooks (the “<span class="quote">post hooks</span>”)
run after the completion of a repository event, and are useful
for performing tasks that examine—but don't
modify—the repository. Each hook is handed enough
information to tell what that event is (or was), the specific
repository changes proposed (or completed), and the username
of the person who triggered the event.</p><p>The <code class="filename">hooks</code> subdirectory is, by
default, filled with templates for various repository
hooks.</p><pre class="screen">
$ ls repos/hooks/
post-commit.tmpl post-unlock.tmpl pre-revprop-change.tmpl
post-lock.tmpl pre-commit.tmpl pre-unlock.tmpl
post-revprop-change.tmpl pre-lock.tmpl start-commit.tmpl
</pre><p>There is one template for each hook that the Subversion
repository supports, and by examining the contents of those
template scripts, you can see what triggers each script
to run and what data is passed to that script. Also present
in many of these templates are examples of how one might use
that script, in conjunction with other Subversion-supplied
programs, to perform common useful tasks. To actually install
a working hook, you need only place some executable program or
script into the <code class="filename">repos/hooks</code> directory
which can be executed as the name (like
<span class="command"><strong>start-commit</strong></span> or
<span class="command"><strong>post-commit</strong></span>) of the hook.</p><p>On Unix platforms, this means supplying a script or
program (which could be a shell script, a Python program, a
compiled C binary, or any number of other things) named
exactly like the name of the hook. Of course, the template
files are present for more than just informational
purposes—the easiest way to install a hook on Unix
platforms is to simply copy the appropriate template file to a
new file that lacks the <code class="literal">.tmpl</code> extension,
customize the hook's contents, and ensure that the script is
executable. Windows, however, uses file extensions to
determine whether or not a program is executable, so you would
need to supply a program whose basename is the name of the
hook, and whose extension is one of the special extensions
recognized by Windows for executable programs, such as
<code class="filename">.exe</code> for programs, and
<code class="filename">.bat</code> for batch files.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>For security reasons, the Subversion repository executes
hook programs with an empty environment—that is, no
environment variables are set at all, not even
<code class="literal">$PATH</code> (or <code class="literal">%PATH%</code>,
under Windows). Because of this, many administrators
are baffled when their hook program runs fine by hand, but
doesn't work when run by Subversion. Be sure to explicitly
set any necessary environment variables in your hook program
and/or use absolute paths to programs.</p></div><p>Subversion executes hooks as the same user who owns the
process which is accessing the Subversion repository. In most
cases, the repository is being accessed via a Subversion
server, so this user is the same user as which that server
runs on the system. The hooks themselves will need to be
configured with OS-level permissions that allow that user to
execute them. Also, this means that any file or programs
(including the Subversion repository itself) accessed directly
or indirectly by the hook will be accessed as the same user.
In other words, be alert to potential permission-related
problems that could prevent the hook from performing the tasks
it is designed to perform.</p><p>There are nine hooks implemented by the Subversion
repository, and you can get details about each of them in
<a class="xref" href="svn.ref.reposhooks.html" title="Repository Hooks">the section called “Repository Hooks”</a>. As a repository
administrator, you'll need to decide which of hooks you wish
to implement (by way of providing an appropriately named and
permissioned hook program), and how. When you make this
decision, keep in mind
the big picture of how your repository is deployed.
For example, if you are using server configuration
to determine which users are permitted to commit
changes to your repository, then you don't need to do this
sort of access control via the hook system.</p><p>There is no shortage of Subversion hook programs and
scripts freely available either from the Subversion community
itself or elsewhere. These scripts cover a wide range of
utility—basic access control, policy adherence checking,
issue tracker integration, email- or syndication-based commit
notification, and beyond. See <a class="xref" href="svn.3rdparty.html" title="Appendix D. Third Party Tools">Appendix D, <i>Third Party Tools</i></a>
for discussion of some of the most commonly used hook
programs. Or, if you wish to write your own, see <a class="xref" href="svn.developer.html" title="Chapter 8. Embedding Subversion">Chapter 8, <i>Embedding Subversion</i></a>.</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>While hook scripts can do almost
anything, there is one dimension in which hook script
authors should show restraint: do <span class="emphasis"><em>not</em></span>
modify a commit transaction using hook scripts. While it
might be tempting to use hook scripts to automatically
correct errors or shortcomings or policy violations present
in the files being committed, doing so can cause problems.
Subversion keeps client-side caches of certain bits of
repository data, and if you change a commit transaction in
this way, those caches become indetectably stale. This
inconsistency can lead to surprising and unexpected
behavior. Instead of modifying the transaction, you should
simply <span class="emphasis"><em>validate</em></span> the transaction in the
<code class="filename">pre-commit</code> hook and reject the commit
if it does not meet the desired requirements. As a
bonus, your users will learn the value of careful,
compliance-minded work habits.</p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="svn.reposadmin.create.bdb"></a>Berkeley DB Configuration</h3></div></div></div><p>A Berkeley DB environment is an encapsulation of one or
more databases, log files, region files and configuration
files. The Berkeley DB environment has its own set of default
configuration values for things like the number of database locks
allowed to be taken out at any given time, or the maximum size
of the journaling log files, etc. Subversion's filesystem
logic additionally chooses default values for some of the
Berkeley DB configuration options. However, sometimes your
particular repository, with its unique collection of data and
access patterns, might require a different set of
configuration option values.</p><p>The producers of Berkeley DB understand that different
applications and database environments have different
requirements, and so they have provided a mechanism for
overriding at runtime many of the configuration values for the
Berkeley DB environment: BDB checks for the presence of
a file named <code class="filename">DB_CONFIG</code> in the environment
directory (namely, the repository's
<code class="filename">db</code> subdirectory), and parses the options found in that file . Subversion itself creates
this file when it creates the rest of the repository. The
file initially contains some default options, as well as
pointers to the Berkeley DB online documentation so you can
read about what those options do. Of course, you are free to
add any of the supported Berkeley DB options to your
<code class="filename">DB_CONFIG</code> file. Just be aware that while
Subversion never attempts to read or interpret the contents of
the file, and makes no direct use of the option settings in
it, you'll want to avoid any configuration changes that may
cause Berkeley DB to behave in a fashion that is at odds with
what Subversion might expect. Also, changes made to
<code class="filename">DB_CONFIG</code> won't take effect until you
recover the database environment (using <span class="command"><strong>svnadmin
recover</strong></span>).</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="svn.reposadmin.planning.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="svn.reposadmin.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="svn.reposadmin.maint.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Strategies for Repository Deployment </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Repository Maintenance</td></tr></table></div></body></html>
