2.3 Subversion in Action

It's time to move from the abstract to the concrete. In this section, we'll show real examples of Subversion being used.

2.3.1 Working Copies

You've already read about working copies; now we'll demonstrate how the Subversion client creates and uses them.

A Subversion working copy is an ordinary directory tree on your local system, containing a collection of files. You can edit these files however you wish, and if they're source code files, you can compile your program from them in the usual way. Your working copy is your own private work area: Subversion will never incorporate other people's changes, nor make your own changes available to others, until you explicitly tell it to do so.

After you've made some changes to the files in your working copy and verified that they work properly, Subversion provides you with commands to publish your changes to the other people working with you on your project (by writing to the repository). If other people publish their own changes, Subversion provides you with commands to merge those changes into your working directory (by reading from the repository).

A working copy also contains some extra files, created and maintained by Subversion, to help it carry out these commands. In particular, each directory in your working copy contains a subdirectory named .svn, also known as the working copy administrative directory. The files in each administrative directory help Subversion recognize which files contain unpublished changes, and which files are out-of-date with respect to others' work.

A typical Subversion repository often holds the files (or source code) for several projects; usually, each project is a subdirectory in the repository's filesystem tree. In this arrangement, a user's working copy will usually correspond to a particular subtree of the repository.

For example, suppose you have a repository that contains two software projects, paint and calc. Each project lives in its own top-level directory, as shown in Figure 2-6.

Figure 2-6. The repository's filesystem

