blob: c7840b9bd2dbcb99ab7d32645e732c3a96c72a03 [file] [log] [blame]
<h1>Subversion FAQ</h1>
<p>
<![CDATA[ Table of Contents ]]>
<ol>
<p>
<strong>General questions:</strong>
</p>
<li><a href="#why">Why does this project exist?</a></li>
<li><a href="#collab">Is Subversion proprietary? I heard that it
belongs to CollabNet.</a></li>
<li><a href="#stable">Is Subversion stable enough for me to use for my
own projects?</a></li>
<li><a href="#interop">What is Subversion's pre-1.0 interoperability
policy?</a></li>
<li><a href="#portability">What operating systems does Subversion run
on?</a></li>
<li><a href="#filesystem">What's all this about a new filesystem? Is
it like ext2?</a></li>
<li><a href="#apache-extension">I heard that Subversion is an Apache
extension?</a></li>
<li><a href="#need-apache">Does this mean I have to set up Apache to
use Subversion?</a></li>
<li><a href="#multiple-apachim">I run Apache 1.x right now, and can't
switch to Apache 2.0 just to serve Subversion repositories.
Does that mean I can't run a Subversion server?</a></li>
<li><a href="#feature-x">Why don't you do X, just like SCM system Y?</a></li>
<li><a href="#globalrev">Why does the entire repository share the
same revision number? I want each of my projects to have their
own revision numbers. </a></li>
<li><a href="#release">When's the next release?</a></li>
<li><a href="#more-information">I have other questions. Where can I
get more information?</a></li>
<p>
<strong>How-to:</strong>
</p>
<li><a href="#co-svn">How do I check out the Subversion code?</a></li>
<li><a href="#repository">How do I create a repository? How do I
import data into it?</a></li>
<li><a href="#cvs2svn">How do I convert an existing CVS repository
into a Subversion repository?</a></li>
<li><a href="#proxy">What if I'm behind a proxy?</a></li>
<li><a href="#paranoid">My admins don't want me to have a HTTP server for
Subversion. What can I do if I still want remote usage?</a></li>
<li><a href="#multi-proj">How do I manage several different projects
under Subversion?</a></li>
<li><a href="#multi-merge">How do I merge two completely separate repositories?</a></li>
<li><a href="#bdblogs">Why is my repository taking up so much disk space?</a></li>
<li><a href="#reposperms">How do I set repository permissions correctly?</a></li>
<li><a href="#readonly">Why do read-only operations still need repository write access?</a></li>
<li><a href="#removal">How do I completely remove a file from the repository's history?</a></li>
<li><a href="#patch">How do I submit a patch for Subversion?</a></li>
<li><a href="#in-place-import">How can I do an in-place 'import'
(i.e. add a tree to subversion without moving or deleting the
original working copy)?</a></li>
<p>
<strong>Troubleshooting:</strong>
</p>
<li><a href="#wedged-repos">What the heck! Every time I try to access
my repository, the process just hangs. Is my repository
corrupt?</a></li>
<li><a href="#wedged-wc">What the heck! Every time I try to run a svn
command, it says my working copy is locked. Is my working copy
corrupt?</a></li>
<li><a href="#unrecognized-url-error">I just built the distribution
binary, and when I try to check out Subversion, I get an error
about an "Unrecognized URL scheme." What's up with that?</a></li>
<li><a href="#db-recover">I'm getting errors finding or opening a repository,
but I know my repository URL is correct. What's wrong?</a></li>
<li><a href="#configure-sed-error">When I run `<tt>configure</tt>', I
get errors <tt>subs-1.sed&nbsp;line&nbsp;38:&nbsp;Unterminated&nbsp;`s'&nbsp;command</tt>. What's wrong?</a></li>
<li><a href="#windows-msvc-build">I'm having trouble building
Subversion under Windows with MSVC++ 6.0. What should I do?</a></li>
<li><a href="#windows-repository">I'm running Subversion under windows
and I can create a repository fine, but I get errors trying to
import or check out from it. What's wrong?</a></li>
<li><a href="#write-over-dav">I'm having trouble doing write
operations to a Subversion repository over a network.</a></li>
<li><a href="#windows-xp-server">Under Windows XP, the Subversion
server sometimes seems to send out corrupted data. Can this really be
happening?</a></li>
<li><a href="#ethereal">What is the best method of doing a network
trace of the conversation between a Subversion client and server?</a></li>
<li><a href="#revert">Why does the <tt>svn revert</tt> require an
explicit target? Why is it not recursive by default? These
behaviors differ from almost all the other subcommands.</a></li>
<li><a href="#db3db4">When I start Apache, mod_dav_svn complains about
a "bad database version", that it found db-3.X, rather than
db-4.X.</a></li>
<li><a href="#redhat-db">I'm getting "Function not implemented" errors on
RedHat 9, and nothing works. How do I fix this?</a></li>
<li><a href="#no-author">Why does SVN log say "(no author)" for files
committed or imported via Apache (ra_dav)?</a></li>
<p>
<strong>Developer questions:</strong>
</p>
<li><a href="#ramdisk-tests">How do I run the regression tests in a
ram disk?</a></li>
<p>
<strong>References:</strong>
</p>
<li><a href="#http-methods">What are all the HTTP methods Subversion
uses?</a></li>
<li><a href="#bikeshed">What's a 'bikeshed'?</a></li>
<li><a href="#baton">What's a 'baton'?</a></li>
</ol>
<![CDATA[=========================================================]]>
<p>
<hr>
<p>
<h2>General questions:</h2>
<p>
<![CDATA[-----------------------------------------------------------]]>
<h3><a name="why">Why does this project exist?</a></h3>
<p>To take over the CVS user base. Specifically, we're writing a new
version control system that is very similar to CVS, but fixes many
things that are broken. See our front page.</p>
<![CDATA[-----------------------------------------------------------]]>
<h3><a name="collab">Is Subversion proprietary? I heard that it
belongs to CollabNet.</a></h3>
<p>No, Subversion is open source / free software. CollabNet pays the
salaries of several full-time developers, and holds the copyright on
the code, but that copyright is <a
href="http://subversion.tigris.org/project_license.html">an
Apache/BSD-style license</a>
which is fully compliant with the <a
href="http://www.debian.org/social_contract#guidelines">Debian Free
Software Guidelines</a>. In other words, you are free to download,
modify, and redistribute Subversion as you please; no permission from
CollabNet or anyone else is required.</p>
<![CDATA[-----------------------------------------------------------]]>
<h3><a name="stable">Is Subversion stable enough for me to use for my
own projects?</a></h3>
<p><b>We think so!</b> Subversion has small bugs here and there, but
in general is reliable enough for real use. If it were any other
project, it probably would have been declared "1.0" long ago; but
because it's version-control software, we're being extra paranoid
about labeling.</b></p>
<ul>
<li>We believe that Subversion is stable and have confidence in our
code, in fact, we've been self-hosting since September of 2001--eating
our own caviar so to speak. We declared "alpha" because we're ready for
the world to try Subversion.</li>
<li>After nearly two years of self-hosting, we haven't lost any data
at all.</li>
<li>Lots of people are already using Subversion in production,
and are having great results. See the <a href="svn-repositories.html">svn
repositories</a> list for just a few examples.</li>
<li>The repository db schema is stable now and should only undergo one
more major change before 1.0. These migrations have happened before,
and we already have dump/load utilities available to aid you in the
migration.</li>
<li>In order to make Subversion as stable as possible, we need more
people to use Subversion. If you use Subversion on a day-to-day basis,
you can help us find and fix any bugs that might turn up. It may sound
risky at first, but odds are that if you find any bugs they will be minor
inconveniences as opposed to data destroyers.</li>
<li>For many more reasons, read the feature list on the <a
href="http://subversion.tigris.org/">Subversion home page</a>.
</li>
</ul>
<p><font color="red"><b>WARNING</b></font>: while Subversion is
definitely <i>reliable</i>, the API and protocols still change from
release to release, so it would be wrong to say it is <i>stable</i>.
That's why it's still Alpha sofware. This means that if you depend on
Subversion, you should <b>not</b> be using whatever binary packages
ship in your distribution, they are most likely months old, and will
no longer interoperate with modern clients or servers. The developers
release every month or so, and won't accept bug reports on old releases!</p>
<p>What does this mean to you? It means that if you depend on
Subversion before it hits 1.0, you should <b>always</b> use the latest
release, even if it means building from source. This requires
diligence: subscribe to the dev list, notice when new releases come
out, and upgrade. If you don't do this, you may (one day)
accidentally discover that your clients and servers no longer
<a href="#interop">interoperate.</a></p>
<![CDATA[-----------------------------------------------------------]]>
<h3><a name="interop">What is Subversion's pre-1.0 interoperability
policy?</h3>
<p>For the WebDAV network layer: the client and server are guaranteed
to work as long as they aren't more than one major release version
apart. (For example, a 0.25.X client will talk to a 0.24.X or 0.26.X
server.)</p>
<p>For the custom 'svnserve' network layer: the client and server must
have <i>identical</i> release numbers. (This policy may change
soon.)</p>
<![CDATA[-----------------------------------------------------------]]>
<h3><a name="portability">What operating systems does Subversion run
on?</a></h3>
<p>All modern flavors of Unix, Win32, BeOS, OS/2, MacOS X.</p>
<p>Subversion is written in ANSI C and uses APR, the <a
href="http://apr.apache.org">Apache Portable Runtime</a> library, as a
portability layer. Although the Subversion client will compile
anywhere APR does, the Subversion server depends on <a
href="http://www.sleepycat.com">Berkeley DB</a> (as well as Apache
2.X, but Apache is as portable as APR). In theory Berkeley DB is
portable to most of those platforms as well (except Win95/Win98, where
it's known not to work due to shared-memory segment problems). In
practice, it's difficult to get the Subversion repository running on
non-Unix platforms; if you succeed, we'd like to hear about it.</p>
<![CDATA[-----------------------------------------------------------]]>
<h3><a name="filesystem">What's all this about a new filesystem? Is
it like ext2?</a></h3>
<p>No. The "Subversion Filesystem" is not a kernel-level filesystem that
one would install in an operating system. Instead, it refers to the
design of Subversion's repository. The repository is built on a
database (currently <a href="http://www.sleepycat.com">Berkeley
DB</a>) and exports a C API that <i>simulates</i> a filesystem -- a
versioned filesystem. Thus writing a program to access the repository
is like writing against other filesystem APIs. The main difference is
that this particular filesystem doesn't lose data when written to; old
versions of files and directories are saved.</p>
<![CDATA[-----------------------------------------------------------]]>
<h3><a name="apache-extension">I heard that Subversion is an Apache
extension?</a></h3>
<p>No. Subversion is a set of libraries. It comes with a command-line
client that uses them. The Subversion <i>server</i> is Apache + <a
href="http://www.webdav.org/mod_dav">mod_dav</a> + mod_dav_svn, and
the last module uses the Subversion libraries to speak to a
repository. For more information about how Subversion uses WebDAV as
its network protocol, see our <a
href="http://subversion.tigris.org/servlets/ProjectDocumentList">docs.</a>
Also, as an alternative to Apache, you can use a small standalone
Subversion server process. This will allow you to tunnel a custom
protocol over ssh.</p>
<![CDATA[-----------------------------------------------------------]]>
<h3><a name="need-apache">Does this mean I have to set up Apache to
use Subversion?</a></h3>
<p>The short answer: no.</p>
<p>The long answer: if you just want to access a repository, then you
only need to build a Subversion client. If you want to <b>host</b> a
networked repository, then you either need to set up Apache2 or use
our standalone server process over ssh.</p>
<p>For more details about setting up a network accessible Subversion
server, please read our <a
href="http://svn.collab.net/repos/svn/trunk/INSTALL">INSTALL</a> document.</p>
<![CDATA[-----------------------------------------------------------]]>
<h3>I run Apache 1.x right now, and can't switch to Apache 2.0 just to
serve Subversion repositories. <a name="multiple-apachim">
Does that mean I can't run a Subversion server?</a></h3>
<p> Don't worry, you can run Apache 2.0 on a different port, while
continuing to run Apache 1.x on port 80. Different versions of Apache
can happily coexist on the same machine. Just change the
<tt>Listen</tt> directive in httpd.conf from "<tt>Listen&nbsp;80</tt>"
to "<tt>Listen&nbsp;8080</tt>" or whatever port number you want, and
make sure to specify that port when you publish your repository URL
(e.g., <tt>http://svn.mydomain.com:8080/repos/blah/trunk/</tt>).</p>
<![CDATA[-----------------------------------------------------------]]>
<h3><a name="feature-x">Why don't you do X, just like SCM system Y?</a></h3>
<p>We aren't attempting to break new ground in SCM systems, nor are we
attempting to imitate all the best features of every SCM system out
there. We're trying to replace CVS. See the first question.</p>
<![CDATA[-----------------------------------------------------------]]>
<h3><a name="globalrev">Why does the entire repository share the
same revision number? I want each of my projects to have their
own revision numbers.</a></h3>
<p>
The global revision number attached to the repository as a whole is
meaningless from a user's perspective. It's an internal mechanism that
accomplishes the goal of the underlying schema design. It just so
happens to be exposed so that the user's interface can sometimes be a
little more convenient than always having to type obnoxiously long
date/time strings.
</p>
<p>
The revision number is only relevant to the repository, and user
convenience. It has <b>no</b> impact on any other factor of what you
store in the repository. Repository revision number bumps aren't
nearly useful enough to be an accurate indication of the real rate of
change of a given code base. There are other more complicated ways to
get a much better picture of a code-base's rate of change.
</p>
<![CDATA[-----------------------------------------------------------]]>
<h3><a name="release">When's the next release?</a></h3>
<p>See our status page, <a
href="http://subversion.tigris.org/project_status.html">
http://subversion.tigris.org/project_status.html</a>.</p>
<![CDATA[-----------------------------------------------------------]]>
<h3>I have other questions. Where can I get more<a
name="more-information"> information?</a></h3>
<p>Please send your questions or concerns to the Subversion Development <a
href="mailto:dev@subversion.tigris.org">mailing list</a>. Alternatively,
several Subversion users and developers can usually be contacted via IRC on
channel #svn on <a
href="http://www.openprojects.net">irc.openprojects.net</a>.</p>
<![CDATA[=========================================================]]>
<p>
<hr>
<p>
<h2>How-to:</h2>
<p>
<![CDATA[-----------------------------------------------------------]]>
<h3><a name="co-svn">How do I check out the Subversion code?</a></h3>
<p>Use the subversion client:
<pre>
$ svn co http://svn.collab.net/repos/svn/trunk subversion
</pre>
<p>
That will check out a copy of the Subversion source tree into a
directory named subversion on your local machine.
<![CDATA[-----------------------------------------------------------]]>
<h3><a name="repository">How do I create a repository? How do I
import data into it?</a></h3>
<p>See <a
href="http://svn.collab.net/repos/svn/trunk/README">
http://svn.collab.net/repos/svn/trunk/README</a>; specifically, look
at section IV, the "Quickstart Guide".</p>
<![CDATA[-----------------------------------------------------------]]>
<h3><a name="cvs2svn">How do I convert an existing CVS repository
into a Subversion repository?</a></h3>
We are currently working on a script to convert CVS repositories to
Subversion--It's called <a
href="http://svn.collab.net/repos/svn/trunk/tools/cvs2svn/cvs2svn.py">cvs2svn.py</a>.
Note that it is <b>still under development</b>, so only use it on a
copy of your CVS repository and <b>double check your results</b>. Be
sure to read the <a
href="http://svn.collab.net/repos/svn/trunk/tools/cvs2svn/README">README</a>
for cvs2svn. <p>
cvs2svn.py will be completed and well tested for Subversion's 1.0
release, but for now, use it with caution.
<![CDATA[-----------------------------------------------------------]]>
<h3><a name="proxy">What if I'm behind a proxy?</a></h3>
<p>The Subversion client can go through a proxy, if you configure it
to do so. First, edit your "servers" configuration file
to indicate which proxy to use. The files location depends on your
operating system. On Linux or Unix it is located in the directory
"~/.subversion". On Windows it is in "%APPDATA%\Subversion". (Try
"echo %APPDATA%", note this is a hidden directory.)</p>
<p>There are comments in the file explaining what to do. If you don't
have that file, get the latest Subversion client and run any command;
this will cause the configuration directory and template files to be
created.</p>
<p>Older versions of Subversion, including the 0.14.3 bootstrap
tarball, use the file ~/.subversion/proxies to define the proxy
settings. This file is ignored by the current version of
Subversion.</p>
<p>Next, you need to make sure the proxy server itself supports all
the HTTP methods Subversion uses. Some proxy servers do not support
these methods by default: PROPFIND, REPORT, MERGE, MKACTIVITY,
CHECKOUT. In general, solving this depends on the particular proxy
software. For Squid, the config option is</p>
<pre>
# TAG: extension_methods
# Squid only knows about standardized HTTP request methods.
# You can add up to 20 additional "extension" methods here.
#
#Default:
# none
extension_methods REPORT MERGE MKACTIVITY CHECKOUT
</pre>
<p>(Squid 2.4 and later already knows about PROPFIND.)</p>
<p>See also "<a href="#http-methods">What are all the HTTP methods
Subversion uses?</a>" for advice on additional HTTP methods to allow
through your proxy.</p>
<p>If it's difficult or impossible to get the proxy to allow
Subversion traffic, but you want to check out the Subversion sources,
you may be able to go around the proxy. Some proxies that filter port
80 nevertheless allow anything on port 81. For this reason, the
<tt>svn.collab.net</tt> repository server listens on port 81 as well
as on port 80. Try:</p>
<pre>
svn checkout http://svn.collab.net:81/repos/svn/trunk subversion
</pre>
<p>and maybe the proxy will let you through. Another strategy is to
attempt the checkout over SSL, which many proxies allow:</p>
<pre>
svn checkout https://svn.collab.net/repos/svn/trunk subversion
</pre>
<p>Of course, your svn client will have to have been built with ssl
support; just pass <tt>--with-ssl</tt> to subversion's
<tt>./configure</tt> script. You can check to see whether the 'https'
schema is supported by running <tt>svn --version</tt>.</p>
<![CDATA[=========================================================]]>
<h3><a name="paranoid"/>My admins don't want me to have a HTTP server for
Subversion. What can I do if I still want remote usage?</h3>
<p>If you previously used CVS, you may have used SSH to login to the
CVS server. The ra_svn Subversion access method is the equivalent way of doing
this with Subversion. Just use the "svn+ssh" prefix to your Subversion
repository URL.
<pre>
$ svn checkout svn+ssh://your.domain.com/full/path/to/repository
</pre>
</p>
<p>The preferred solution would be to use ra_dav combined
with an Apache HTTP server configured with mod_ssl and appropriate
authentication support. This should provide enough security for most
users. However, we realize that there are places that do not allow
adding servers of any kind with external connectivity.</p>
<p>However, another solution that can be used instead is to leverage
SSH port forwarding to connect to the protected server via ra_dav.
You would connect via SSH to a machine behind your firewall that can
access your Subversion server. Note that this SSH server does
<b>not</b> have to be the same as where Subversion is installed. It
can be, but it doesn't have to be.</p>
<p>Then, you create a local port forward that connects to the HTTP
server that houses your Subversion repository. You would then
'connect' to the Subversion repository via this local port. Then,
the request will be sent 'tunneled' via SSH server to your Subversion
server.</p>
<p>An example: a Subversion ra_dav setup is behind your company firewall
at 10.1.1.50 (call it svn-server.example.com). Your company allows SSH
access via publicly accessible ssh-server.example.com. Internally, you
can access the Subversion repository via
http://svn-server.example.com/repos/ours.</p>
<p><i>Example</i>: client connecting to ssh-server with port-forwarding
and checking out via the port forward</p>
<pre>
% ssh -L 8888:svn-server.example.com:80 me@ssh-server.example.com
% svn checkout http://localhost:8888/repos/ours
</pre>
<p>Note that your svn-server.example.com could also have its httpd
instance running on an unpriviliged port by a non-trusted user. This
will allow your Subversion server not to require root access.</p>
<!-- Can you use svn switch to switch your WC between your internal and
external Subversion server? I think so. -->
<p>Joe Orton notes</p>
<pre>
The server is sensitive to the hostname used in the Destination header
in MOVE and COPY requests, so you have to be a little careful here - a
"ServerAlias localhost" may be required to get this working properly.
</pre>
<p>Some links on SSH port forwarding</p>
<ul>
<li><a href="http://www.onlamp.com/pub/a/onlamp/excerpt/ssh_11/index3.html"
>http://www.onlamp.com/pub/a/onlamp/excerpt/ssh_11/index3.html</a></li>
<li><a href="http://csociety.ecn.purdue.edu/~sigos/projects/ssh/forwarding/"
>http://csociety.ecn.purdue.edu/~sigos/projects/ssh/forwarding/</a></li>
<li><a href="http://www.zip.com.au/~roca/ttssh.html">TTSSH: A Win32 SSH client capable of port forwarding</a></li>
</ul>
<![CDATA[=========================================================]]>
<h3><a name="multi-proj">How do I manage several different projects under Subversion?</a></h3>
<p>It depends upon the projects involved. If the projects are
related, and are likely to share data, then it's best to create one
repository with several subdirectories like this:
<pre>
$ svnadmin create /repo/svn
$ svn mkdir file:///repo/svn/projA
$ svn mkdir file:///repo/svn/projB
$ svn mkdir file:///repo/svn/projC
</pre>
If the projects are completely unrelated, and not likely to share data
between them, then it's probably best to create separate and unrelated
repositories.
<pre>
$ mkdir /repo/svn
$ svnadmin create /repo/svn/projA
$ svnadmin create /repo/svn/projB
$ svnadmin create /repo/svn/projC
</pre>
<p>
The difference between these two approaches is this (as explained by
Ben Collins-Sussman &lt;sussman@collab.net&gt;):
<ul>
<li>
<pre>
In the first case, code can easily be copied or moved around
between projects, and the history is preserved. ('svn cp/mv'
currently only works within a single repository.)
</pre>
</li>
<li>
<pre>
Because revision numbers are repository-wide, a commit to any
project in the first case causes a global revision bump. So it
might seem a bit odd if somebody has 'projB' checked out, notices
that 10 revisions have happened, but projB hasn't changed at
all. Not a big deal, really. Just a little weird at first.
This already happens to svn, everytime people commit to
rapidsvn. :-)
</pre>
</li>
<li>
<pre>
The second case might be easier to secure; it's easier to insulate
projects from each other (in terms of users and permissions)
using Apache's access control. In the 1st case, you'll need a
fancy hook script in the repository that distinguishes projects
("is this user allowed to commit to this particular subdir?") Of
course, we already have such a script, ready for you to use.
</pre>
</li>
</ul>
<![CDATA[=========================================================]]>
<h3><a name="multi-merge">How do I merge two completely separate repositories?</a></h3>
<p>If you don't care about retaining all the history of one of the
repositories, you can just create a new directory under one project's
repository, then import the other.
<p>If you care about retaining the history of both, then you can use
'svnadmin dump' to dump one repository, and 'svnadmin load' to load it into
the other repository. The revision numbers will be off, but you'll
still have the history.
<p>Peter Davis &lt;peter@pdavis.cx&gt; also explains a method using svn's
equivalent to CVS modules:
<p><blockquote>
<p>As long as the merging takes place in separate directory
trees, you can use svn's version of CVS modules.
<p>Set the <em>svn:externals</em> property on a directory to checkout
directories from other repositories whenever the original
directory is checked out. The repository remains separate,
but in the working copy it appears that they have been merged.
If you commit to the imported directory, it will affect the
external repository.
<p>The merge isn't completely clean: the import only affects
working copies, so you won't be able to use a URL in the first
repository to access modules imported from the second. They
remain separate URLs.
</blockquote>
<![CDATA[=========================================================]]>
<h3><a name="bdblogs">Why is my repository taking up so much disk space?</h3>
<p>The repository stores all your data in a Berkeley DB "environment"
in the repos/db/ subdirectory. The environment contains a collection
of tables and bunch of logfiles (log.*). Berkeley DB journals all
changes made to the tables, so that the tables can be recovered to a
consistent state in case of interruptions (<a
href="#wedged-repos">more info</a>).</p>
<p>The logfiles will grow forever, eating up disk space, unless you,
(as the repository administrator) do something about it. At any given
moment, Berkeley DB is only using a couple of logfiles actively; the
rest can be safely deleted. If you keep all the logfiles around
forever, then in theory Berkeley DB can replay every change to your
repository from the day it was born. But in practice, if you're
making backups, it's probably not worth the cost in disk space.</p>
<p>Run the <code>db_archive</code> command in the db/ area to see
which log files can be deleted. You may want a cron job to do this.</p>
<pre>
$ db_archive -a -h /repos/db
/repos/db/log.000003
/repos/db/log.000004
[...]
$ db_archive -a -h /repos/db | xargs rm
# disk space reclaimed!
</pre>
<p>Or, if you are running a Subversion release <em>later</em> than
0.24.2, then there's no need to locate the correct
<code>db_archive</code> command or set of arguments. Just use
<code>svnadmin</code>:</p>
<pre>
$ svnadmin archive /repos | xargs rm
# disk space reclaimed!
</pre>
<![CDATA[=========================================================]]>
<h3><a name="reposperms">How do I set repository
permissions correctly?</a></h3>
<p>If you have multiple processes (httpd, svnserve, etc.) accessing
the repository, look at <a
href="http://svnbook.red-bean.com/html-chunk/ch05s05.html"> this
section of the Subversion Book</a>.</p>
<![CDATA[=========================================================]]>
<h3><a name="readonly">Why do read-only operations still need repository
write access?</a></h3>
<p>Certain client operations are "read-only", like checkouts and
updates. From an access-control standpoint, apache treats them as
such. But libsvn_fs (the repository filesystem API) still has to
write temporary data in order to produce tree-deltas. So the process
accessing the repository always requires both read <em>and</em> write
access to the Berkeley DB files in order to function.</p>
<p>In particular, the repository responds to many "read-only"
operations by comparing two trees. One tree is the usually the HEAD
revision, and the other is often a temporary transaction-tree -- thus
the need for write access.</p>
<![CDATA[=========================================================]]>
<h3><a name="removal">
How do I completely remove a file from the repository's history?
</a></h3>
<p>There are special cases where you might want to destroy all
evidence of a file or commit. (Perhaps somebody accidentally committed
a confidential document.) This isn't so easy, because Subversion is
deliberately designed to never lose information. Revisions are
immutable trees which build upon one another. Removing a revision from
history would cause a domino effect, creating chaos in all subsequent
revisions and possibly invalidating all working copies.</p>
<p>The project has plans, however, to someday implement an <b>svnadmin
obliterate</b> command which would accomplish the task of permanently
deleting information. (See <a
href="http://subversion.tigris.org/issues/show_bug.cgi?id=516">issue
516</a>.)</p>
<p>In the meantime, your only recourse is to <b>svnadmin dump</b> your
repository, then pipe the dumpfile through <b>svndumpfilter</b>
(excluding the bad path) into an <b>svnadmin load</b> command.</p>
<![CDATA[=========================================================]]>
<h3><a name="patch">How do I submit a patch for Subversion?</a></h3>
<p>FIRST, read the <a href="http://svn.collab.net/repos/svn/trunk/HACKING">HACKING</a> document.
<p>Once you've digested that, send a mail to the dev list with the
word [PATCH] and a one-line description in the subject, and include
the patch inline in your mail (unless your MUA munges it up
totally). Then a committer will pick it up, apply it (making any
formatting or content changes necessary), and check it in.
<p>The basic process looks like this:
<pre>
<blockquote>
$ svn co http://svn.collab.net/repos/svn/trunk subversion
$ cd subversion/www
[ make changes to project_faq.html ]
$ svn diff project_faq.html > /tmp/foo
$ Mail -s "[PATCH] FAQ updates" < /tmp/foo
</blockquote>
</pre>
Of course, the email you send should contain a nice long
explanation about what the patch does, as per the
<a href="http://svn.collab.net/repos/svn/trunk/HACKING">HACKING</a>
document, but you already know that, since you read and completely
understood it <em>before</em> actually hacking the code, right? :)
<![CDATA[=========================================================]]>
<h3><a name="in-place-import">How can I do an in-place 'import'
(i.e. add a tree to subversion without moving or deleting the
original working copy)?</a></h3>
<p>Suppose, for example, that you wanted to put some of /etc under
version control inside a brand-new repository you created using:
</p>
<pre>
# svnadmin create /root/svn
</pre>
<p>To do this you would:
</p>
<pre>
# cd /
# svn co file:///root/svn etc
# cd etc
# svn add apache samba alsa X11
# svn commit -m "configury"
</pre>
<p>This takes advantage of the a hidden feature of add which allows it
to create working copies for directories which do not yet exist in the
repository.
</p>
<![CDATA[=========================================================]]>
<p>
<hr>
<p>
<h2>Troubleshooting:</h2>
<p>
<![CDATA[-----------------------------------------------------------]]>
<h3>What the heck! Every time I try to access my repository, the
process just hangs. Is my repository <a name="wedged-repos">corrupt?</a></h3>
<p>
Your repository is not corrupt, nor is your data lost. If your process
accesses the repository directly (mod_dav_svn, svnlook, svnadmin, or
if you access a `file://' URL), then it's using Berkeley DB to access
your data. Berkeley DB is journaling system, meaning that it logs
everything it is about to do before it does so. If your process is
interrupted (Control-C, or segfault), then a lockfile is left behind,
along with a logfile describing unfinished business. Any other
process that attempts to access the database will just hang, waiting
for the lockfile to disappear. To awaken your repository, you need to
ask Berkeley DB to either finish the work, or rewind the database to a
previous state that is known to be consistent.</p>
<p><b><font color="red">WARNING:</font> you can seriously corrupt your
repository if you run recover and another process accesses the repository.
</b></p>
<p>Make absolutely sure you disable all access to the repository before
doing this (by shutting down Apache, removing executable permissions from
'svn'). Make sure you run this command as the user that owns and manages
the database, and not as root, else it will leave root-owned files in the
db directory which cannot be opened by the non-root user that manages the
database, which is typically either you or your Apache process. Also be
sure to have the correct umask set when you run recover, since failing to
do so will lock out users that are in the group allowed to access the
repository.</p>
<p>
Simply run:</p>
<pre>
svnadmin recover /path/to/repos
</pre>
<p>Once the command has completed, check the permissions in the
<code>db</code> directory of the repository.</p>
<![CDATA[-----------------------------------------------------------]]>
<h3>What the heck! Every time I try to run a svn command, it says my
working copy is locked. Is my working copy <a name="wedged-wc">
corrupt?</a></h3>
<p>
Your working copy is not corrupt, nor is your data lost. Subversion's
working copy is journaling system, meaning that it logs everything it
is about to do before it does so. If the svn client program is
interrupted (Control-C, or segfault), then one or more lockfiles are
left behind, along with logfiles describing unfinished business.
(The`svn status' command will show an 'L' next to locked directories.)
Any other process that attempts to access the working copy will fail
when it sees the locks. To awaken your working copy, you need to tell
the svn client to finish the work. Simply run:</p>
<pre>
svn cleanup working-copy
</pre>
<![CDATA[-----------------------------------------------------------]]>
<h3>I just built the distribution binary, and when I try to check out
Subversion, I get an error about an "Unrecognized URL scheme." What's up
with<a name="unrecognized-url-error"> that?</a></h3>
<p>Subversion uses a plugin system to allow access to repositories.
Currently there are three of these plugins: ra_local allows access to
a local repository, ra_dav which allows access to a repository via
WebDAV, and ra_svn allows local or remote access via the svnserve
server. When you attempt to perform an operation in subversion, the
program tries to dynamically load a plugin based on the URL scheme. A
`file://' URL will try to load ra_local, and an `http://' URL will try
to load ra_dav.</p>
<p>The error you are seeing means that the dynamic linker/loader can't find
the plugins to load. This normally happens when you build subversion with
shared libraries, then attempt to run it without first running 'make
install'. Another possible cause is that you ran make install, but the
libraries were installed in a location that the dynamic linker/loader
doesn't recognize. Under Linux, you can allow the linker/loader to find the
libraries by adding the library directory to /etc/ld.so.conf and running
ldconfig. If you don't wish to do this, or you don't have root access, you
can also specify the library directory in the LD_LIBRARY_PATH environment
variable.</p>
<![CDATA[-----------------------------------------------------------]]>
<h3><a name="db-recover">I'm getting errors finding or opening a repository,
but I know my repository URL is correct. What's wrong?</a></h3>
<p>See <a href="#wedged-repos">this faq.</a></p>
<![CDATA[-----------------------------------------------------------]]>
<h3>When I run `<tt>configure</tt>', I get errors about
<tt>subs-1.sed&nbsp;line&nbsp;38:&nbsp;Unterminated&nbsp;`s'&nbsp;command</tt>.
What<a name="configure-sed-error">'s wrong?</a></h3>
<p>
You probably have old copies of
<tt>/usr/local/bin/apr-config</tt> and
<tt>/usr/local/bin/apu-config</tt> on your system. Remove them, make
sure the <tt>apr/</tt> and <tt>apr-util/</tt> that you're
building with are completely up-to-date, and try again.
</p>
<![CDATA[-----------------------------------------------------------]]>
<h3>I'm having trouble building Subversion under Windows with MSVC++ 6.0.
<a name="windows-msvc-build"> What should I do?</a></h3>
<p>
Probably you just need to get the latest platform SDK. The one that
ships with VC++ 6.0 is not recent enough.
</p>
<![CDATA[-----------------------------------------------------------]]>
<h3>I'm running Subversion under windows and I can create a repository
fine, but <a name="windows-repository">I get errors trying to import
or check out from it. What's wrong?</a></h3>
<p>If the error looks something like:
<pre>
svn_error: #21085 : <URL is not a versioned resource>
svn_ra_local__split_URL: Unable to find valid repository
</pre>
Then the problem is that Subversion doesn't yet handle file URLs that have a
drive specification. Try changing to that drive then doing an import without
the drive spec. For example:
<pre>
d:
svn import file:///some/path/to/repos/on/d/drive e:\file\to\be\imported
</pre>
<![CDATA[-----------------------------------------------------------]]>
<h3>I'm having trouble doing write <a name="write-over-dav">
operations to a Subversion repository over a network.</a></h3>
<p>For example, one user reported that imports worked fine over local
access:
<ul>
<pre>
$ mkdir test
$ touch test/testfile
$ svn import file:///var/svn/test test test -m "Initial import"
Adding test/testfile
Transmitting file data .
Committed revision 1.
</pre>
</ul>
But not from a remote host:
<ul>
<pre>
$ svn import http://svn.sabi.net/test testfile -m "import"
nicholas's password: xxxxxxx
svn_error: #21110 : <Activity not found>
The specified activity does not exist.
</pre>
</ul>
</p>
<p> We've seen this when the REPOS/dav/ directory is not writable by
the httpd process. Check the permissions to ensure Apache can write
to the <tt>dav/</tt> directory (and to <tt>db/</tt>, of course). </p>
<![CDATA[=========================================================]]>
<h3>Under Windows XP, the Subversion server sometimes seems to send
out corrupted data. <a name="windows-xp-server"> Can this really
be happening?</a></h3>
<p>You need to install Window XP Service Pack 1. You can get all
sorts of information about that Service Pack here:</p>
<ul>
<a href="http://support.microsoft.com/default.aspx?scid=kb;EN-US;q317949"
>http://support.microsoft.com/default.aspx?scid=kb;EN-US;q317949</a>
</ul>
<![CDATA[-----------------------------------------------------------]]>
<h3><a name="ethereal">What is the best method of doing a network
trace of the conversation between a Subversion client and
server?</a></h3>
<p>Use <a href="http://ethereal.ntop.org/">Ethereal</a> to eavesdrop
on the conversation:
<!-- TODO: Make these instructions less specific to ra_dav. -->
<ol>
<li>Pull down the <i>Capture</i> menu, and choose <i>Start</i>.</li>
<li>Type <code>port 80</code> for <i>Filter</i>, and turn off
promiscuous mode.</li>
<li>Run your Subversion client.</li>
<li>Hit <i>Stop</i> (probably in a little box). Now you have a
capture. It looks like a huge list of lines.</li>
<li>Click on the <i>Protocol</i> column to sort.</li>
<li>Then, click on the first relevant TCP line to select it.</li>
<li>Right click, and choose <i>Follow TCP Stream</i>. You'll be
presented with the request/response pairs of the Subversion
client's HTTP conversion.</li>
</ol>
The above instructions are specific to the graphical version of
Ethereal, and may not apply to the commandline version (whose binary
is usually named tethereal).</p>
<p>Alternatively, if you have an up-to-date client (more recent than
the 0.16 tarball) you may set the <tt>neon-debug-mask</tt> parameter in your
<tt>servers</tt> configuration file to cause neon's debugging output
to appear when you run the <tt>svn</tt> client. The numeric value of
<tt>neon-debug-mask</tt> is a combination of the <tt>NE_DBG_...</tt> values
in the header file <tt>ne_utils.h</tt>. For neon 0.23.7 setting
<tt>neon-debug-mask</tt> to 130 (i.e. <tt>NE_DBG_HTTP+NE_DBG_HTTPBODY)</tt>
will cause the HTTP data to be shown.</p>
<p>You may well want to disable compression when doing a network
trace, see the <tt>compression</tt> parameter in the <tt>config</tt>
configuration file.</p>
<![CDATA[-----------------------------------------------------------]]>
<h3><a name="revert">Why does the <tt>svn revert</tt> require an
explicit target? Why is it not recursive by default? These
behaviors differ from almost all the other subcommands.</a></h3>
<p>The short answer: it's for your own good.</p>
<p>Subversion places a very high priority on protecting your data, and
not just your versioned data. Modifications that you make to
already-versioned files, and new files scheduled for addition to the
version control system, must be treated with care.</p>
<p>Making the <tt>svn revert</tt> command require an explicit
target&mdash;even if that target is just '.'&mdash;is one way of
accomplishing that. This requirement (as well as requiring you to
supply the <tt>--recursive (-R)</tt> flag if you want that behavior)
is intended to make you really think about what you're doing, because
once your files are reverted, your local modifications are gone
forever.</p>
<![CDATA[-----------------------------------------------------------]]>
<h3><a name="db3db4">When I start Apache, mod_dav_svn complains about
a "bad database version", that it found db-3.X, rather than
db-4.X.</a></h3>
<p>Your apr-util linked against DB-3, and svn linked against DB-4.
Unfortunately, the DB symbols aren't different. When mod_dav_svn is
loaded into Apache's process-space, it ends up resolving the
symbol names against apr-util's DB-3 library.</p>
<p>The solution is to make sure apr-util compiles against DB-4. You
can do this by passing specific switches to either apr-util's or
apache's configure: "--with-dbm=db4 --with-berkeley-db=/the/db/prefix".</p>
<![CDATA[=========================================================]]>
<h3><a name="redhat-db">I'm getting "Function not implemented" errors on RedHat
9, and nothing works. How do I fix this?</a></h3>
<p>This is not really a problem with Subversion, but it often affects
Subversion users.</p>
<p>RedHat 9 ships with a Berkeley DB library that relies on the kernel
support for NPTL (the Native Posix Threads Library).</p>
<p>The kernels that RedHat provides have this support built in, but if you
compile your own kernel, then you may well not have the NPTL support. If that
is the case, then you will see errors like this:
<blockquote><pre>
svn: Berkeley DB error
svn: Berkeley DB error while creating environment for filesystem tester/db:
Function not implemented
</pre></blockquote>
This can be fixed in one of several ways:
<ul>
<li>Rebuild db4 for the kernel you're using.</li>
<li>Use a RedHat 9 kernel.</li>
<li>Apply the NPTL patches to the kernel you're using.</li>
<li>Use a recent (2.5.x) kernel with the NPTL support included.</li>
</ul>
</p>
<![CDATA[-----------------------------------------------------------]]>
<h3><a name="no-author">Why does SVN log say "(no author)" for files
committed or imported via Apache (ra_dav)?</a></h3>
<p>If you allow anonymous write access to the repository via Apache,
the Apache server never challenges the SVN client for a username, and
instead permits the write operation without authentication. Since
Subversion has no idea who did the operation, this results in a log
like this:</p>
<blockquote><pre>
$ svn log
------------------------------------------------------------------------
rev 24:&nbsp; (no author) | 2003-07-29 19:28:35 +0200 (Tue, 29 Jul 2003)
</pre></blockquote>
<p>See the Subversion Book (<a
href="http://svnbook.red-bean.com/book.html#svn-ch-5-sect-4"
>"Networking a Repository"</a>)
to learn about configuring access restrictions in Apache.</p>
<![CDATA[=========================================================]]>
<p>
<hr>
<p>
<h2>Developer questions:</h2>
<p>
<h3><a name="ramdisk-tests">How do I run the regression tests in a
ram disk?</a></h3>
<p>
See
<a href="http://www.contactor.se/~dast/svn/archive-2003-02/0068.shtml"
>http://www.contactor.se/~dast/svn/archive-2003-02/0068.shtml</a>.
</p>
<![CDATA[=========================================================]]>
<p>
<hr>
<p>
<h2>References:</h2>
<p>
<h3><a name="http-methods">What are all the HTTP methods Subversion
uses?</a></h3>
<p>The following email says it all. As the author points out,
Subversion does not actually use all of these WebDAV/DeltaV methods
yet, but it probably will someday, so if you're configuring a proxy,
you might as well allow all of them:</p>
<p>
<blockquote>
<pre>
From: Nuutti Kotivuori &lt;naked@iki.fi&gt;
Subject: Re: list of HTTP messages used by svn?
To: "Hamilton Link" &lt;helink@sandia.gov&gt;
Cc: dev@subversion.tigris.org
Date: Sat, 10 Aug 2002 13:51:52 +0300
Hamilton Link wrote:
&gt; Is there a full list of the HTTP methods svn uses somewhere, that
&gt; someone could piont me to? From the documentation I can find (in
&gt; particular project_faq.html and INSTALL), the list of methods svn
&gt; uses include at least the following:
&gt;
&gt; GET, PROPFIND, REPORT, OPTIONS, MERGE, MKACTIVITY, and CHECKOUT
&gt;
&gt; But since the lists I can find are only partial lists and nowhere
&gt; does it suggest these are all the ones used, I'm reluctant to make
&gt; any assumptions.
&gt;
&gt; If I had a complete list, I could go to the corp. proxy guy once
&gt; instead of many times, and reduce the risk of pissing him off and
&gt; being left with inadequate svn support in the proxy.
<a href="http://www.webdav.org/deltav/WWW10/deltav-intro.htm">http://www.webdav.org/deltav/WWW10/deltav-intro.htm</a>
A list copied from there:
HTTP/1.1: GET, HEAD, POST, PUT, DELETE, OPTIONS, TRACE, CONNECT
WebDAV: LOCK, UNLOCK, PROPFIND, PROPPATCH, COPY, MOVE, MKCOL
DeltaV: CHECKIN, CHECKOUT, UNCHECKOUT, VERSION-CONTROL, REPORT,
UPDATE, LABEL, MERGE, MKWORKSPACE, BASELINE-CONTROL, MKACTIVITY
Subversion uses no methods outside these. It doesn't use all of them
either, but it's better to support the full WebDAV/DeltaV than just
some arbitrary subset. If the proxy being configured is a recent
Squid, it probably has everything from HTTP/1.1 and WebDAV - and then
it only needs the DeltaV extensions added.
You can give that list to your corp. proxy guy and explain to him that
he can check the RFC's for further information.
</pre>
</blockquote>
</p>
<![CDATA[-----------------------------------------------------------]]>
<h3><a name="bikeshed">What's a 'bikeshed'?</a></h3>
<p>See Poul-Henning Kamp's post to freebsd-hackers: <a href="http://www.freebsd.org/doc/en_US.ISO8859-1/books/faq/misc.html#BIKESHED-PAINTING">http://www.freebsd.org/doc/en_US.ISO8859-1/books/faq/misc.html#BIKESHED-PAINTING</a>.
</p>
<![CDATA[-----------------------------------------------------------]]>
<h3><a name="baton">What's a 'baton'?</a></h3>
<p>Throughout subversion's source code there are many references to
'baton' objects. These are just <pre>void *</pre> datastructures that
provide context to a function. In other APIs, they're often called
<pre>void *ctx</pre> or <pre>void *userdata</pre>. Subversion
developers call the structures "batons" because they're passed around
quite a bit.</p>