Subversion FAQ

    General questions:

  1. Why does this project exist?
  2. Is Subversion proprietary? I heard that it belongs to CollabNet.
  3. Is Subversion stable enough for me to use for my own projects?
  4. What is Subversion's client/server interoperability policy?
  5. What operating systems does Subversion run on?
  6. What's all this about a new filesystem? Is it like ext2?
  7. I heard that Subversion is an Apache extension? What does it use for servers?
  8. Does this mean I have to set up Apache to use Subversion?
  9. 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?
  10. Why don't you do X, just like SCM system Y?
  11. Why does the entire repository share the same revision number? I want each of my projects to have their own revision numbers.
  12. Does Subversion have changesets?
  13. When's the next release?
  14. Does Subversion support symlinks?
  15. I need a high resolution version of the Subversion logo, where can I get it?
  16. I have other questions. Where can I get more information?
  17. How-to:

  18. How do I check out the Subversion code?
  19. How do I create a repository? How do I import data into it?
  20. How do I convert an existing CVS repository into a Subversion repository?
  21. What if I'm behind a proxy?
  22. My admins don't want me to have a HTTP server for Subversion. What can I do if I still want remote usage?
  23. How do I manage several different projects under Subversion?
  24. How do I merge two completely separate repositories?
  25. Should I store my repository on a NFS server?
  26. Why is my repository taking up so much disk space?
  27. How do I set repository permissions correctly?
  28. Why do read-only operations still need repository write access?
  29. How do I completely remove a file from the repository's history?
  30. How do I change the log message for a revision after it's been committed?
  31. How do I submit a patch for Subversion?
  32. How can I do an in-place 'import' (i.e. add a tree to subversion without moving or deleting the original working copy)?
  33. What is this "dump/load cycle" people sometimes talk about when upgrading a Subversion server?
  34. How do I allow clients to authenticate against a Windows domain controller using SSPI Authentication?
  35. I don't like the ".svn" directory name, and prefer "SVN" or something else. How do I change it?
  36. I checked in a file but had the wrong case in the filename. How do I change it?
  37. I can't use tags to merge changes from a branch into the trunk like I used to with CVS, can I?
  38. Why doesn't the $Revision$ keyword do what I want? It expands to the file's last-changed revision, but I want something that will expand to the file's current revision.
  39. Troubleshooting:

  40. My repository seems to get stuck all the time, giving me errors about needing recovery (DB_RUNRECOVERY). What could be the cause?
  41. Every time I try to access my repository, the process just hangs. Is my repository corrupt?
  42. Every time I try to run a svn command, it says my working copy is locked. Is my working copy corrupt?
  43. I'm trying to commit, but Subversion says my working copy is out of date?
  44. 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?
  45. I'm getting errors finding or opening a repository, but I know my repository URL is correct. What's wrong?
  46. When I run `configure', I get errors subs-1.sed line 38: Unterminated `s' command. What's wrong?
  47. I'm having trouble building Subversion under *NIX with BerkeleyDB 4.2 What should I do?
  48. I'm having trouble building Subversion under Windows with MSVC++ 6.0. What should I do?
  49. How can I specify a Windows drive letter in a file: URL?
  50. I'm having trouble doing write operations to a Subversion repository over a network.
  51. Under Windows XP, the Subversion server sometimes seems to send out corrupted data. Can this really be happening?
  52. What is the best method of doing a network trace of the conversation between a Subversion client and server?
  53. Why does the svn revert require an explicit target? Why is it not recursive by default? These behaviors differ from almost all the other subcommands.
  54. When I start Apache, mod_dav_svn complains about a "bad database version", that it found db-3.X, rather than db-4.X.
  55. I'm getting "Function not implemented" errors on RedHat 9, and nothing works. How do I fix this?
  56. Why does SVN log say "(no author)" for files committed or imported via Apache (ra_dav)?
  57. I'm getting occasional "Access Denied" errors on Windows. They seem to happen at random. Why?
  58. On FreeBSD, certain operations (especially svnadmin create) sometimes hang. Why?
  59. I can see my repository in a web browser, but 'svn checkout' gives me an error about "301 Moved Permanently". What's wrong?
  60. I'm trying to look at an old version of my file, but svn says something about "path not found". What's going on?
  61. Why doesn't HTTP Digest auth work?
  62. Compiling with xlc on AIX, I get compilation errors. What's wrong?
  63. I checked out a directory non-recursively (with -N), and now I want to make certain subdirectories "appear". But svn up subdir doesn't work.
  64. I am trying to use mod_dav_svn with Apache on Win32 and I'm getting an error saying that the module cannot be found, yet the mod_dav_svn.so file is right there in \Apache\modules.
  65. Developer questions:

  66. How do I run the regression tests in a ram disk?
  67. References:

  68. What are all the HTTP methods Subversion uses?
  69. What's a 'bikeshed'?
  70. What's a 'baton'?


