Section 6.1. Storing Metadata

6.1. Storing Metadata

Properties are associated with a file or directory by using the svn propset command. The simplest way to set a property is by passing to the svn propset command the property key and value, along with the file to set the property on.

 $ svn propset property_key "property value" repos/trunk/foo.h 

The property key is a string of your choosing, which will be used later for retrieving the associated data from the file. Property keys are handled internally by Subversion as XML, and therefore the property keys themselves are restricted by valid XML NAMES, which is basically any string that contains letters, digits, ., -, and _. For a more formal definition, see the XML standard, available from the World Wide Web Consortium (www.w3.org).

When choosing property names, it is a good idea to use some sort of naming convention. The naming scheme used by the built-in Subversion properties is to begin each property key with svn:. This might seem like a good convention to adopt for your own property names, but alas, the colon isn't really a valid character in property names. It can only be used reliably in the svn: prefix. It is, however, a sound idea to use prefixes to categorize your properties. You just can't categorize them with a colon. Instead, I suggest using a period to separate a category prefix from a property name. This allows you to assign properties to different categories, and name them accordingly, making it easy to quickly identify broad purposes for the properties, which makes specific meaning easier to discern and remember. You are also able to selectively search for all of the properties in a given category, using the svn proplist command, as I will discuss later in Section 6.2.1, "Listing Properties."

As an example, let's say that you use Subversion properties to store automated tests and file ownership information. You can then standardize on two property categories, named test and ownership. A property containing a unit-testing script could be named test.unit, and properties containing the file's author and copyright could be named ownership.author and ownership.copyright.

Subversion property values can be of any form, either text or binary. If the property is short, it is easy to provide it as a parameter on the command line (remember to enclose it with quotation marks if it has spaces though). If the property is long, or if it is a binary file, entering the property value on the command line is impractical. In that case, you can direct svn propset to read the property from a file using the --file (-F) option, which directs Subversion to read the property's value from a file, as in the following example.

 $ svn propset property_key --file ~/property_val.txt repos/trunk/foo.h 

6.1.1. Editing Properties

Sometimes, you don't want to change an entire property, but would rather make a small change to an existing one. In these cases, Subversion provides you with the svn propedit command, which opens the current property in the current editor.^[1] After you have finished editing the property's value, you can save the file and quit. As soon as you quit, Subversion will apply the modified property value to the file or directory's property.

^[1] See Section 7.2.1, "The config File.".

Subversion does not require that a property must exist prior to calling svn propedit. If you have a long property to add to a file or directory, it is often easier to call svn propedit instead of svn propset to add the initial property value to the file. All you need to do is just run the propedit command and type in the property to the new document that is opened in the editor. When you're done, save and quit.

6.1.2. Automatically Setting Properties

If you have a property that needs to be set for every file of a certain type that's added, it's almost a guarantee that you will forget at least once if you need to set the property manually every time. Fortunately, if the value of the property is static for every file of a certain filename pattern, you can tell Subversion to set the value automatically. All you have to do is set up the Subversion configuration file with the appropriate patterns and values (see Section 7.2.1).

6.1.3. Committing Properties

When you run svn propset or svn propedit, Subversion sets the new property value in the working copy, but does not contact the repository. Instead, the property changes are scheduled to be committed to the repository on the next svn commit. You can tell which files and directories will have properties committed on the next svn commit by running svn status. The status command will show all files with modified properties by placing an M in the second column of its output.

When you commit a file or directory property to the repository, it is handled just like file data. It is applied to the new revision, but doesn't affect any previous revisions.

6.1.4. Storing Revision Properties

Revision properties are stored using the --revprop option to either svn propset or svn propedit. They must be set on a particular revision, so you also need to use the --revision (-r) option when setting or editing a revision property. Be careful when using svn propset, because changes are applied immediately and are not undoable. Any previous data in the revision property will be irretrievably lost. It is almost always better to use svn propedit when working with revision properties, as it is much harder to accidentally delete important data that way.

As an example, the following command will invoke an editor to edit a property that stores which issue-tracking issue is fixed in the last revision that you committed.

 $ svn status --show-updates Status against revision:   2225 $ svn propedit --revprop --revision 2225 issues.fixes 

You'll notice that I didn't run svn propedit with the HEAD revision label, but instead used svn status -show-updates to get the number of the HEAD revision. I do that to ensure that I am setting the revision property on the revision that I think I am. If another user were to commit a new revision while I was editing the property, the HEAD would be changed to point to the new head of the repository, which is likely not the revision that I want to edit. It's always safer to get the revision number and then use that explicitly.