This section is from the "Version Control with Subversion" book, by Ben Collins-Sussman, Brian W. Fitzpatrick and C. Michael Pilato. Also available from Amazon: Version Control with Subversion.
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. You can even have multiple working copies of the same project.
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's 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 subdirectory, as shown in Figure 1.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/Makefile A calc/integer.c A calc/button.c Checked out revision 56. $ ls -A calc Makefile integer.c button.c .svn/
The list of letter As in the left margin 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
—which
holds the extra information needed by Subversion, as mentioned
earlier.
Suppose you make changes to button.c
.
Since the .svn
directory remembers the
file's original modification date and 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.
$ svn commit button.c -m "Fixed a typo in button.c." Sending button.c Transmitting file data . Committed revision 57.
Now your changes to button.c
have
been committed to the repository, with a note describing your
change (namely, that you fixed a typo). 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 modifies working copies only at the
user's request.
To bring her project up to date, Sally can ask Subversion to update her working copy, by using the 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.
$ pwd /home/sally/calc $ ls -A .svn/ Makefile integer.c button.c $ svn update U button.c Updated to revision 57.
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 as well as further
information in the repository, to decide which files need to
be brought up to date.