To get a working copy, you must check out some subtree of the repository. (The term check out may sound like it has something to do with locking or reserving resources, but it doesn't; it simply creates a private copy of the project for you.) For example, if you check out /calc, you will get a working copy like this:

$ svn checkout http://svn.example.com/repos/calc A  calc A  calc/Makefile A  calc/integer.c A  calc/button.c $ ls -a calc Makefile  integer.c  button.c  .svn/

The list of letter A's indicates that Subversion is adding a number of items to your working copy. You now have a personal copy of the repository's /calc directory, with one additional entry .svn that holds the extra information needed by Subversion, as mentioned earlier.

Repository URLs

Subversion repositories can be accessed through many different methods on local disk, or through various network protocols. A repository location, however, is always a URL. Table 2-1 describes how different URL schemas map to the available access methods.

For the most part, Subversion's URLs use the standard syntax, allowing for server names and port numbers to be specified as part of the URL. Remember that the file: access method is valid only for locations on the same server as the client in fact, in accordance with convention, the server name portion of the URL needs to be either absent or localhost:

$ svn checkout file:///path/to/repos ... $ svn checkout file://localhost/path/to/repos ...

Also, users of the file: scheme on Windows platforms need to use an unofficially standard syntax for accessing repositories that are on the same machine, but on a different drive than the client's current working drive. Either of the two following URL path syntaxes will work where X is the drive on which the repository resides:

C:\> svn checkout file:///X:/path/to/repos ... C:\> svn checkout "file:///X|/path/to/repos" ...

In the second syntax, you need to quote the URL so that the vertical bar character is not interpreted as a pipe.

Note that a URL uses ordinary slashes even though the native (non-URL) form of a path on Windows uses backslashes.

Table 2-1. Repository access URLs
Schema	Access Method
`file://`	direct repository access (on local disk)
`http://`	access via WebDAV protocol to Subversion-aware Apache server
`https://`	same as `http://`, but with SSL encryption.
`svn://`	access via custom protocol to an `svnserve` server
`svn+ssh://`	same as `svn://`, but through an SSH tunnel.

Suppose you make changes to button.c. Since the .svn directory remembers the file's modification date and original contents, Subversion can tell that you've changed the file. However, Subversion does not make your changes public until you explicitly tell it to do so. The act of publishing your changes is more commonly known as committing (or checking in) changes to the repository.

To publish your changes to others, you can use Subversion's commit command:

$ svn commit button.c Sending        button.c Transmitting file data . Committed revision 57.

Now your changes to button.c have been committed to the repository; if another user checks out a working copy of /calc, they will see your changes in the latest version of the file.

Suppose you have a collaborator, Sally, who checked out a working copy of /calc at the same time you did. When you commit your change to button.c, Sally's working copy is left unchanged; Subversion only modifies working copies at the user's request.

To bring her project up to date, Sally can ask Subversion to update her working copy, by using the Subversion update command. This incorporates your changes into her working copy, as well as any others that have been committed since she checked it out.

$ pwd /home/sally/calc $ ls -a  .svn/ Makefile integer.c button.c $ svn update U button.c

The output from the svn update command indicates that Subversion updated the contents of button.c. Note that Sally didn't need to specify which files to update; Subversion uses the information in the .svn directory, and further information in the repository, to decide which files need to be brought up to date.

2.3.2 Revisions

An svn commit operation can publish changes to any number of files and directories as a single atomic transaction. In your working copy, you can change files' contents; create, delete, rename and copy files and directories; and then commit the complete set of changes as a unit.

In the repository, each commit is treated as an atomic transaction: either all the commit's changes take place, or none of them take place. Subversion tries to retain this atomicity in the face of program crashes, system crashes, network problems, and other users' actions.

Each time the repository accepts a commit, this creates a new state of the filesystem tree, called a revision. Each revision is assigned a unique natural number, one greater than the number of the previous revision. The initial revision of a freshly created repository is numbered 0, and consists of nothing but an empty root directory.

Figure 2-7 illustrates a nice way to visualize the repository. Imagine an array of revision numbers, starting at 0, stretching from left to right. Each revision number has a filesystem tree hanging below it, and each tree is a snapshot of the way the repository looked after each commit.

Figure 2-7. The repository

Global Revision Numbers

Unlike those of many other version control systems, Subversion's revision numbers apply to entire trees, not individual files. Each revision number selects an entire tree, a particular state of the repository after some committed change. Another way to think about it is that revision N represents the state of the repository filesystem after the Nth commit. When a Subversion user talks about revision 5 of foo.c, they really mean foo.c as it appears in revision 5. Notice that in general, revisions N and M of a file do not necessarily differ! Because CVS uses per-file revision numbers, CVS users might want to see Appendix A for more details.

It's important to note that working copies do not always correspond to any single revision in the repository; they may contain files from several different revisions. For example, suppose you check out a working copy from a repository whose most recent revision is 4:

calc/Makefile:4      integer.c:4      button.c:4

At the moment, this working directory corresponds exactly to revision 4 in the repository. However, suppose you make a change to button.c, and commit that change. Assuming no other commits have taken place, your commit will create revision 5 of the repository, and your working copy now looks like this:

calc/Makefile:4      integer.c:4      button.c:5

Suppose that, at this point, Sally commits a change to integer.c, creating revision 6. If you use svn update to bring your working copy up to date, then it looks like this:

calc/Makefile:6      integer.c:6      button.c:6

Sally's changes to integer.c appears in your working copy, and your change is still present in button.c. In this example, the text of Makefile is identical in revisions 4, 5, and 6, but Subversion marks your working copy of Makefile with revision 6 to indicate that it is still current. Thus, after you do a clean update at the top of your working copy, it generally corresponds to exactly one revision in the repository.

2.3.3 How Working Copies Track the Repository

For each file in a working directory, Subversion records two essential pieces of information in the .svn/ administrative area:

what revision your working file is based on (this is called the file's working revision)
a timestamp recording when the local copy was last updated by the repository.

Given this information, by talking to the repository, Subversion can tell which of the following four states a working file is in:

Unchanged, and current: The file is unchanged in the working directory, and no changes to that file have been committed to the repository since its working revision. A svn commit of the file will do nothing, and an svn update of the file will do nothing.
Locally changed, and current: The file has been changed in the working directory, and no changes to that file have been committed to the repository since its base revision. There are local changes that have not been committed to the repository; thus an svn commit of the file will succeed in publishing your changes, and an svn update of the file will do nothing.
Unchanged, and out-of-date: The file has not been changed in the working directory, but it has been changed in the repository. The file should eventually be updated, to make it current with the public revision. An svn commit of the file will do nothing, and an svn update of the file will fold the latest changes into your working copy.
Locally changed, and out-of-date: The file has been changed both in the working directory, and in the repository. An svn commit of the file will fail with an out-of-date error. The file should be updated first; an svn update command will attempt to merge the public changes with the local changes. If Subversion can't complete the merge in a plausible way automatically, it leaves it to the user to resolve the conflict.

This may sound like a lot to keep track of, but the svn status command will show you the state of any item in your working copy. For more information on that command, see Section 3.5.3.1.

2.3.4 The Limitations of Mixed Revisions

As a general principle, Subversion tries to be as flexible as possible. One special kind of flexibility is the ability to have a working copy containing mixed revision numbers.

At first, it may not be entirely clear why this sort of flexibility is considered a feature, and not a liability. After completing a commit to the repository, the freshly committed files and directories are at a more recent working revision than the rest of the working copy. It looks like a bit of a mess. As demonstrated earlier, the working copy can always be brought to a single working revision by running svn update. Why would someone deliberately want a mixture of working revisions?

Assuming your project is sufficiently complex, you'll discover that it's sometimes nice to forcibly backdate portions of your working copy to an earlier revision; you'll learn how to do that in Chapter 3. Perhaps you'd like to test an earlier version of a submodule, contained in a subdirectory, or perhaps you'd like to examine a number of previous versions of a file in the context of the latest tree.

However you make use of mixed revisions in your working copy, there are limitations to this flexibility.

First, you cannot commit the deletion of a file or directory which isn't fully up-to-date. If a newer version of the item exists in the repository, your attempt to delete will be rejected, to prevent you from accidentally destroying changes you've not yet seen.

Second, you cannot commit a metadata change to a directory unless it's fully up-to-date. You'll learn about attaching properties to items in Chapter 6. A directory's working revision defines a specific set of entries and properties, and thus committing a property change to an out-of-date directory may destroy properties you've not yet seen.