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, your working copy contains a
.svn, also known as
the working copy administrative
directory. The files in this administrative
directory help Subversion recognize which files contain
unpublished changes, and which files are out-of-date with
respect to others' work. Prior to 1.7 Subversion maintained
.svn administrative subdirectories in every
versioned directory of your working copy.
Subversion 1.7 takes a completely different approach and each
working copy now has only one administrative subdirectory which
is an immediate child of the root of that working copy.
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.
In other words, the repository's root directory has two
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.)
Suppose you make changes to
.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.
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.
Now your changes to
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
To bring her project up to date, Sally can ask Subversion to update her working copy, by using the Subversion update command. This will incorporate your changes into her working copy, as well as any others that have been committed since she checked it out.
Note that Sally didn't need to
specify which files to update; Subversion uses the information
.svn directory, and further
information in the repository, to decide which files need to
be brought up to date.
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. The URL schema indicates the access method:
Table 2.1. Repository Access URLs
||Direct repository access on local or network drive.|
||Access via WebDAV protocol to Subversion-aware Apache server.|
Same as |
Unauthenticated TCP/IP access via custom protocol
to a |
authenticated, encrypted TCP/IP access via custom protocol
to a |
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.
file:// access method is normally used
for local access, although it can be used with UNC paths to
a networked host. The URL therefore takes the form
file://hostname/path/to/repos. For the
local machine, the
hostname portion of the URL is required
to be either absent or
this reason, local paths normally appear with three slashes,
Also, users of the
file:// scheme on
Windows platforms will 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
file:///X:/path/to/repos ... file:///X|/path/to/repos ...
Note that a URL uses ordinary slashes even though the native (non-URL) form of a path on Windows uses backslashes.
You can safely access a FSFS repository via a network share, but you cannot access a BDB repository in this way.
Do not create or access a Berkeley DB repository on a network share. It cannot exist on a remote filesystem. Not even if you have the network drive mapped to a drive letter. If you attempt to use Berkeley DB on a network share, the results are unpredictable - you may see mysterious errors right away, or it may be months before you discover that your repository database is subtly corrupted.
A 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 commits changes take place, or none of them take place. Subversion retains 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 zero, and consists of nothing but an empty root directory.
A nice way to visualize the repository is as a series of trees. 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.
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
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 will now look 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 will look like this:
calc/Makefile:6 integer.c:6 button.c:6
Sally's changes to
appear in your working copy, and your change will still be
button.c. In this example,
the text of
Makefile is identical in
revisions 4, 5, and 6, but Subversion will mark your working
Makefile with revision 6 to
indicate that it is still current. So, after you do a clean
update at the top of your working copy, it will generally
correspond to exactly one revision in 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), and
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:
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 commit of the file will do nothing, and an update of the file will do nothing.
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 a commit of the file will succeed in publishing your changes, and an update of the file will do nothing.
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. A commit of the file will do nothing, and an update of the file will fold the latest changes into your working copy.
The file has been changed both in the working directory, and in the repository. A commit of the file will fail with an out-of-date error. The file should be updated first; an 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.