Quick Start Guide - Version Control with Subversionby Ben Collins-Sussman, Brian W. Fitzpatrick, C. Michael Pilato
If you’re eager to get Subversion up and running (and you enjoy learning by experimentation), this appendix will show you how to create a repository, import code, and then check it back out again as a working copy. Along the way, we give links to the relevant chapters of this book.
This excerpt is from Version Control with Subversion. Written by members of the development that maintains Subversion, this is the official guide and reference manual for the popular open source revision control technology. The new edition covers Subversion 1.5 and includes an introduction to Subversion, a guided tour of the capabilities and structure, detailed coverage of advanced topics, such as branching and repository administration, and best practice recommendations.
If you’re new to the entire concept of version control or to the “copy-modify-merge” model used by both CVS and Subversion, you should read Chapter 1, Fundamental Concepts before going any further.
Subversion is built on a portability layer called APR: the Apache Portable Runtime library. The APR library provides all the interfaces that Subversion needs to function on different operating systems: disk access, network access, memory management, and so on. While Subversion is able to use Apache as one of its network server programs, its dependence on APR does not mean that Apache is a required component. APR is a standalone library usable by any application. It does mean, however, that like Apache, Subversion clients and servers run on any operating system that the Apache httpd server runs on: Windows, Linux, all flavors of BSD, Mac OS X, NetWare, and others.
The easiest way to get Subversion is to download a binary package built for your operating system. Subversion’s web site (http://subversion.tigris.org) often has these packages available for download, posted by volunteers. The site usually contains graphical installer packages for users of Microsoft operating systems. If you run a Unix-like operating system, you can use your system’s native package distribution system (RPMs, DEBs, the ports tree, etc.) to get Subversion.
Alternatively, you can build Subversion directly from source code, though it’s not always an easy task. (If
you’re not experienced at building open source software packages, you’re
probably better off downloading a binary distribution instead!) From the
Subversion web site, download the latest source code release. After
unpacking it, follow the instructions in the
INSTALL file to build
it. Note that a released source package may not contain everything you
need to build a command-line client capable of talking to a remote
repository. Starting with Subversion 1.4 and later, the libraries
Subversion depends on (apr, apr-util, and neon) are distributed in a
separate source package suffixed with
-deps. These libraries are now common enough
that they may already be installed on your system. If not, you’ll need to
unpack the dependency package into the same directory where you unpacked
the main Subversion source. Regardless, it’s possible that you may want to
fetch other optional dependencies, such as Berkeley DB and possibly Apache
httpd. If you want to do a complete
build, make sure you have all of the packages documented in the
If you’re one of those folks who likes to use bleeding-edge software, you can also get the Subversion source code from the Subversion repository in which it lives. Obviously, you’ll need to already have a Subversion client on hand to do this. But once you do, you can check out a working copy of the Subversion source repository from http://svn.collab.net/repos/svn/trunk/:
$ svn checkout http://svn.collab.net/repos/svn/trunk subversion A subversion/HACKING A subversion/INSTALL A subversion/README A subversion/autogen.sh A subversion/build.conf ...
The preceding command will create a working copy of the latest
(unreleased) Subversion source code into a subdirectory named
subversion in your current working directory.
You can adjust that last argument as you see fit. Regardless of what you
call the new working copy directory, though, after this operation
completes, you will now have the Subversion source code. Of course, you
will still need to fetch a few helper libraries (apr, apr-util, etc.)—see
INSTALL file in the top level of
the working copy for details.
“Please make sure your seat backs are in their full, upright position and that your tray tables are stored. Flight attendants, prepare for take-off….”
What follows is a quick tutorial that walks you through some basic Subversion configuration and operation. When you finish it, you should have a general understanding of Subversion’s typical usage.
The examples used in this appendix assume that you have svn, the Subversion command-line client, and
svnadmin, the administrative tool,
ready to go on a Unix-like operating system. (This tutorial also works
at the Windows command-line prompt, assuming you make some obvious
tweaks.) We also assume you are using Subversion 1.2 or later (run
svn --version to check).
Subversion stores all versioned data in a central repository. To begin, create a new repository:
$ svnadmin create /var/svn/repos $ ls /var/svn/repos conf/ dav/ db/ format hooks/ locks/ README.txt
This command creates a new directory,
/var/svn/repos, which contains a Subversion
repository. This new directory contains (among other things) a collection
of database files. You won’t see your versioned files if you peek inside.
For more information about repository creation and maintenance, see Chapter 5, Repository Administration.
Subversion has no concept of a “project.” The repository is just a virtual versioned filesystem, a large tree that can hold anything you wish. Some administrators prefer to store only one project in a repository, and others prefer to store multiple projects in a repository by placing them into separate directories. We discuss the merits of each approach in the section called “Planning Your Repository Organization”. Either way, the repository manages only files and directories, so it’s up to humans to interpret particular directories as “projects.” So, while you might see references to projects throughout this book, keep in mind that we’re only ever talking about some directory (or collection of directories) in the repository.
In this example, we assume you already have some sort of project (a
collection of files and directories) that you wish to import into your
newly created Subversion repository. Begin by organizing your data into a
single directory called
whatever you wish). For reasons explained in Chapter 4, Branching and Merging, your project’s tree structure should contain
three top-level directories named
trunk directory should contain all of your
data, and the
tags directories should be empty:
/tmp/myproject/branches/ /tmp/myproject/tags/ /tmp/myproject/trunk/ foo.c bar.c Makefile ...
trunk subdirectories aren’t actually required
by Subversion. They’re merely a popular convention that you’ll most likely
want to use later on.
Once you have your tree of data ready to go, import it into the repository with the svn import command (see the section called “Getting Data into Your Repository”):
$ svn import /tmp/myproject file:///var/svn/repos/myproject -m "initial import" Adding /tmp/myproject/branches Adding /tmp/myproject/tags Adding /tmp/myproject/trunk Adding /tmp/myproject/trunk/foo.c Adding /tmp/myproject/trunk/bar.c Adding /tmp/myproject/trunk/Makefile ... Committed revision 1. $
Now the repository contains this tree of data. As mentioned earlier,
you won’t see your files by directly peeking into the repository; they’re
all stored within a database. But the repository’s imaginary filesystem
now contains a top-level directory named
myproject, which in turn contains your
Note that the original
/tmp/myproject directory is unchanged;
Subversion is unaware of it. (In fact, you can even delete that directory
if you wish.) To start manipulating repository data, you need to create a
new “working copy” of the data, a sort of private workspace.
Ask Subversion to “check out” a working copy of the
myproject/trunk directory in the repository:
$ svn checkout file:///var/svn/repos/myproject/trunk myproject A myproject/foo.c A myproject/bar.c A myproject/Makefile ... Checked out revision 1.
Now you have a personal copy of part of the repository in a new
myproject. You can
edit the files in your working copy and then commit those changes back
into the repository:
Enter your working copy and edit a file’s contents.
Run svn diff to see unified diff output of your changes.
Run svn commit to commit the new version of your file to the repository.
Run svn update to bring your working copy “up to date” with the repository.
For a full tour of all the things you can do with your working copy, read Chapter 2, Basic Usage.
At this point, you have the option of making your repository available to others over a network. See Chapter 6, Server Configuration to learn about the different sorts of server processes available and how to configure them.
 Note that the URL checked out in the example ends not with
svn, but with a subdirectory
trunk. See our
discussion of Subversion’s branching and tagging model for the
reasoning behind this.
If you enjoyed this excerpt, buy a copy of Version Control with Subversion.