# Subversion for CVS Users

This appendix is a guide for CVS users new to Subversion. It's essentially a list of differences between the two systems as viewed from 10,000 feet. For each section, we provide backreferences to relevant chapters when possible.

Although the goal of Subversion is to take over the current and future CVS user base, some new features and design changes were required to fix certain broken behaviors that CVS had. This means that, as a CVS user, you may need to break habits—ones that you forgot were odd to begin with.

## Revision Numbers Are Different Now

In CVS, revision numbers are per-file. This is because CVS uses RCS as a backend; each file has a corresponding RCS file in the repository, and the repository is roughly laid out according to the structure of your project tree.

In Subversion, the repository looks like a single filesystem. Each commit results in an entirely new filesystem tree; in essence, the repository is an array of trees. Each of these trees is labeled with a single revision number. When someone talks about revision 54, they're talking about a particular tree (and indirectly, the way the filesystem looked after the 54th commit).

Technically, it's not valid to talk about revision 5 of `foo.c`. Instead, one would say `foo.c` as it appears in revision 5. Also, be careful when making assumptions about the evolution of a file. In CVS, revisions 5 and 6 of `foo.c` are always different. In Subversion, it's most likely that `foo.c` did not change between revisions 5 and 6.

For more details on this topic, see .

## Directory Versions

Subversion tracks tree structures, not just file contents. It's one of the biggest reasons Subversion was written to replace CVS.

Here's what this means to you, as a former CVS user:

- The `svn add` and `svn delete` commands work on directories now, just as they work on files. So do `svn copy` and `svn move`. However, these commands do not cause any kind of immediate change in the repository. Instead, the working items are simply scheduled for addition or deletion. No repository changes happen until you run `svn commit`.

- Directories aren't dumb containers anymore; they have revision numbers like files. (Or more properly, it's correct to talk about directory `foo/` in revision 5.)

Let's talk more about that last point. Directory versioning is a hard problem; because we want to allow mixed-revision working copies, there are some limitations on how far we can abuse this model.

From a theoretical point of view, we define revision 5 of directory `foo` to mean a specific collection of directory-entries and properties. Now suppose we start adding and removing files from `foo`, and then commit. It would be a lie to say that we still have revision 5 of `foo`. However, if we bumped `foo`'s revision number after the commit, that would be a lie too; there may be other changes to `foo` we haven't yet received, because we haven't updated yet.

Subversion deals with this problem by quietly tracking committed adds and deletes in the `.svn` area. When you eventually run `svn update`, all accounts are settled with the repository, and the directory's new revision number is set correctly. Therefore, only after an update is it truly safe to say that you have a perfect revision of a directory. Most of the time, your working copy will contain imperfect directory revisions.

Similarly, a problem arises if you attempt to commit property changes on a directory. Normally, the commit would bump the working directory's local revision number. But again, that would be a lie, because there may be adds or deletes that the directory doesn't yet have, because no update has happened. Therefore, you are not allowed to commit property-changes on a directory unless the directory is up-to-date.

For more discussion about the limitations of directory versioning, see .

## More Disconnected Operations

In recent years, disk space has become outrageously cheap and abundant, but network bandwidth has not. Therefore, the Subversion working copy has been optimized around the scarcer resource.

The `.svn` administrative directory serves the same purpose as the `CVS` directory, except that it also stores read-only, pristine copies of your files. This allows you to do many things off-line:

`svn status`

  Shows you any local changes you've made (see )

`svn diff`

  Shows you the details of your changes (see )

`svn revert`

  Removes your local changes (see )

Also, the cached pristine files allow the Subversion client to send differences when committing, which CVS cannot do.

The last subcommand in the list is new; it will not only remove local mods, but it will un-schedule operations such as adds and deletes. It's the preferred way to revert a file; running `rm file; svn update` will still work, but it blurs the purpose of updating. And, while we're on this subject…

## Distinction Between Status and Update

In Subversion, we've tried to erase a lot of the confusion between the `cvs status` and `cvs update` commands.

The `cvs status` command has two purposes: first, to show the user any local modifications in the working copy, and second, to show the user which files are out-of-date. Unfortunately, because of CVS's hard-to-read status output, many CVS users don't take advantage of this command at all. Instead, they've developed a habit of running `cvs update` or `cvs update -n` to quickly see their mods. If users forget to use the `-n` option, this has the side effect of merging repository changes they may not be ready to deal with.

With Subversion, we've tried to remove this muddle by making the output of `svn status` easy to read for both humans and parsers. Also, `svn update` only prints information about files that are updated, not local modifications.

`svn status` prints all files that have local modifications. By default, the repository is not contacted. While this subcommand accepts a fair number of options, the following are the most commonly used ones:

`-u`

  Contact the repository to determine, and then display, out-of-dateness information.

`-v`

  Show all entries under version control.

`-N`

  Run non-recursively (do not descend into subdirectories).

The `status` command has two output formats. In the default short format, local modifications look like this:

    % svn status
    M     ./foo.c
    M     ./bar/baz.c

If you specify the `--show-updates` (`-u`) switch, a longer output format is used:

    % svn status -u
    M             1047    ./foo.c
           *      1045    ./faces.html
           *         -    ./bloo.png
    M             1050    ./bar/baz.c
    Status against revision:   1066

In this case, two new columns appear. The second column contains an asterisk if the file or directory is out-of-date. The third column shows the working-copy's revision number of the item. In the example above, the asterisk indicates that `faces.html` would be patched if we updated, and that `bloo.png` is a newly added file in the repository. (The `-` next to `bloo.png` means that it doesn't yet exist in the working copy.)

