Inside the Working Copy Administration Area
Prev | Chapter 8. Embedding Subversion | Next

## Inside the Working Copy Administration Area

As we mentioned earlier, each directory of a Subversion working copy contains a special subdirectory called `.svn` that 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 is 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

The Subversion working copy administration area's layout and contents are considered implementation details not really intended for human consumption. Developers are encouraged to use Subversion's public APIs, or the tools that Subversion provides, to access and manipulate the working copy data, instead of directly reading or modifying those files. The file formats employed by the working copy library for its administrative data do change from time to time—a fact that the public APIs do a great job of hiding from the average user. In this section, we expose some of these implementation details sheerly to appease your overwhelming curiosity.

### The Entries File

Perhaps the single most important file in the `.svn` directory is the `entries` file. It contains the bulk of the administrative information about the versioned items in a working copy directory. This one file 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!

Folks familiar with CVS's administrative directories will have recognized at this point that Subversion's `.svn/entries` file serves the purposes of, among other things, CVS's `CVS/Entries`, `CVS/Root`, and `CVS/Repository` files combined.

The format of the `.svn/entries` file has changed over time. Originally an XML file, it now uses a custom—though still human-readable—file format. While XML was a great choice for early developers of Subversion who were frequently debugging the file's contents (and Subversion's behavior in light of them), the need for easy developer debugging has diminished as Subversion has matured and has been replaced by the user's need for snappier performance. Be aware that Subversion's working copy library automatically upgrades working copies from one format to another—it reads the old formats and writes the new—which saves you the hassle of checking out a new working copy, but can also complicate situations where different versions of Subversion might be trying to use the same working copy.

### Pristine Copies and Property Files

As mentioned before, the `.svn` directory also holds the pristine “text-base” versions of files. You can find those 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, more efficient transmission of changes to the server—but they come 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 she wants 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.

Prev | Up | Next
Layered Library Design | Home | Using the APIs