A Crash Course in Subversion

Basic Workflow

Now that you have data in your Subversion repository, it's time to do something with it. The first step is to check out a working copy. A Subversion working copy is an ordinary directory in your filesystem. It contains any number of files and sub-directories, some of which correspond to files and directories in your Subversion repository. In addition to your files and directories, each working copy directory contains a special subdirectory named .svn/. This is known as an administrative directory, and Subversion uses it to store some bookkeeping information about the files and directories in your working copy. Note that the administrative directory's contents are under Subversion's control, and you shouldn't edit them in any way. If you do change them manually, you're likely to render your working copy unusable.

Once you have a working copy, you can edit the files, make changes to the files, and eventually commit those changes back to the repository so others can see them. In the process of making your changes, you can ask Subversion to tell you about the status of your changes, view the difference between your current version and the version you checked out (or any other revision, for that matter), or update your working copy to take into account other users' changes. These actions comprise the majority of the Subversion workflow, so let's examine exactly how they work.

To check out a working copy you use the command svn checkout. There's only one required argument: a URL that indicates what directory in the repository you're checking out. Other than that, the most interesting options are an optional path, which specifies the name of the directory you want to check out into, with the default being the name of the directory in the repository, and the -r or --revision argument, which allows you to indicate what revision you want to check out. If you don't indicate what revision you want, the HEAD revision of the repository will be used. Let's take a look at an example of checking out the most recent version of a directory in the repository and inspecting the resulting working copy.

$svn checkout file:///path/to/repository/trunk myproject
A foo.c
A bar.c
A main.c
Checked out revision 2.
$ls myproject/
foo.c bar.c main.c
$cd myproject
$svn status
$svn status -v
               2       2       rooneg    .
               2       2       rooneg    bar.c
               2       2       rooneg    foo.c
               2       2       rooneg    main.c
$svn info
Path:.
URL:file:///path/to/repository
Repository UUID:18dffd47-64c3-0310-bd18-cbeae88b449f
Revision:2
Node Kind:directory
Schedule:normal
Last Changed Author:rooneg
Last Changed Rev:2
Last Changed Date:2003-07-26 19:03:29 -0400 (Sat,26 Jul 2003)
$svn info main.c
Path:main.c
Name:main.c
URL:file:///path/to/repos/trunk/main.c
Repository UUID:18dffd47-64c3-0310-bd18-cbeae88b449f
Revision:2
Node Kind:file
Schedule:normal
Last Changed Author:rooneg
Last Changed Rev:2
Last Changed Date:2003-07-26 19:03:29 -0400 (Sat, 26 Jul 2003)
Text Last Updated:2003-07-26 19:03:37 -0400 (Sat, 26 Jul 2003)
Properties Last Updated:2003-07-26 19:03:37 -0400 (Sat, 26 Jul 2003)
Checksum:0c1ea17162fcd46023bf6712a35dba03
$

In addition to svn checkout, you've seen two other new commands, svn status and svn info, so let's take a look at them before moving on. svn status is the command you'll probably run most often while using Subversion. It prints out the current status of your working copy.

Note: In Perforce, the closest analogous command to svn status is p4 opened, but svn status shows a lot more information because a Subversion working copy is considerably more complex (at least from the client's perspective) than a Perforce client. In CVS, there really isn't a useful status command, so most people just end up running either cvs diff or cvs update to determine what local changes they've made. The first case isn't all that bad, although cvs diff produces quite a bit more information than just the status of the working copy. The second case is particularly bad because the act of updating your working copy and the act of determining what you've changed are two completely different things. When Subversion's command-line client was designed, great care was taken to make the output of svn status useful and easy to understand, so that you aren't tempted to resort to running other commands to discover information you should be getting from svn status.

When you run just svn status, with no arguments, it will tell you only about files and directories in your working copy that you've modified. In this case when you ran it the first time, there was no output because you hadn't yet modified any of the files in the working copy. Later on, you'll see some examples of the output from svn status when the working copy has some modifications. When you add the -v flag, svn status runs in verbose mode, and you can see some more information. The first eight columns of data are blank because you haven't modified any of the files, but the next ones are the current working copy revision (i.e., WORKING), followed by the revision the file last changed in (i.e., COMMITTED) and the author of the previous commit. Everything after the author is the path to the file.

svn info, as you might expect, enables you to find information about items in your working copy. For CVS users, svn info is somewhat similar to the cvs status command. Some of the more useful bits of information here that aren't available elsewhere are the URL of the item in the repository, the universally unique identifier (UUID) of the repository the item came from, the MD5 checksum of the file's contents, and the dates on which the file's text and properties were last modified. svn info isn't used especially often, but at times you'll need information about a working copy that you can't obtain in any other way, so keep it in mind.

In this example, you can see that svn info tells you that, among other things, main.c has a URL of file:///path/to/repos/trunk/main.c; it comes from a repository with a UUID of 18dffd47-64c3-0310-bd18-cbeae88b449f; it's at revision 2; it was last changed by user rooneg on Saturday July 26, 2003; and it has an MD5 checksum of 0c1ea17162fcd46023bf6712a35dba03.

Now that you have a working copy checked out, it's time to start making changes to it. Suppose you've made some changes to some files, and you want to see what you've done. Subversion provides two commands for that purpose. First, there's svn status, which you've already seen. Second, once you know that your working copy has actually been modified, you can run svn diff to see exactly what has been changed. Let's take a look at how these commands work.

$svn status
M bar.c
$svn status -v
               2      2      rooneg    .
               2      2      rooneg    bar.c
M              2      2      rooneg    foo.c
               2      2      rooneg    main.c
$svn diff
Index:bar.c
===================================================================
---bar.c       (revision 2)
+++bar.c       (working copy)
@@-1, 5 +1, 5 @@
void
bar (int a, int b)
{
-printf ("b =%d, a =%d \n", a, b);
+printf ("b =%d, a =%d \n", b, a);
}
$

svn status shows that bar.c has had its text modified because the first column in the output is an M, and svn diff shows that you changed a single new line in the file.

Page 4 of 5