8.3 Inside the Working Copy Administration Area

As we mentioned earlier, each directory of a Subversion working copy contains a special subdirectory called .svn which houses administrative data about that working copy directory. Subversion uses the information in .svn to keep track of things such as:

• Which repository location(s) are represented by the files and subdirectories in the working copy directory

• What revision of each of those files and directories are currently present in the working copy

• Any user-defined properties that might be attached to those files and directories

• Pristine (unedited) copies of the working copy files

While there are several other bits of data stored in the .svn directory, we examine only a couple of the most important items.

8.3.1 The Entries File

Perhaps the single most important file in the .svn directory is the entries file. The entries file is an XML document that contains the bulk of the administrative information about a versioned resource in a working copy directory. It is this one file which tracks the repository URLs, pristine revision, file checksums, pristine text and property timestamps, scheduling and conflict state information, last-known commit information (author, revision, timestamp), local copy history practically everything that a Subversion client is interested in knowing about a versioned (or to-be-versioned) resource!

Comparing the Administrative Areas of Subversion and CVS

A glance inside the typical .svn directory turns up a bit more than what CVS maintains in its CVS administrative directories. The entries file contains XML which describes the current state of the working copy directory, and basically serves the purposes of CVS's Entries, Root, and Repository files combined.

Example 8-4 is an example of an actual entries file.

Example 8-4. Contents of a typical .svn/entries file

<?xml version="1.0" encoding="utf-8"?> <wc-entries    xmlns="svn:"> <entry    committed-rev="1"    name="svn:this_dir"    committed-date="2002-09-24T17:12:44.064475Z"    url="http://svn.red-bean.com/tests/.greek-repo/A/D"    kind="dir"    revision="1"/> <entry    committed-rev="1"    name="gamma"    text-time="2002-09-26T21:09:02.000000Z"    committed-date="2002-09-24T17:12:44.064475Z"    checksum="QSE4vWd9ZM0cMvr7/+YkXQ= ="    kind="file"    prop-time="2002-09-26T21:09:02.000000Z"/> <entry    name="zeta"    kind="file"    schedule="add"    revision="0"/> <entry    url="http://svn.red-bean.com/tests/.greek-repo/A/B/delta"    name="delta"    kind="file"    schedule="add"    revision="0"/> <entry    name="G"    kind="dir"/> <entry    name="H"    kind="dir"    schedule="delete"/> </wc-entries>

As you can see, the entries file is essentially a list of entries. Each <entry> tag represents one of three things: the working copy directory itself (called the this directory entry, and noted as having an empty value for its name attribute), a file in that working copy directory (noted by having its kind attribute set to "file"), or a subdirectory in that working copy (kind here is set to "dir"). The files and subdirectories whose entries are stored in this file are either already under version control, or (as in the case of the file named zeta above) are scheduled to be added to version control when the user next commits this working copy directory's changes. Each entry has a unique name, and each entry has a node kind.

Developers should be aware of some special rules that Subversion uses when reading and writing its entries files. While each entry has a revision and URL associated with it, note that not every <entry> tag in the sample file has explicit revision or url attributes attached to it. Subversion allows entries to not explicitly store those two attributes when their values are the same as (in the revision case) or trivially calculable from^[4] (in the url case) the data stored in the this directory entry. Note also that for subdirectory entries, Subversion stores only the crucial attributes name, kind, url, revision, and schedule. In an effort to reduce duplicated information, Subversion dictates that the method for determining the full set of information about a subdirectory is to traverse down into that subdirectory, and read the this directory entry from its own .svn/entries file. However, a reference to the subdirectory is kept in its parent's entries file, with enough information to permit basic versioning operations in the event that the subdirectory itself is actually missing from disk.

^[4] That is, the URL for the entry is the same as the concatenation of the parent directory's URL and the entry's name.

8.3.2 Pristine Copies and Property Files

As mentioned before, the .svn directory also holds the pristine text-base versions of files. Those can be found in .svn/text-base. The benefits of these pristine copies are multiple network-free checks for local modifications and difference reporting, network-free reversion of modified or missing files, smaller transmission of changes to the server but comes at the cost of having each versioned file stored at least twice on disk. These days, this seems to be a negligible penalty for most files. However, the situation gets uglier as the size of your versioned files grows. Some attention is being given to making the presence of the text-base an option. Ironically though, it is as your versioned files' sizes get larger that the existence of the text-base becomes more crucial who wants to transmit a huge file across a network just because they want to commit a tiny change to it?

Similar in purpose to the text-base files are the property files and their pristine prop-base copies, located in .svn/props and .svn/prop-base respectively. Since directories can have properties, too, there are also .svn/dir-props and .svn/dir-prop-base files. Each of these property files (working and base versions) uses a simple hash-on-disk file format for storing the property names and values.