Properties
We’ve already covered in detail how Subversion stores and retrieves various versions of files and directories in its repository. Whole chapters have been devoted to this most fundamental piece of functionality provided by the tool. And if the versioning support stopped there, Subversion would still be complete from a version control perspective.
But it doesn’t stop there.
In addition to versioning your directories and files, Subversion provides interfaces for adding, modifying, and removing versioned metadata on each of your versioned directories and files. We refer to this metadata as properties, and they can be thought of as two-column tables that map property names to arbitrary values attached to each item in your working copy. Generally speaking, the names and values of the properties can be whatever you want them to be, with the constraint that the names must contain only ASCII characters. And the best part about these properties is that they, too, are versioned, just like the textual contents of your files. You can modify, commit, and revert property changes as easily as you can file content changes. And the sending and receiving of property changes occurs as part of your typical commit and update operations—you don’t have to change your basic processes to accommodate them.
Note
Subversion has reserved the set of properties whose names begin
with svn: as its own. While there are
only a handful of such properties in use today, you should avoid
creating custom properties for your own needs with names that begin with
this prefix. Otherwise, you run the risk that a future release of
Subversion will grow support for a feature or behavior driven by a
property of the same name but with perhaps an entirely different
interpretation.
Properties show up elsewhere in Subversion, too. Just as files and directories may have arbitrary property names and values attached to them, each revision as a whole may have arbitrary properties attached to it. The same constraints apply—human-readable names and anything-you-want binary values. The main difference is that revision properties are not versioned. In other words, if you change the value of, or delete, a revision property, there’s no way, within the scope of Subversion’s functionality, to recover the previous value.
Subversion has no particular policy regarding the use of properties.
It asks only that you not use property names that begin with the
prefix svn:. That’s the
namespace that it sets aside for its own use. And Subversion does, in
fact, use properties—both the versioned and unversioned variety. Certain
versioned properties have special meaning or effects when found on files
and directories, or they house a particular bit of information about the
revisions on which they are found. Certain revision properties are
automatically attached to revisions by Subversion’s commit process, and
they carry information about the revision. Most of these properties are
mentioned elsewhere in this or other chapters as part of the more general
topics to which they are related. For an exhaustive list of Subversion’s
predefined properties, see Subversion Properties.
In this section, we’ll examine the utility—both to users of Subversion and to Subversion itself—of property support. You’ll learn about the property-related svn subcommands and how property modifications affect your normal Subversion workflow.