Section 5.2. Checking Out and Maintaining a Working Copy

5.2. Checking Out and Maintaining a Working Copy

A working copy is created by checking out all or part of a Subversion repository, using the command svn checkout (which can be abbreviated svn co). To indicate the repository that should be checked out, you pass a URL that points to the desired repository along with the checkout command. The exact form that the URL takes depends on the type of server that you are contacting.

If the repository is being served by Apache, via HTTP/WebDAV, the appropriate URL prefix is http://, or if the connection is secured by SSL, https://. On the other hand, if the Subversion server for the repository is svnserve, you will want to use svn:// or svn+ssh://, depending on whether the connection should be tunneled over SSH. Finally, if you are not contacting a remote server, but are instead directly accessing a repository that resides on the local machine, the prefix should be file://. The remainder of the URL follows the same standards as a URL used for any other purpose and consists of the form [e-mail]/path/to/repository. Of course, the username and hostname are dropped if it is a directly accessed local repository, via a file:// prefix. Also, remember that a local filesystem path should have an initial /, in addition to the prefixed double slash (so you should have three slashes total). This applies even for local filesystem URLs on Windows, even though Windows doesn't use the slash to indicate a root directory in the filesystem hierarchy.

You can also make a working copy that consists of only part of a repository by continuing the path in the URL out to identify the portion to check out. For example, if a repository repos contains a directory named trunk at the top level, you could check out just trunk by issuing the following command.

 $ svn co http://svn.example.com/repos/trunk A trunk A trunk/foo.c 

Running the preceding checkout command with that URL will check out just the TRunk directory in the repository and create a local directory named TRunk in the directory where the checkout command was run. The trunk directory is now your working copy. It contains copies of the versioned files located inside the TRunk directory, as well as a directory named .svn, where Subversion stores metadata about the local working copy.

If you want to check out a working copy into a directory other than the directory where the svn co command is actually run (for instance, if you create a script to automate the checkout), you can pass a path to the checkout command, after the URL, which will tell Subversion where to place the checked out working copy. So, if you want to check out a repository into your home directory, you can run the following command from anywhere:

 $ svn co http://svn.example.com/repos /home/bill/repos_wc A repos_wc A repos_wc/trunk A repos_wc/trunk/foo.c A repos_wc/branches A repos_wc/branches/branch1/foo.c A repos_wc/tags 

Subversion also allows you to specify multiple URLs to check out on the same command line. If you do supply multiple URLs, Subversion will check out each of the repositories (or subsets of a repository) given, and place them either in the local directory or the directory given as a path after all of the URLs.

 $ svn co http://svn.example.com/repos/trunk http://svn.mycomain.com/repos/branches A trunk A trunk/foo.c A branches A branches/branch1/foo.c 

If for one reason or another you don't want to check out the subdirectories of a repository, you can also pass svn co the argument --non-recursive (-N) to tell it to only check out the directory given, without checking out the contents of any directories it contains. If you do this though, the working copy will remember that you didn't check out any of the subdirectories, and it won't get them when you do an update either. If you do want to get a subdirectory that wasn't checked out originally, you can get it by running svn update with the name of the directory you'd like to get.

 $ svn co --non-recursive http://svn.example.com/repos Checked out revision 21657 $ cd repos/ $ ls -a .  ..  .svn $ svn update trunk A  trunk A  trunk/test.c $ ls -a .  ..  .svn  trunk 

There may also be times when you want to check out a revision of the repository other than the HEAD revision. You can do this by passing --revision (-r) with the revision that you want to check out. The revision can either be an explicit revision number, or it can be a date (which needs to be enclosed in brackets). For example, if you want to check out the last revision committed before July 20th, 2004 at noon, you could check out with the following command.

 $ svn co --revision "{2004-07-20 12:00}" http://svn.example.com/repos 

5.2.1. Keeping Up-to-Date

After you have a repository checked out, you will want to keep it up-to-date with changes made by other developers. The basic command for doing this is svn update (or svn up). When it is run without any options, the differences between the current revision of files in your working copy and the HEAD revision of the repository are downloaded from the server and applied to your working copy. As it updates, Subversion will show you which files were updated, and what sort of update occurred.

 $ svn update A  trunk/vid/wildflowers.mpg U  trunk/src/anim.c D  trunk/src/works.c G  trunk/src/Makefile C  trunk/README Updated to revision 1450. 

As you can see here, there were five files modified by the update, and each one has a different letter in front of its name. Each of those letters tells you what Subversion did when it updated the file in your working copy. Only files that were in some way updated are shown in the output.

• The A tells you that a file named trunk/vid/wildflowers.mpg has been added to the repository since your last update, so Subversion downloaded a copy of it and added it to your working copy.

• The U tells you that the file TRunk/src/anim was updated with changes from the repository.

• The D tells you that file was deleted from your working copy, because it no longer exists in the repository.

• The G tells you that Subversion merged the changes received from the repository with the locally modified file trunk/src/Makefile.

• The C indicates that Subversion was not able to merge the changes to the file trunk/README, and has instead declared a conflict.

If the update command is run with no path supplied, it operates on the current directory and recursively updates that directory and all of its contents. If a path is supplied, it updates the directory or file that is given, as well as anything contained within if the path points to a directory. If recursive updating is not what you want (for instance, if you want to update the properties associated with a directory without updating its contents), you can use the --non-recursive option. The following command, for example, will update the trunk directory, but leave its contents untouched.

 $ svn update --non-recursive /home/bill/repos/trunk U  trunk Updated to revision 1478. 

It is important to note that svn update operates on files and directories known to the repository, regardless of whether those files have been locally removed from your working copy. The advantage of this is best illustrated by the following snippet.

 $ ls foo.c        bar.c $ rm bar.c $ svn update bar.c U  bar.c Updated to revision 503. $ ls foo.c        bar.c 

As you can see, Subversion makes it easy to recover files that were locally deleted, eliminating any worry about causing real harm to data within the working copy. Recovering a file by deleting and updating can also be handy if a file in the working copy somehow gets corrupted. In most cases, if Subversion is misbehaving on a versioned file, you can get things back to a sane state by just deleting (or moving) it and performing an svn update.

Another command that is useful for restoring a working copy to a known state is svn revert. This command works similarly to svn update, but instead of updating to a different revision in the repository, the revert command restores locally modified files to a pristine version of the file, corresponding to the most recent checkout, update, or commit.

Reversions that are done with svn revert are very fast, because Subversion always keeps a pristine copy of every versioned file in the working copy.^[1] This allows the revert to occur without contacting the remote repository, saving not just time but also bandwidth.

^[1] Subversion stores pristine copies for every file in a working copy directory inside the corresponding .svn directory.

As a safety feature though (because the command can destroy local changes), svn revert does not recurse into subdirectories like svn checkout and svn update, nor will it do anything if you run it without explicitly identifying the files to revert. If you want recursion, you have to explicitly request it with the --recursive (-R) option. Subversion also can't revert directories that were locally deleted. To do that, you have to use svn update.