General questions:

Why does this project exist?

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.

Is Subversion proprietary? I heard that it belongs to CollabNet.

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 an Apache/BSD-style license which is fully compliant with the Debian Free Software Guidelines. In other words, you are free to download, modify, and redistribute Subversion as you please; no permission from CollabNet or anyone else is required.

Is Subversion stable enough for me to use for my own projects?

Yes, absolutely. It's ready for prime-time production.

Subversion has been in development since 2000, and became self-hosting after one year. A year later when we declared "alpha", Subversion was already being used by dozens of private developers and shops for real work. After that, it was two more years of bugfixing and stabilization until we reached 1.0. Most other projects probably would have called the product "1.0" much earlier, but we deliberately decided to delay that label as long as possible. We were aware that many people were waiting for a 1.0 before using Subversion, and had very specific expectations about the meaning of that label. So we stuck to that same standard.

What is Subversion's client/server interoperability policy?

For pre-1.0 releases of Subversion (which you shouldn't be using anymore!), the client and server are designed 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.)

Now that Subversion is beyond the 1.0 milestone, client/server interoperability policy is documented in the "Compatibility" section of the HACKING file.

What operating systems does Subversion run on?

All modern flavors of Unix, Win32, BeOS, OS/2, MacOS X.

Subversion is written in ANSI C and uses APR, the Apache Portable Runtime library, as a portability layer. The Subversion client will run anywhere APR runs, which is most places. The Subversion server (i.e., the repository side) is the same, except that it will not work on Win9x platforms (Win95/Win98/WinME), because it depends on Berkeley DB, which has shared-memory segment problems on Win9x.

To reiterate, a Subversion server can be run on all platforms except Win95/Win98/WinMe. The Subversion client can be used on any platform where APR runs.

What's all this about a new filesystem? Is it like ext2?

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 Berkeley DB) and exports a C API that simulates 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.

I heard that Subversion is an Apache extension? What does it use for servers?

No. Subversion is a set of libraries. It comes with a command-line client that uses them. There are two different Subversion server processes: either svnserve, which is small standalone program similar to cvs pserver, or Apache httpd-2.0 using a special mod_dav_svn module. svnserve speaks a custom protocol, while mod_dav_svn uses WebDAV as its network protocol. See chapter 6 in the Subversion book to learn more.

Does this mean I have to set up Apache to use Subversion?

The short answer: no.

The long answer: if you just want to access a repository, then you only need to build a Subversion client. If you want to host a networked repository, then you need to set up either Apache2 or an "svnserve" server.

For more details about setting up a network accessible Subversion server, see chapter 6 in the Subversion book.

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?

No, you can run svnserve as a Subversion server. It works extremely well.