Lastly, here's a quick summary of the most common status codes that you may see:

    A    Resource is scheduled for Addition
    D    Resource is scheduled for Deletion
    M    Resource has local modifications
    C    Resource has conflicts (changes have not been completely merged
           between the repository and working copy version)
    X    Resource is external to this working copy (comes from another
           repository.  See )
    ?    Resource is not under version control
    !    Resource is missing or incomplete (removed by another tool than
           Subversion)

Subversion has combined the CVS `P` and `U` codes into just `U`. When a merge or conflict occurs, Subversion simply prints `G` or `C`, rather than a whole sentence about it.

For a more detailed discussion of `svn status`, see .

## Branches and Tags

Subversion doesn't distinguish between filesystem space and branch space; branches and tags are ordinary directories within the filesystem. This is probably the single biggest mental hurdle a CVS user will need to climb. Read all about it in .

Since Subversion treats branches and tags as ordinary directories, always remember to check out the `trunk` (`http://svn.example.com/repos/calc/trunk/`) of your project, and not the project itself (`http://svn.example.com/repos/calc/`). If you make the mistake of checking out the project itself, you'll wind up with a working copy that contains a copy of your project for every branch and tag you have. That is, providing you don't run out of disk space before your checkout finishes.

## Metadata Properties

A new feature of Subversion is that you can attach arbitrary metadata (or properties) to files and directories. Properties are arbitrary name/value pairs associated with files and directories in your working copy.

To set or get a property name, use the `svn propset` and `svn propget` subcommands. To list all properties on an object, use `svn proplist`.

For more information, see .

## Conflict Resolution

CVS marks conflicts with in-line conflict markers, and prints a `C` during an update. Historically, this has caused problems, because CVS isn't doing enough. Many users forget about (or don't see) the `C` after it whizzes by on their terminal. They often forget that the conflict-markers are even present, and then accidentally commit files containing conflict-markers.

Subversion solves this problem by making conflicts more tangible. It remembers that a file is in a state of conflict, and won't allow you to commit your changes until you run `svn resolved`. See for more details.

## Binary Files and Translation

In the most general sense, Subversion handles binary files more gracefully than CVS does. Because CVS uses RCS, it can only store successive full copies of a changing binary file. But internally, Subversion expresses differences between files using a binary-differencing algorithm, regardless of whether they contain textual or binary data. That means that all files are stored differentially (compressed) in the repository, and small differences are always sent over the network.

CVS users have to mark binary files with `-kb` flags, to prevent data from being garbled (due to keyword expansion and line-ending translations). They sometimes forget to do this.

Subversion takes the more paranoid route: first, it never performs any kind of keyword or line-ending translation unless you explicitly ask it do so (see and for more details). By default, Subversion treats all file data as literal byte strings, and files are always stored in the repository in an untranslated state.

Second, Subversion maintains an internal notion of whether a file is text or binary data, but this notion is only extant in the working copy. During an `svn update`, Subversion will perform contextual merges on locally modified text files, but will not attempt to do so for binary files.

To determine whether a contextual merge is possible, Subversion examines the `svn:mime-type` property. If the file has no `svn:mime-type` property, or has a mime-type that is textual (e.g. `text/*`), Subversion assumes it is text. Otherwise, Subversion assumes the file is binary. Subversion also helps users by running a binary-detection algorithm in the `svn import` and `svn add` commands. These commands will make a good guess and then (possibly) set a binary `svn:mime-type` property on the file being added. (If Subversion guesses wrong, the user can always remove or hand-edit the property.)

## Versioned Modules

Unlike CVS, a Subversion working copy is aware that it has checked out a module. That means that if somebody changes the definition of a module (e.g. adds or removes components), then a call to `svn update` will update the working copy appropriately, adding and removing components.

Subversion defines modules as a list of directories within a directory property: see .

## Authentication

With CVS's pserver, you are required to login to the server before any read or write operation—you even have to login for anonymous operations. With a Subversion repository using Apache `httpd` or `svnserve` as the server, you don't provide any authentication credentials at the outset—if an operation that you perform requires authentication, the server will challenge you for your credentials (whether those credentials are username and password, a client certificate, or even both). So if your repository is world-readable, you will not be required to authenticate at all for read operations.

As with CVS, Subversion still caches your credentials on disk (in your `~/.subversion/auth/` directory) unless you tell it not to by using the `--no-auth-cache` switch.

The exception to this behaviors, however, is in the case of accessing an `svnserve` server over an ssh tunnel, using the `svn+ssh://` URL schema. In that case, the `ssh` program unconditionally demands authentication just to start the tunnel.

## Converting a Repository from CVS to Subversion

Perhaps the most important way to familiarize CVS users with Subversion is to let them continue to work on their projects using the new system. And while that can be somewhat accomplished using a flat import into a Subversion repository of an exported CVS repository, the more thorough solution involves transferring not just the latest snapshot of their data, but all the history behind it as well, from one system to another. This is an extremely difficult problem to solve that involves deducing changesets in the absence of atomicity, and translating between the systems' completely orthogonal branching policies, among other complications. Still, there are a handful of tools claiming to at least partially support the ability to convert existing CVS repositories into Subversion ones.

One such tool is cvs2svn (http://cvs2svn.tigris.org/), a Python script originally created by members of Subversion's own development community. Others include Chia-liang Kao's Subversion converter plugin to the VCP tool (http://svn.clkao.org/revml/branches/svn-perl/) and Lev Serebryakov's RefineCVS (http://lev.serebryakov.spb.ru/refinecvs/). These tools have various levels of completeness, and may make entirely different decisions about how to handle your CVS repository history. Whichever tool you decide to use, be sure to perform as much verification as you can stand on the conversion results—after all, you've worked hard to build that history!

For an updated collection of links to known converter tools, visit the Links page of the Subversion website (http://subversion.tigris.org/project_links.html).