14.1. Conceptual Overview Subversion is a version-control system. It lets you track changes to an entire project directory tree. Every change made to the tree is recorded and can be retrieved. Subversion is intended to be "a better CVS"; this is discussed in detail shortly. Subversion is purposely an open source project. If you want to participate, you can! 14.1.1. Basic Version-Control Operations Actual data is kept in a repository, a set of directories and files managed by Subversion. Users use the svn client program to access the repository and make changes to it. Subversion uses the copy-modify-merge development model. You make a private copy of a given project in a sandbox. (This is often called checking out a copy.) Like CVS, this private copy is not locked in the repository. You then make all the changes you like to the copy within the sandbox, without having to worry about what other developers are doing. As you work, you can compare your changes to the version you started with, as well as the version currently in the repository. Once you're satisfied with the changes, you commit them, sometimes referred to as a check-in. (These terms come from RCS and CVS.) In the event that another developer has modified part of a file that you were working on and checked it in, when you commit your changes, Subversion notices and indicates that a conflict exists. Conflicts are marked as such in the file, and Subversion creates pristine copies of the file as it exists in the repository and of the file as you modified it, so that you can do full comparisons. Once you have resolved the conflict, you tell Subversion about it, and then commit the final version. Like CVS, Subversion lets you create a development branch, a separate stream of development versions. You can periodically merge changes from the main development stream (the trunk) into your branch, and also merge changes from your branch back into the trunk. Finally, you can tag a particular copy of the project. For instance, when a project is ready for a release, you can create a snapshot of the project and give it a descriptive tag that allows you to re-create the project tree exactly as it was for the release. This is particularly valuable when you need to produce a bug fix for an older version of the project, or when you have to attempt to retrofit a fix or feature from current development into an older version. 14.1.2. Building a Better CVS When discussing Subversion's features, it is often helpful to speak of them in terms of how they improve upon CVS's design. Subversion provides:
Directory versioning CVS only tracks the history of individual files, but Subversion implements a virtual versioned filesystem that tracks changes to whole directory trees over time. Files and directories are versioned.
True version history Since CVS is limited to file versioning, operations such as copies and renameswhich might happen to files, but which are really changes to the contents of some containing directoryaren't supported in CVS. In CVS, you cannot delete a versioned file and then create a new file of the same name with different contents without inheriting the history of the oldperhaps completely unrelatedfile. With Subversion, you can add, delete, copy, and rename both files and directories. And every newly added file begins with a fresh, clean history all its own, even if the filename was previously used.
Atomic commits A collection of modifications either goes into the repository completely, or not at all. This allows developers to construct and commit changes as logical chunks, and prevents problems that can occur when only a portion of a set of changes is successfully sent to the repository.
Versioned metadata Each file and directory has a set of propertieskeys and their valuesassociated with it. You can create and store any arbitrary key/value pairs. Properties are versioned over time, just like file contents.
Choice of network layers Subversion has an abstracted notion of repository access, making it easy for people to implement new network mechanisms. Subversion can plug into the Apache HTTP Server as an extension module. This gives Subversion a big advantage in stability and interoperability, and instant access to existing features provided by that serverauthentication, authorization, wire compression, and so on. A more lightweight, standalone Subversion server process is also available. This server speaks a custom protocol that can be easily tunneled over SSH.
Consistent data handling Subversion expresses file differences using a binary differencing algorithm, which works identically on both text (human-readable) and binary (human-unreadable) files. Both types of files are stored equally compressed in the repository, and only the differences are transmitted in both directions across the network.
Efficient branching and tagging The cost of branching and tagging need not be proportional to the project size. Subversion creates branches and tags by simply copying the project, using a mechanism similar to a hard link. Thus these operations take only a very small, constant amount of time.
Hackability Subversion has no historical baggage; it is implemented as a collection of shared C libraries with well-defined APIs. This makes Subversion extremely maintainable and usable by other applications and languages.
Optimized around the network Disk storage continues to increase in size and speed, and decrease in cost: disk space is cheap on today's systems. However, network connectivity has not kept pace; access to remote repositories is several orders of magnitude slower than local access. Thus the Subversion design is optimized to avoid connecting to the repository when possible. For example, in the working copy's administrative directory, .svn, Subversion maintains a pristine copy of each file as it was checked out of the repository. This makes it possible to produce the differences very quickly, with no need to contact the repository.
In addition, Subversion uses similar commands to those of CVS, making it straightforward to transfer your CVS habits to Subversion. 14.1.3. Converting a Repository from CVS to Subversion A very effective way to learn Subversion if you already know CVS is to move your project from CVS to Subversion. The minimal way to accomplish this is to do a flat import into a Subversion repository from an exported CVS repository. However, this only gives you a "snapshot" of your repository; the revision history (changes, logs, tags, branches, etc.) are not kept. Copying a repository while maintaining history is a difficult problem to solve. Nevertheless, a few tools exist that at least partially convert existing CVS repositories into new Subversion ones, such as cvs2svn, a Python script originally created by members of Subversion's own development community (see http://cvs2svn.tigris.org/), and Lev Serebryakov's RefineCVS (see http://lev.serebryakov.spb.ru/refinecvs/). For an updated collection of links to known converter tools, visit the Links page of the Subversion web site (http://subversion.tigris.org/project_links.html). 14.1.4. Special File Properties Subversion allows you to associate properties with files or directories. A property is just a keyword/value pair associated with the file. Subversion reserves property names starting with svn: for its own use. The special properties in Subversion 1.0 are:
svn:author The username of the person who committed a particular revision.
svn:date The date when the transaction for a revision was created.
svn:eol-style Different operating systems use different conventions to mark the end of lines in text files. Unix and its workalikes use a single ASCII line-feed character (LF) to end lines. MS Windows systems use a Carriage Return + Line Feed combination (CRLF), and older Macintosh systems use a single Carriage Return (CR). This can cause problems when a Windows user stores a new revision of the file: suddenly a Unix user who does a checkout sees a file with extraneous Carriage Return characters at the end of every line. The svn:eol-style attribute solves this problem. It should be set to one of the following values:
CR Clients should always use CR line terminators, no matter what the native format is.
CRLF Clients should always use CR-LF line terminators, no matter what the native format is.
LF Clients should always use LF line terminators, no matter what the native format is.
native Clients should use the native format when checking out files.
Subversion always stores files in normalized, LF-only format in the repository.
svn:executable Valid only for files, the mere presence of this property indicates that the file should be made executable when it's checked out or updated from the repository. It has no effect on filesystems, such as FAT-32 or NTFS, that don't have the concept of an execute bit.
svn:externals This property, when set on a directory under version control, allows you to specify other, external repositories to use for particular local subdirectories. You set this property with svn propset or svn propedit (see svn Subcommands," later in this chapter). The value is a multiline table of directories and fully qualified Subversion URLs. For example: $ svn propget svn:externals calc third-party/sounds http://sounds.red-bean.com/repos third-party/skins http://skins.red-bean.com/repositories/ skinproj third-party/skins/toolkit -r21 http://svn.red-bean.com/repos/skin-maker
Once set, anyone else who checks out a working copy will also get the third party files checked out automatically.
svn:ignore A property containing a list of file patterns that certain Subversion operations will ignore. It should be set on directories, as needed. It works to filter unversioned files and directories out of commands like svn status, svn add, and svn import. It is similar to the .cvsignore file in CVS, and you can often import your .cvsignore with this command: $ svn propset svn:ignore -F .cvsignore . property 'svn:ignore' set on '.'
svn:keywords A list of keywords for which Subversion should perform keyword expansion when checking out the file. This is purposely similar to the same feature in RCS and CVS. However, Subversion does keyword expansion only when this property is set, and only for the keywords listed in the property's value. The list of recognized keywords is provided shortly.
svn:log The log message associated with the commit of a particular revision.
svn:mime-type An indication of the type of data stored in the file. In general, if it does not begin with text/, Subversion assumes that the file contains binary data. For updates, this causes Subversion to rename a modified working copy of the file with a .orig extension and replace the file with the current version from the repository. This prevents an attempt to perform a "merge" on data that can't be merged. This property also influences how the Subversion Apache module sets the HTTP Content-type: header.
svn:realmstring A specialized property that describes the "authentication realm" for a file in Subversion's cached copy of the authentication credentials. See Chapter 6 of Version Control with Subversion (O'Reilly) for more information.
Subversion defines the list of keywords available for substitution. That list contains the following five keywords, some of which have shorter aliases that you can also use:
$LastChangedDate$ This keyword describes the last time the file was changed in the repository and looks like $LastChangedDate: 2002-07-22 21:42:37 -0700 (Mon, 22 Jul 2002) $. It may be abbreviated as Date.
$LastChangedRevision$ This keyword describes the last revision in which this file changed in the repository and looks like $LastChangedRevision: 144 $. It may be abbreviated as Revision or Rev.
$LastChangedBy$ This keyword describes the last user to change this file in the repository, and looks like $LastChangedBy: harry $. It may be abbreviated as Author.
$HeadURL$ This keyword describes the full URL to the latest version of the file in the repository. It looks like $HeadURL: http://svn.collab.net/repos/trunk/README $. It may be abbreviated as URL.
$Id: ch14.xml,v 1.5 2005/08/12 21:21:32 sally Exp sally $ This keyword is a compressed combination of the other keywords. Its substitution looks like $Id: ch14.xml,v 1.5 2005/08/12 21:21:32 sally Exp sally $, and is interpreted to mean that the file calc.c was last changed in revision 148 on the evening of July 28, 2005 by the user sally.
|