If you want WebDAV and all the other "goodies" that come with the Apache server, then yes, you'll need Apache 2.0. It's always an option to 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 Listen directive in httpd.conf from "Listen 80" to "Listen 8080" or whatever port number you want, and make sure to specify that port when you publish your repository URL (e.g., http://svn.mydomain.com:8080/repos/blah/trunk/).

Why don't you do X, just like SCM system Y?

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.

Why does the entire repository share the same revision number? I want each of my projects to have their own revision numbers.

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.

The revision number is only relevant to the repository, and user convenience. It has no 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.

Does Subversion have Changesets?

The question is a bit loaded, because everyone seems to have a slightly different definition of "changeset", or a least a slightly different expectation of what it means for a version control system to have "changeset features".

For the purposes of this discussion, here's a simple definition of changeset: it's a collection of changes with a unique name. The changes might include textual edits to file contents, modifications to tree structure, or tweaks to metadata. In more common speak, a changeset is just a patch with a name you can refer to.

Subversion manages versioned trees as first order objects (the repository is an array of trees), and the changesets are things that are derived (by comparing adjacent trees.) Systems like Arch or Bitkeeper are built the other way around: they're designed to manage changesets as first order objects (the repository is a bag of patches), and trees are derived by composing sets of patches together.

Neither philosophy is better in absolute terms: the debate goes back at least 30 years. The two designs are better or worse for different types of software development. We're not going to discuss that here. Instead, here's an explanation of what you can do with Subversion.

In Subversion, a global revision number 'N' names a tree in the repository: it's the way the repository looked after the Nth commit. It's also the name of an implicit changeset: if you compare tree N with tree N-1, you can derive the exact patch that was committed.

For this reason, it's easy to think of "revision N" as not just a tree, but a changeset as well. If you use an issue tracker to manage bugs, you can use the revision numbers to refer to particular patches that fix bugs -- for example, "this issue was fixed by revision 9238." Somebody can then run 'svn log -r9238' to read about the exact changeset which fixed the bug, and run 'svn diff -r9237:9238' to see the patch itself. And svn's merge command also uses revision numbers. You can merge specific changesets from one branch to another by naming them in the merge arguments: 'svn merge -r9237:9238 branchURL' would merge changeset #9238 into your working copy.

This is nowhere near as complicated as a system built around changesets as primary objects, but it's still a vast convenience over CVS.

When's the next release?

See our status page, http://subversion.tigris.org/project_status.html.

Does Subversion support symlinks?

Subversion does not currently support symlinks, and there are no concrete plans to support them. The obstacle has been that symbolic links are not portable across all the platforms Subversion runs on. Therefore, any design for symlink support has to account for how the symlinks will behave in a working copy checked out into an environment that doesn't support symlinks. If you have a proposal, please share it with the developers at dev@subversion.tigris.org.

I need a high resolution version of the Subversion logo, where can I get it?

Vectorized versions of the Subversion logo are available in the logo directory of the www tree of the Subversion repository.

Specifically, an EPS version, as well as an Adobe Illustrator document are available.

I have other questions. Where can I get more information?

Please send your questions or concerns to the Subversion Users mailing list. Alternatively, several Subversion users and developers can usually be contacted via IRC on channel #svn on irc.freenode.net.


How-to:

How do I check out the Subversion code?

Use the subversion client:

	$ svn co http://svn.collab.net/repos/svn/trunk subversion

That will check out a copy of the Subversion source tree into a directory named subversion on your local machine.

How do I create a repository? How do I import data into it?

See http://svn.collab.net/repos/svn/trunk/README; specifically, look at section IV, the "Quickstart Guide".

For even more detail, read chapter 5 in The Subversion Book.

How do I convert an existing CVS repository into a Subversion repository?

Members of the Subversion development community created and maintain a tool called cvs2svn. You can find it at http://cvs2svn.tigris.org/. Note that it is still under development, so only use it on a copy of your CVS repository and double check your results. Be sure to read the README.

If cvs2svn.py does not work for you, (e.g. your repository causes it to crash, or it doesn't deal with branches and tags quite how you would like), there are at least two other conversion utilities you can try. These have different features (and possibly different bugs):

See also the Subversion links page.

What if I'm behind a proxy?

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

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.

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.

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

   #  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

(Squid 2.4 and later already knows about PROPFIND.)

See also "What are all the HTTP methods Subversion uses?" for advice on additional HTTP methods to allow through your proxy.

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 svn.collab.net repository server listens on port 81 as well as on port 80. Try:

   svn checkout http://svn.collab.net:81/repos/svn/trunk subversion

and maybe the proxy will let you through. Another strategy is to attempt the checkout over SSL, which many proxies allow:

   svn checkout https://svn.collab.net/repos/svn/trunk subversion

Of course, your svn client will have to have been built with ssl support; just pass --with-ssl to subversion's ./configure script. You can check to see whether the 'https' schema is supported by running svn --version.

My admins don't want me to have a HTTP server for Subversion. What can I do if I still want remote usage?

A simple option is to use the svnserve server instead of Apache. See chapter 6 in the Subversion book for details.

However, if your admins don't want you to run Apache, it's very likely they don't want you to run a custom server process on port 3690 either! So the rest of this answer assumes that your admins are okay with you using an existing SSH infrastructure.

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.

$ svn checkout svn+ssh://your.domain.com/full/path/to/repository

This makes your SSH program launch a private 'svnserve' process on the remote box, which accesses the repository as your UID and tunnels the information back over the encrypted link.

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 not have to be the same as where Subversion is installed. It can be, but it doesn't have to be.

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.

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.

Example: client connecting to ssh-server with port-forwarding and checking out via the port forward

% ssh -L 8888:svn-server.example.com:80 me@ssh-server.example.com
% svn checkout http://localhost:8888/repos/ours

Note that your svn-server.example.com could also have its httpd instance running on an unprivileged port by a non-trusted user. This will allow your Subversion server not to require root access.

Joe Orton notes

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.

Some links on SSH port forwarding

How do I manage several different projects under Subversion?

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:

	$ svnadmin create /repo/svn
	$ svn mkdir file:///repo/svn/projA
	$ svn mkdir file:///repo/svn/projB
	$ svn mkdir file:///repo/svn/projC
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.
	$ mkdir /repo/svn
	$ svnadmin create /repo/svn/projA
	$ svnadmin create /repo/svn/projB
	$ svnadmin create /repo/svn/projC

The difference between these two approaches is this (as explained by Ben Collins-Sussman <sussman@collab.net>):

How do I merge two completely separate repositories?

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.

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.

Peter Davis <peter@pdavis.cx> also explains a method using svn's equivalent to CVS modules:

As long as the merging takes place in separate directory trees, you can use svn's version of CVS modules.

Set the svn:externals 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.

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.

Should I store my repository on a NFS server?

No, don't ever do that. Berkeley DB does not support storage of databases on remote file systems. Some NFS servers claim that they explicitly support use of BDB on NFS-mounted partitions, but we've only ever seen BDB databases get corrupted when living on an NFS or SMB network drive.

A working copy, however, can be stored on a NFS server (i.e. your home directory is on a NFS server). On Linux NFS servers, due to the volume of renames used internally in Subversion when checking out files, some users have reported that 'subtree checking' should be disabled (it's enabled by default). Please see NFS Howto Server Guide and exports(5) for more information on how to disable subtree checking.

Why is my repository taking up so much disk space?

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 (more info).

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.

Use svnadmin to see which log files can be deleted. You may want a cron job to do this.

$ svnadmin list-unused-dblogs /repos
/repos/db/log.000003
/repos/db/log.000004
[...]

$ svnadmin list-unused-dblogs /repos | xargs rm
# disk space reclaimed!

You could instead use Berkeley DB's db_archive command:

$ db_archive -a -h /repos/db | xargs rm
# disk space reclaimed!

See also svnadmin hotcopy or hotbackup.py.

Note: If you use Berkeley DB 4.2, Subversion 0.35 or later will create new repositories with automatic log file removal enabled. You can change this by passing the --bdb-log-keep option to svnadmin create. Refer to the section about the DB_LOG_AUTOREMOVE flag in the Berkeley DB manual.

How do I set repository permissions correctly?

If you have multiple processes (httpd, svnserve, etc.) accessing the repository, look at this section of the Subversion Book.

Why do read-only operations still need repository write access?

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 and write access to the Berkeley DB files in order to function.

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.

How do I completely remove a file from the repository's history?

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.

The project has plans, however, to someday implement an svnadmin obliterate command which would accomplish the task of permanently deleting information. (See issue 516.)

In the meantime, your only recourse is to svnadmin dump your repository, then pipe the dumpfile through svndumpfilter (excluding the bad path) into an svnadmin load command. See chapter 5 of the Subversion book for details about this.

How do I change the log message for a revision after it's been committed?

Log messages are kept in the repository as properties attached to each revision. By default, the log message property (svn:log) cannot be edited once it is committed. That is because changes to revision properties (of which svn:log is one) cause the property's previous value to be permanently discarded, and Subversion tries to prevent you from doing this accidentally. However, there are a couple of ways to get Subversion to change a revision property.

The first way is for the repository administrator to enable revision property modifications. This is done by creating a hook called "pre-revprop-change" (see this section in the Subversion book for more details about how to do this). The "pre-revprop-change" hook has access to the old log message before it is changed, so it can preserve it in some way (for example, by sending an email). Once revision property modifications are enabled, you can change a revision's log message by passing the --revprop switch to svn propedit or svn propset, like either one of these:

$ svn propedit -r N --revprop svn:log URL
$ svn propset -r N --revprop svn:log "new log message" URL

where N is the revision number whose log message you wish to change, and URL is the location of the repository. If you run this command from within a working copy, you can leave off the URL.

The second way of changing a log message is to use svnadmin setlog. This must be done by referring to the repository's location on the filesystem. You cannot modify a remote repository using this command.

$ svnadmin setlog REPOS_PATH -r N FILE

where REPOS_PATH is the repository location, N is the revision number whose log message you wish to change, and FILE is a file containing the new log message. If the "pre-revprop-change" hook is not in place (or you want to bypass the hook script for some reason), you can also use the --bypass-hooks option. However, if you decide to use this option, be very careful. You may be bypassing such things as email notifications of the change, or backup systems that keep track of revision properties.

How do I submit a patch for Subversion?

FIRST, read the HACKING document.

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.

The basic process looks like this:

$ 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
Of course, the email you send should contain a nice long explanation about what the patch does, as per the HACKING document, but you already know that, since you read and completely understood it before actually hacking the code, right? :)

How can I do an in-place 'import' (i.e. add a tree to subversion without moving or deleting the original working copy)?

Suppose, for example, that you wanted to put some of /etc under version control inside a brand-new repository you created using:

     # svnadmin create /root/svn

To do this you would:

     # cd /
     # svn co file:///root/svn etc
     # cd etc
     # svn add apache samba alsa X11 
     # svn commit -m "configury"

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.

There is an issue filed for enhancing svn import to be able to convert the imported tree to a working copy automatically; see http://subversion.tigris.org/issues/show_bug.cgi?id=1328.

What is this "dump/load cycle" people sometimes talk about when upgrading a Subversion server?

Subversion's repository database schema has changed occasionally during development. Old repositories, created with a pre-1.0 development version of Subversion, may require the following operation when upgrading. If a schema change happens between Subversion releases X and Y, then repository administrators upgrading to Y must do the following:

  1. Shut down svnserve, Apache, and anything else that might be accessing the repository.
  2. svnadmin dump /path/to/repository > dumpfile.txt , using version X of svnadmin.
  3. mv /path/to/repository /path/to/saved-old-repository
  4. Now upgrade to Subversion Y (i.e., build and install Y, replacing X).
  5. svnadmin create /path/to/repository, using version Y of svnadmin.
  6. svnadmin load /path/to/repository < dumpfile.txt , again using version Y of svnadmin.
  7. Copy over hook scripts, etc, from the old repository to the new one.
  8. Restart svnserve, Apache, etc.

See http://svnbook.red-bean.com/html-chunk/ch05s03.html#svn-ch-5-sect-3.4 for more details on dumping and loading.

Note: Most upgrades of Subversion do not involve a dump and load. When one is required, the release announcement and the CHANGES file for the new version will carry prominent notices about it. If you don't see such a notice, then there has been no schema change, and no dump/load is necessary.

How do I allow clients to authenticate against a Windows domain controller using SSPI authentication?

TortoiseSVN has an excellent document that describes setting up a Subversion server on Windows. Go to http://tortoisesvn.tigris.org/docs/TortoiseSVN_en/ch03.html#tsvn-serversetup-apache-5, to see the section on SSPI authentication.

An earlier version of this document left out a line:

   SSPIOfferBasic On

Without this line, a browser will prompt for the user's credentials, but Subversion clients will not. (The browser understands SSPI authentication, but the current release of Neon - Subversion's HTTP library - handles only basic authentication.) Because the client never asks for credentials, any action that requires authentication will fail. Adding this line tells mod_auth_sspi to use basic authentication with the client, but to use the Windows domain controller to authenticate the credentials.

I don't like the ".svn" directory name, and prefer "SVN" or something else. How do I change it?

We recommend that you live with ".svn" if you possibly can. If you use some other name, your working copy may not work with Subversion clients other than the one you regularly use. However, if you absolutely must, you can simply change this line in subversion/include/svn_wc.h from

#define SVN_WC_ADM_DIR_NAME   ".svn"

to

#define SVN_WC_ADM_DIR_NAME   "SVN"

then recompile your client.

I checked in a file but had the wrong case in the filename. How do I change it?

If you're adding files on an operating system with a case-insensitive filesystem, such as Windows, you might find you accidentally add a file with the wrong case in the filename. You can correct this by copying the file somewhere temporary, deleting the file from Subversion, then adding the copy with the correct case, or by performing a move operation with Subversion URLs. Using URLs is recommended, because it will preserve history for the file, and will take effect immediately.

Both fixes will leave Windows working copies with problems, because Windows can still get confused when trying to add the file with the new case. One way of fixing the problem is to delete your working copy and check out again. If this is not possible, you must perform a two step update.

For each file with the wrong the case, do:

svn mv svn://svnserver/path/to/file.java svn://svnserver/path/to/File.java

Then for each working copy, change to the relevant directory and do:

svn update *
svn update
The first update will remove file.java from your working copy, the second update will add File.java, leaving you with a correct working copy.

As you can see, adding a file with the wrong case is tricky to fix on an operating system that has a case insensitive filesystem. Do try to get it right when you add the file the first time!

I can't use tags to merge changes from a branch into the trunk like I used to with CVS, can I?

As shown below it is possible to merge from a branch to the trunk without remembering one revision number. Or vice versa (not shown in the example).

The example below presumes an existing repository in /home/repos in which you want to start a branch named bar containing a file named foo you are going to edit.

For the purpose of tracing branch merges, this repository has set up tags/branch_traces/ to keep tags.

# setup branch and tags
$ svn copy file:///home/repos/trunk \
           file:///home/repos/branches/bar_branch \
           -m "start of bar branch"
$ svn copy file:///home/repos/branches/bar_branch \
           file:///home/repos/tags/branch_traces/bar_last_merge \
           -m "start"

# checkout branch working copy
$ svn checkout file:///home/repos/branches/bar_branch wc
$ cd wc

# edit foo.txt file and commit
$ echo "some text" >>foo.txt
$ svn commit -m "edited foo"

# switch to trunk and merge changes from branch
$ svn switch file:///home/repos/trunk
$ svn merge file:///home/repos/tags/branch_traces/bar_last_merge \
            file:///home/repos/branches/bar_branch

# and check the file content of 'foo.txt'

Why doesn't the $Revision$ keyword do what I want? It expands to the file's last-changed revision, but I want something that will expand to the file's current revision.

Subversion increments the revision number of the repository as a whole, so it can't expand any keyword to be that number - it would have to search and possibly modify every file in your working copy on every update and commit.

The information you want (the revision of your working copy) is available from the command svnversion; it gives you information on the revision level of a working copy given a path (see svnversion --help for details).

You can incorporate it into your build or release process to get the information you need into the source itself. For example, in a build environment based on make, add something like this to your Makefile:


##
## on every build, record the working copy revision string
##
svn_version.c: FORCE
    echo -n 'const char* svn_version(void) { const char* SVN_Version = "' \
                                       > svn_version.c
    svnversion -n .                   >> svn_version.c
    echo '"; return SVN_Version; }'   >> svn_version.c

any executable that links in svn_version.o will be able to call the function svn_version() to get a string that describes exactly what revision was built.

Windows users may want to use SubWCRev.exe, available from the TortoiseSVN download page; it replaces all $WCREV$ tags in a given file with the current working copy revision.


Troubleshooting:

My repository seems to get stuck all the time, giving me errors about needing recovery (DB_RUNRECOVERY). What could be the cause?

The BerkeleyDB database in your repository is susceptible to interruptions. If a process accessing the database exits without "cleanly" closing the environment, then the database is left in an inconsistent state. Common causes of this include:

To make the repository function again, simply run "svnadmin recover". This rewinds the repository back to a consistent state. (See this question for more information.)

The best way to prevent this problem is to get your repository permissions and ownership set up correctly. Segfaults and forced killings are pretty rare; far and away, this problem almost always results from one process accessing the repository and accidentally changing ownership or permissions. Then another process tries to access and chokes on the permissions.

Here are our recommendations:

Every time I try to access my repository, the process just hangs. Is my repository corrupt?

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.

WARNING: you can seriously corrupt your repository if you run recover and another process accesses the repository.

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.

Simply run:

svnadmin recover /path/to/repos

Once the command has completed, check the permissions in the db directory of the repository.

Every time I try to run a svn command, it says my working copy is locked. Is my working copy corrupt?

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 violently (segfault or killed, not with Control-C), 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:

svn cleanup working-copy

I'm trying to commit, but Subversion says my working copy is out of date?

When you commit, Subversion bumps the revision numbers of all nodes the commit touches. This means that in a single folder, the files and folders might be at different revisions, depending on when you last committed them.

For certain operations (deletes and property modifications), if the repository has a more recent version of the node, the commit will be rejected, to prevent data loss.

See The Limitations of Mixed Revisions in the Version Control with Subversion for details.

To prevent this error, simply update your working copy using:

svn update working-copy

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?

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.

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.

I'm getting errors finding or opening a repository, but I know my repository URL is correct. What's wrong?

See this faq.

When I run `configure', I get errors about subs-1.sed line 38: Unterminated `s' command. What's wrong?

You probably have old copies of /usr/local/bin/apr-config and /usr/local/bin/apu-config on your system. Remove them, make sure the apr/ and apr-util/ that you're building with are completely up-to-date, and try again.

I'm having trouble building Subversion under *NIX with BerkeleyDB 4.2.x What should I do?

Subversion compiles against BerkeleyDB by asking apr-util for the appropriate BDB build options. This means that either the apr-util in your Subversion tarball or the one in your Apache tree must successfully detect BDB. Normally one does this by passing "--with-berkeley-db" to apr-util's ./configure. (When you pass this argument to either Apache or Subversion's ./configure, it's really just getting passed down to apr-util's ./configure.)

