Version Control with Subversion

Initial Checkout

Most of the time, you will start using a Subversion repository by doing a checkout of your project. Checking out a repository creates a copy of it on your local machine. This copy contains the HEAD (latest revision) of the Subversion repository that you specify on the command line:

$ svn checkout https://svn.collab.net/repos/svn/trunk
A  trunk/subversion.dsw
A  trunk/svn_check.dsp
A  trunk/COMMITTERS
A  trunk/configure.in
A  trunk/IDEAS
…
Checked out revision 2499.

What's in a Name?

Subversion tries hard not to limit the type of data you can place under version control. The contents of files and property values are stored and transmitted as binary data, and the the section called “svn:mime-type” tells you how to give Subversion a hint that “textual” operations don't make sense for a particular file. There are a few places, however, where Subversion places restrictions on information it stores.

Subversion handles text internally as UTF-8 encoded Unicode. As a result, certain items which are inherently “textual”, such as property names, path names, and log messages, can only contain legal UTF-8 characters. It also provides a minimum requirement for use of the svn:mime-type property—if a file's contents aren't compatible with UTF-8, you should mark it as a binary file. Otherwise, Subversion will attempt to merge differences using UTF-8, which is likely to leave garbage in the file.

In addition, path names are used as XML attribute values in WebDAV exchanges, as well in as some of Subversion's housekeeping files. This means that path names can only contain legal XML (1.0) characters. Subversion also prohibits TAB, CR, and LF characters in path names, so they aren't broken up in diffs, or in the output of commands like svn log or svn status.

While it may seem like a lot to remember, in practice these limitations are rarely a problem. As long as your locale settings are compatible with UTF-8, and you don't use control characters in path names, you should have no trouble communicating with Subversion. The command-line client adds an extra bit of help—it will automatically escape legal path characters as needed in URLs you type to create “legally correct” versions for internal use.

Experienced users of Subversion have also developed a set of best-practice conventions for laying out paths in the repository. While these aren't strict requirements like the syntax described above, they help to organize frequently performed tasks. The /trunk part of URLs you'll find throughout this book is one of these conventions; we'll talk a lot more about it and related recommendations in Chapter 4, Branching and Merging .

Although the above example checks out the trunk directory, you can just as easily check out any deep subdirectory of a repository by specifying the subdirectory in the checkout URL:

$ svn checkout https://svn.collab.net/repos/svn/trunk/doc/book/tools
A  tools/readme-dblite.html
A  tools/fo-stylesheet.xsl
A  tools/svnbook.el
A  tools/dtd
A  tools/dtd/dblite.dtd
…
Checked out revision 2499.

Since Subversion uses a “copy-modify-merge” model instead of “lock-modify-unlock” (see Chapter 2, Basic Concepts ), you're already able to start making changes to the files and directories in your working copy. Your working copy is just like any other collection of files and directories on your system. You can edit and change them, move them around, you can even delete the entire working copy and forget about it.

Note

While your working copy is “just like any other collection of files and directories on your system”, you need to let Subversion know if you're going to be rearranging anything inside of your working copy. If you want to copy or move an item in a working copy, you should use svn copy or svn move instead of the copy and move commands provided by your operating system. We'll talk more about them later in this chapter.

Unless you're ready to commit a new file or directory, or changes to existing ones, there's no need to further notify the Subversion server that you've done anything.

While you can certainly check out a working copy with the URL of the repository as the only argument, you can also specify a directory after your repository URL. This places your working copy in the new directory that you name. For example:

$ svn checkout https://svn.collab.net/repos/svn/trunk subv
A  subv/subversion.dsw
A  subv/svn_check.dsp
A  subv/COMMITTERS
A  subv/configure.in
A  subv/IDEAS
…
Checked out revision 2499.

That will place your working copy in a directory named subv instead of a directory named trunk as we did previously.