The problem is that BerkeleyDB 4.2 is newer than the latest released version of apr-util, so apr-util doesn't know how to detect it.

The long-term solution is already in place: the latest apr-util in CVS has code to explicitly detect BDB 4.2. When either apr-util or Apache httpd does another release, this ability will widely available.

In the short term, the best thing to do is apply this patch to your apr-util's ./configure script -- either to the apr-util in your apache tree (if you're building Apache before Subversion), or to the apr-util in your Subversion tarball (if you're not building Apache at all.) This patch is the new DB 4.2 detection code already in the latest apr-util CVS.

If you've building Apache first, apply the patch to httpd-2.0.48's apr-util's configure script, and then build with these options:

  $ configure \
  --enable-dav \
  --enable-so \
  --with-berkeley-db=/usr/local/BerkeleyDB.4.2 \
  --with-dbm=db42

You can confirm that Apache is built with the proper BDB libraries with the following command:

  $ ldd /usr/local/apache2/bin/httpd | fgrep libdb
      libdb-4.2.so => /usr/local/BerkeleyDB.4.2/lib/libdb-4.2.so

And then you can simply build Subversion with no mention of BDB. (...although Subversion might need to be told where to find your Apache installation, if it's in a non-standard place.)

If you're not building Apache, apply the patch to the apr-util ./configure script in your Subversion tree, and use similar build options:

  $ configure \
  --with-berkeley-db=/usr/local/BerkeleyDB.4.2 \
  --with-dbm=db42

Again, you can confirm that Subversion was built against the proper BDB library with the following:

  $ ldd /usr/local/bin/svn | fgrep libdb
      libdb-4.2.so => /usr/local/BerkeleyDB.4.2/lib/libdb-4.2.so

If you install your libraries in locations other than the defaults, you would need to adjust the paths at each step accordingly.

I'm having trouble building Subversion under Windows with MSVC++ 6.0. What should I do?

Probably you just need to get the latest platform SDK. The one that ships with VC++ 6.0 is not recent enough.

How can I specify a Windows drive letter in a file: URL?

Like this:

svn import file:///d:/some/path/to/repos/on/d/drive

See Repository URLs in the Subversion Book for more details.

I'm having trouble doing write operations to a Subversion repository over a network.

For example, one user reported that imports worked fine over local access:

But not from a remote host:

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 dav/ directory (and to db/, of course).

Under Windows XP, the Subversion server sometimes seems to send out corrupted data. Can this really be happening?

You need to install Window XP Service Pack 1. You can get all sorts of information about that Service Pack here:

What is the best method of doing a network trace of the conversation between a Subversion client and server?

Use Ethereal to eavesdrop on the conversation:

  1. Pull down the Capture menu, and choose Start.
  2. Type port 80 for Filter, and turn off promiscuous mode.
  3. Run your Subversion client.
  4. Hit Stop (probably in a little box). Now you have a capture. It looks like a huge list of lines.
  5. Click on the Protocol column to sort.
  6. Then, click on the first relevant TCP line to select it.
  7. Right click, and choose Follow TCP Stream. You'll be presented with the request/response pairs of the Subversion client's HTTP conversion.
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).

Alternatively, if you have an up-to-date client (more recent than the 0.16 tarball) you may set the neon-debug-mask parameter in your servers configuration file to cause neon's debugging output to appear when you run the svn client. The numeric value of neon-debug-mask is a combination of the NE_DBG_... values in the header file ne_utils.h. For neon 0.23.7 setting neon-debug-mask to 130 (i.e. NE_DBG_HTTP+NE_DBG_HTTPBODY) will cause the HTTP data to be shown.

You may well want to disable compression when doing a network trace, see the compression parameter in the config configuration file.

Why does the svn revert require an explicit target? Why is it not recursive by default? These behaviors differ from almost all the other subcommands.

The short answer: it's for your own good.

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.

Making the svn revert command require an explicit target—even if that target is just '.'—is one way of accomplishing that. This requirement (as well as requiring you to supply the --recursive (-R) 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.

When I start Apache, mod_dav_svn complains about a "bad database version", that it found db-3.X, rather than db-4.X.

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.

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

I'm getting "Function not implemented" errors on RedHat 9, and nothing works. How do I fix this?

This is not really a problem with Subversion, but it often affects Subversion users.

RedHat 9 and Fedora ship with a Berkeley DB library that relies on the kernel support for NPTL (the Native Posix Threads Library).

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:

svn: Berkeley DB error
svn: Berkeley DB error while creating environment for filesystem tester/db:
Function not implemented
This can be fixed in one of several ways:

To use the NPTL version of Berkeley DB you also need to use a glibc library with NPTL support, which probably means the i686 version. See http://www.contactor.se/~dast/svnusers/archive-2004-03/0488.shtml for details.

Why does SVN log say "(no author)" for files committed or imported via Apache (ra_dav)?

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:

$ svn log
------------------------------------------------------------------------
rev 24:  (no author) | 2003-07-29 19:28:35 +0200 (Tue, 29 Jul 2003)

See the Subversion Book ("Networking a Repository") to learn about configuring access restrictions in Apache.

I'm getting occasional "Access Denied" errors on Windows. They seem to happen at random. Why?

These appear to be due to the various Windows services that monitor the filesystem for changes (anti-virus software, indexing services, the COM+ Event Notification Service). This is not really a bug in Subversion, which makes it difficult for us to fix. A summary of the current state of the investigation is available here. A workaround that should reduce the incidence rate for most people was implemented in revision 7598; if you have an earlier version, please update to the latest release.

On FreeBSD, certain operations (especially svnadmin create) sometimes hang. Why?

This is usually due to a lack of available entropy on the system. You probably need to configure the system to gather entropy from sources such as hard-disk and network interrupts. Consult your system manpages, specifically random(4) and rndcontrol(8) on how to effect this change.

I can see my repository in a web browser, but 'svn checkout' gives me an error about "301 Moved Permanently". What's wrong?

It means your httpd.conf is misconfigured. Usually this error happens when you've defined the Subversion virtual "location" to exist within two different scopes at the same time.

For example, if you've exported a repository as <Location /www/foo>, but you've also set your DocumentRoot to be /www, then you're in trouble. When the request comes in for /www/foo/bar, apache doesn't know whether to find a real file named /foo/bar within your DocumentRoot, or whether to ask mod_dav_svn to fetch a file /bar from the /www/foo repository. Usually the former case wins, and hence the "Moved Permanently" error.

The solution is to make sure your repository <Location> does not overlap or live within any areas already exported as normal web shares.

I'm trying to look at an old version of my file, but svn says something about "path not found". What's going on?

A nice feature of Subversion is that the repository understands copies and renames, and preserves the historical connections. For example, if you copy /trunk to /branches/mybranch, then the repository understands that every file in the branch has a "predecessor" in the trunk. Running svn log --verbose will show you the historical copy, so you can see the rename:

r7932 | joe | 2003-12-03 17:54:02 -0600 (Wed, 03 Dec 2003) | 1 line
Changed paths:
   A /branches/mybranch (from /trunk:7931)

Unfortunately, while the repository is aware of copies and renames, almost all the svn client subcommands are not aware. Commands like svn diff, svn merge, and svn cat ought to understand and follow renames, but don't yet do this. It's scheduled as post-1.0 feature, currently issue #1093. For example, if you ask svn diff to compare two earlier versions of /branches/mybranch/foo.c, the command will not automatically understand that the task actually requires comparing two versions of /trunk/foo.c, due to the rename. Instead, you'll see an error about how the branch-path doesn't exist in the earlier revisions.

The workaround for all problems of this sort is to do the legwork yourself. That is: you need to be aware of any renamed paths, discover them yourself using svn log -v, and then provide them explicitly to the svn client. For example, instead of running

$ svn diff -r 1000:2000 http://host/repos/branches/mybranch/foo.c
svn: Filesystem has no item
svn: '/branches/mybranch/fooc..c' not found in the repository at revision 1000
...you would instead run
$ svn diff -r1000:2000 http://host/repos/trunk/foo.c
...

Why doesn't HTTP Digest auth work?

This is probably due to a known bug in Apache HTTP Server (versions 2.0.48 and earlier), for which a patch is available, see http://nagoya.apache.org/bugzilla/show_bug.cgi?id=25040. You may also want to read over http://subversion.tigris.org/issues/show_bug.cgi?id=1608 to see if the description there matches your symptoms.

Compiling with xlc on AIX, I get compilation errors. What's wrong?

Adding -qlanglvl=extended to the environment variable CFLAGS for configuration and build will make xlc a bit more flexible and the code should compile without error. See http://www.contactor.se/~dast/svn/archive-2004-01/0922.shtml and its associated thread for more details.

I checked out a directory non-recursively (with -N), and now I want to make certain subdirectories "appear". But svn up subdir doesn't work.

See issue 695. The current implementation of svn checkout -N is quite broken. It results in a working copy which has missing entries, yet is ignorant of its "incompleteness". Apparently a whole bunch of CVS users are fairly dependent on this paradigm, but none of the Subversion developers were. For now, there's really no workaround other than to change your process: try checking out separate subdirectories of the repository and manually nesting your working copies.

I am trying to use mod_dav_svn with Apache on Win32 and I'm getting an error saying that the module cannot be found, yet the mod_dav_svn.so file is right there in \Apache\modules.

The error message in this case is a little misleading. Most likely Apache is unable to load one or more DLLs that mod_dav_svn.so relies on. If Apache is running as a service it will not have the same PATH as a regular user. Make sure that libdb4*.dll, libeay32.dll and ssleay32.dll are present in either \Apache\bin or \Apache\modules. You can copy them from your Subversion installation directory if they are not there.

If this still does not resolve the problem, you should use a tool like Dependency Walker on mod_dav_svn.so to see if there are any other unresolved dependencies.


Developer questions:

How do I run the regression tests in a ram disk?

See http://www.contactor.se/~dast/svn/archive-2003-02/0068.shtml.


References:

What are all the HTTP methods Subversion uses?

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:

From: Nuutti Kotivuori <naked@iki.fi>
Subject: Re: list of HTTP messages used by svn?
To: "Hamilton Link" <helink@sandia.gov>
Cc: dev@subversion.tigris.org
Date: Sat, 10 Aug 2002 13:51:52 +0300

Hamilton Link wrote:
> Is there a full list of the HTTP methods svn uses somewhere, that
> someone could piont me to? From the documentation I can find (in
> particular project_faq.html and INSTALL), the list of methods svn
> uses include at least the following:
>
> GET, PROPFIND, REPORT, OPTIONS, MERGE, MKACTIVITY, and CHECKOUT
>
> But since the lists I can find are only partial lists and nowhere
> does it suggest these are all the ones used, I'm reluctant to make
> any assumptions.
>
> If I had a complete list, I could go to the corp. proxy guy once
> instead of many times, and reduce the risk of pissing him off and
> being left with inadequate svn support in the proxy.

http://www.webdav.org/deltav/WWW10/deltav-intro.htm

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.

What's a 'bikeshed'?

See Poul-Henning Kamp's post to freebsd-hackers: http://www.freebsd.org/doc/en_US.ISO8859-1/books/faq/misc.html#BIKESHED-PAINTING.

What's a 'baton'?

Throughout subversion's source code there are many references to 'baton' objects. These are just

void *
datastructures that provide context to a function. In other APIs, they're often called
void *ctx
or
void *userdata
Subversion developers call the structures "batons" because they're passed around quite a bit.