Just as Subversion uses properties to store extra information about the files, directories, and revisions that it contains, you might also find properties to be of similar use. You might find it useful to have a place close to your versioned data to hang custom metadata about that data.

Say you wish to design a web site that houses many digital photos and displays them with captions and a datestamp. Now, your set of photos is constantly changing, so you'd like to have as much of this site automated as possible. These photos can be quite large, so as is common with sites of this nature, you want to provide smaller thumbnail images to your site visitors.

Now, you can get this functionality using traditional files. That is, you can have your image123.jpg and an image123-thumbnail.jpg side by side in a directory. Or if you want to keep the filenames the same, you might have your thumbnails in a different directory, such as thumbnails/image123.jpg. You can also store your captions and datestamps in a similar fashion, again separated from the original image file. But the problem here is that your collection of files multiplies with each new photo added to the site.

Now consider the same web site deployed in a way that makes use of Subversion's file properties. Imagine having a single image file, image123.jpg, with properties set on that file that are named caption, datestamp, and even thumbnail. Now your working copy directory looks much more manageable—in fact, it looks to the casual browser like there are nothing but image files in it. But your automation scripts know better. They know that they can use svn (or better yet, they can use the Subversion language bindings—see the section called “Using the APIs”) to dig out the extra information that your site needs to display without having to read an index file or play path manipulation games.

Note

While Subversion places few restrictions on the names and values you use for properties, it has not been designed to optimally carry large property values or large sets of properties on a given file or directory. Subversion commonly holds all the property names and values associated with a single item in memory at the same time, which can cause detrimental performance or failed operations when extremely large property sets are used.

Custom revision properties are also frequently used. One common such use is a property whose value contains an issue tracker ID with which the revision is associated, perhaps because the change made in that revision fixes a bug filed in the tracker issue with that ID. Other uses include hanging more friendly names on the revision—it might be hard to remember that revision 1935 was a fully tested revision. But if there's, say, a test-results property on that revision with the value all passing, that's meaningful information to have. And Subversion allows you to easily do this via the --with-revprop option of the svn commit command:

$ svn commit -m "Fix up the last remaining known regression bug." \
             --with-revprop "test-results=all passing"
Sending        lib/crit_bits.c
Transmitting file data .
Committed revision 912.
$

$ svn log --with-all-revprops --xml lib/crit_bits.c
<?xml version="1.0"?>
<log>
<logentry
   revision="912">
<author>harry</author>
<date>2011-07-29T14:47:41.169894Z</date>
<msg>Fix up the last remaining known regression bug.</msg>
<revprops>
<property
   name="testresults">all passing</property>
</revprops>
</logentry>
…
$

Issue(s): IZ2376, IZ1919
Reviewed by:  sally

This fixes a nasty segfault in the wort frabbing process
…

The svn program affords a few ways to add or modify file and directory properties. For properties with short, human-readable values, perhaps the simplest way to add a new property is to specify the property name and value on the command line of the svn propset subcommand:

$ svn propset copyright '(c) 2006 Red-Bean Software' calc/button.c
property 'copyright' set on 'calc/button.c'
$

But we've been touting the flexibility that Subversion offers for your property values. And if you are planning to have a multiline textual, or even binary, property value, you probably do not want to supply that value on the command line. So the svn propset subcommand takes a --file (-F) option for specifying the name of a file that contains the new property value.

$ svn propset license -F /path/to/LICENSE calc/button.c
property 'license' set on 'calc/button.c'
$

There are some restrictions on the names you can use for properties. A property name must start with a letter, a colon (:), or an underscore (_); after that, you can also use digits, hyphens (-), and periods (.).^[13]

In addition to the propset command, the svn program supplies the propedit command. This command uses the configured editor program (see the section called “General configuration”) to add or modify properties. When you run the command, svn invokes your editor program on a temporary file that contains the current value of the property (or that is empty, if you are adding a new property). Then, you just modify that value in your editor program until it represents the new value you wish to store for the property, save the temporary file, and then exit the editor program. If Subversion detects that you've actually changed the existing value of the property, it will accept that as the new property value. If you exit your editor without making any changes, no property modification will occur:

$ svn propedit copyright calc/button.c  ### exit the editor without changes
No changes to property 'copyright' on 'calc/button.c'
$

We should note that, as with other svn subcommands, those related to properties can act on multiple paths at once. This enables you to modify properties on whole sets of files with a single command. For example, we could have done the following:

$ svn propset copyright '(c) 2006 Red-Bean Software' calc/*
property 'copyright' set on 'calc/Makefile'
property 'copyright' set on 'calc/button.c'
property 'copyright' set on 'calc/integer.c'
…
$

All of this property adding and editing isn't really very useful if you can't easily get the stored property value. So the svn program supplies two subcommands for displaying the names and values of properties stored on files and directories. The svn proplist command will list the names of properties that exist on a path. Once you know the names of the properties on the node, you can request their values individually using svn propget. This command will, given a property name and a path (or set of paths), print the value of the property to the standard output stream.

$ svn proplist calc/button.c
Properties on 'calc/button.c':
  copyright
  license
$ svn propget copyright calc/button.c
(c) 2006 Red-Bean Software

There's even a variation of the proplist command that will list both the name and the value for all of the properties. Simply supply the --verbose (-v) option.

$ svn proplist -v calc/button.c
Properties on 'calc/button.c':
  copyright
    (c) 2006 Red-Bean Software
  license
    ================================================================
    Copyright (c) 2006 Red-Bean Software.  All rights reserved.

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions 
    are met:

    1. Redistributions of source code must retain the above copyright
    notice, this list of conditions, and the recipe for Fitz's famous
    red-beans-and-rice.
    …

The last property-related subcommand is propdel. Since Subversion allows you to store properties with empty values, you can't remove a property altogether using svn propedit or svn propset. For example, this command will not yield the desired effect:

$ svn propset license "" calc/button.c
property 'license' set on 'calc/button.c'
$ svn proplist -v calc/button.c
Properties on 'calc/button.c':
  copyright
    (c) 2006 Red-Bean Software
  license
    
$

You need to use the propdel subcommand to delete properties altogether. The syntax is similar to the other property commands:

$ svn propdel license calc/button.c
property 'license' deleted from 'calc/button.c'.
$ svn proplist -v calc/button.c
Properties on 'calc/button.c':
  copyright
    (c) 2006 Red-Bean Software
$

Remember those unversioned revision properties? You can modify those, too, using the same svn subcommands that we just described. Simply add the --revprop command-line parameter and specify the revision whose property you wish to modify. Since revisions are global, you don't need to specify a target path to these property-related commands so long as you are positioned in a working copy of the repository whose revision property you wish to modify. Otherwise, you can simply provide the URL of any path in the repository of interest (including the repository's root URL). For example, you might want to replace the commit log message of an existing revision.^[14] If your current working directory is part of a working copy of your repository, you can simply run the svn propset command with no target path:

$ svn propset svn:log "* button.c: Fix a compiler warning." -r11 --revprop
property 'svn:log' set on repository revision '11'
$

But even if you haven't checked out a working copy from that repository, you can still effect the property change by providing the repository's root URL:

$ svn propset svn:log "* button.c: Fix a compiler warning." -r11 --revprop \
              http://svn.example.com/repos/project
property 'svn:log' set on repository revision '11'
$

Note that the ability to modify these unversioned properties must be explicitly added by the repository administrator (see the section called “Commit Log Message Correction”). That's because the properties aren't versioned, so you run the risk of losing information if you aren't careful with your edits. The repository administrator can set up methods to protect against this loss, and by default, modification of unversioned properties is disabled.

Tip

Users should, where possible, use svn propedit instead of svn propset. While the end result of the commands is identical, the former will allow them to see the current value of the property that they are about to change, which helps them to verify that they are, in fact, making the change they think they are making. This is especially true when modifying unversioned revision properties. Also, it is significantly easier to modify multiline property values in a text editor than at the command line.

Now that you are familiar with all of the property-related svn subcommands, let's see how property modifications affect the usual Subversion workflow. As we mentioned earlier, file and directory properties are versioned, just like your file contents. As a result, Subversion provides the same opportunities for merging—cleanly or with conflicts—someone else's modifications into your own.

As with file contents, your property changes are local modifications, made permanent only when you commit them to the repository with svn commit. Your property changes can be easily unmade, too—the svn revert command will restore your files and directories to their unedited states—contents, properties, and all. Also, you can receive interesting information about the state of your file and directory properties by using the svn status and svn diff commands.

$ svn status calc/button.c
 M      calc/button.c
$ svn diff calc/button.c
Property changes on: calc/button.c
___________________________________________________________________
Added: copyright
## -0,0 +1 ##
+(c) 2006 Red-Bean Software
$

Notice how the status subcommand displays M in the second column instead of the first. That is because we have modified the properties on calc/button.c, but not its textual contents. Had we changed both, we would have seen M in the first column, too. (We cover svn status in the section called “See an overview of your changes”).

$ svn update calc
Updating 'calc':
M  calc/Makefile.in
Conflict for property 'linecount' discovered on 'calc/button.c'.
Select: (p) postpone, (df) diff-full, (e) edit,
        (s) show all options: p
 C calc/button.c
Updated to revision 143.
Summary of conflicts:
  Property conflicts: 1
$ 

$ svn status calc
 C      calc/button.c
?       calc/button.c.prej
$ cat calc/button.c.prej 
Trying to change property 'linecount' from '1267' to '1301',
but property has been locally changed from '1267' to '1256'.
$

You might also have noticed the nonstandard way that Subversion currently displays property differences. You can still use svn diff and redirect its output to create a usable patch file. The patch program will ignore property patches—as a rule, it ignores any noise it can't understand. This does, unfortunately, mean that to fully apply a patch generated by svn diff using patch, any property modifications will need to be applied by hand.

Subversion 1.7 improves this situation in two ways. First, its nonstandard display of property differences is at least machine-readable—an improvement over the display of properties in versions prior to 1.7. But Subversion 1.7 also introduces the svn patch subcommand, designed specifically to handle the additional information which svn diff's output can carry, applying those changes to the Subversion working copy. Of specific relevance to our topic, property differences present in patch files generated by svn diff in Subversion 1.7 or better can be automatically applied to a working copy by the svn patch command. For more about svn patch, see svn patch in svn Reference—Subversion Command-Line Client.

Note

There's one exception to how property changes are reported by svn diff: changes to Subversion's special svn:mergeinfo property—used to track information about merges which have been performed in your repository—are described in a more human-readable fashion. This is quite helpful to the humans who have to read those descriptions. But it also serves to cause patching programs (including svn patch) to skip those change descriptions as noise. This might sound like a bug, but it really isn't because this property is intended to be managed solely by the svn merge subcommand. For more about merge tracking, see Chapter 4, Branching and Merging.

Subversion 1.8 introduces the concept of inherited properties. There is really nothing special about a property that makes it inheritable. In fact, all versioned properties are inheritable! The main difference between versioned properties before 1.8 and after is that the latter provides a mechanism to find the properties set on a target path's parents, even if those parents are not found within the working copy.

Generic property inheritance manifests itself in a few commands. First, the svn proplist and svn propget subcommands can retrieve all the properties on a URL's or a working copy path's parents by using the --show-inherited-props option. You might think of this as the opposite of a --recursive subcommand operation—instead of recursing "down" into a target's subdirectories, subcommands with the --show-inherited-props option look "up" into the target's parent directories. The svnlook propget and svnlook proplist subcommands also use the --show-inherited-props option in a similar fashion.

Let's look at an example of how this works. The following recursive propget on the root of our working copy finds that the svn:auto-props property is set on both the target of the subcommand and one of its subdirectories site :

$ svn pg svn:auto-props --verbose -R .
Properties on '.':
  svn:auto-props
    *.py = svn:eol-style=native
    *.c = svn:eol-style=native
    *.h = svn:eol-style=native

Properties on 'site':
  svn:auto-props
    *.html = svn:eol-style=native

If we were to instead make the target of the subcommand the subdirectory site, then using the --show-inherited-props option, we find that the svn:auto-props property is set on the target and its parent. The parent's properties are called out as "inherited":

$ svn pg svn:auto-props --verbose --show-inherited-props site
Inherited properties on 'site',
from '.':
  svn:auto-props
    *.py = svn:eol-style=native
    *.c = svn:eol-style=native
    *.h = svn:eol-style=native

Properties on 'site':
  svn:auto-props
    *.html = svn:eol-style=native

In the prior examples the root of the working copy corresponds to the root of the repository, but properties can also be inherited from outside the working copy when this is not the case. Let's checkout the site directory from the prior example, making it the root of our working copy:

$ svn co http://svn.example.com/repos site-wc
A    site-wc/publish
A    site-wc/publish/ch2.html
A    site-wc/publish/news.html
A    site-wc/publish/ch3.html
A    site-wc/publish/faq.html
A    site-wc/publish/index.html
A    site-wc/publish/ch1.html
 U   site-wc
Checked out revision 19.

$ cd site-wc

Now when we check for inherited properties on a working copy path we can see that one property is inherited from a working copy parent and one from a repository parent representing a location "above" the root of the working copy:

$ svn pg svn:auto-props --verbose --show-inherited-props publish
Inherited properties on 'publish',
from 'http://svn.example.com/repos':
  svn:auto-props
    *.py = svn:eol-style=native
    *.c = svn:eol-style=native
    *.h = svn:eol-style=native

Inherited properties on 'publish',
from '.':
  svn:auto-props
    *.html = svn:eol-style=native

	Warning
	You can only inherit properties from repository paths which you have read authorization to—see the section called “Built-in Authentication and Authorization” and the section called “Authorization Options”. If you don't have read authorization to a parent path then it will appear as if the parent has no properties set on it.

As mentioned above, the svnlook proplist and svnlook propget commands also support the --show-inherited-props option, but instead of reporting the inherited props by working copy path or URL, they are listed by repository paths:

$ svnlook pg repos svn:auto-props /site/publish --show-inherited-props -v
Inherited properties on '/site/publish',
from '/':
  svn:auto-props
    *.py = svn:eol-style=native
    *.c = svn:eol-style=native
    *.h = svn:eol-style=native

Inherited properties on '/site/publish',
from '/site':
  svn:auto-props
    *.html = svn:eol-style=native

Properties inherited from above the root of the working copy are cached in the working copy's administrative database when the working copy is initially checked out and then refreshed whenever the working copy is updated. This means that you don't need access to your repository to view inherited properties. This allows Subversion subcommands that have traditionally not required access to the repository (e.g. svn add ) to remain "disconnected" while still accessing properties inherited from paths not found in the working copy. However it also means that inherited properties from above the root of the working copy may have changed since your most recent update, causing your local cache to become out of date. So if you require the absolute latest value of some inherited property, it's always safest to update your working copy first or query the repository directly.

At this point you might be thinking, "nice trick, but what good is it?" By itself property inheritance isn't very useful. Before 1.8, all of Subversion's own reserved svn:* properties (and likely all of your own custom user properties) applied only to the path on which they were set or at most, the path's immediate children^[15] Rather, inheritable properties are a tool that Subversion uses to do other more interesting things, like setting automatic properties with the svn:auto-props property or repository-wide ignores with the svn:global-ignores property—see the section called “Automatic Property Setting” and the section called “Ignoring Unversioned Items” for more information about these special properties and how to use them.

Tip

Currently inheritable properties are primarily useful only as regards the svn:auto-props and svn:global-ignores properties but that doesn't mean those two properties are the end of the story. Look for more features to be built with inherited properties in future releases of Subversion—a log message templating mechanism comes to mind. In the meantime feel free to use the feature however you'd like. Any piece of versioned metadata you want to apply to your whole repository (or large subsections thereof) can easily be stored in a property on the root of your repository (or the appropriate subtree). We suspect that some users and administrators will come up with clever ways to use inheritable properties which we never considered.

Properties are a powerful feature of Subversion, acting as key components of many Subversion features discussed elsewhere in this and other chapters—textual diff and merge support, keyword substitution, newline translation, and so on. But to get the full benefit of properties, they must be set on the right files and directories. Unfortunately, that step can be easily forgotten in the routine of things, especially since failing to set a property doesn't usually result in an obvious error (at least compared to, say, failing to add a file to version control). To help your properties get applied to the places that need them, Subversion provides a few simple but useful features.

Whenever you introduce a file to version control using the svn add or svn import commands, Subversion tries to assist by setting some common file properties automatically. First, on operating systems whose filesystems support an execute permission bit, Subversion will automatically set the svn:executable property on newly added or imported files whose execute bit is enabled. (See the section called “File Executability” later in this chapter for more about this property.)

Second, Subversion tries to determine the file's MIME type. If you've configured a mime-types-files runtime configuration parameter, Subversion will try to find a MIME type mapping in that file for your file's extension. If it finds such a mapping, it will set your file's svn:mime-type property to the MIME type it found. If no mapping file is configured, or no mapping for your file's extension could be found, Subversion will fall back to heuristic algorithms to determine the file's MIME type. Depending on how it is built, Subversion 1.7 can make use of file scanning libraries^[16] to detect a file's type based on its content. Failing all else, Subversion will employ its own very basic heuristic to determine whether the file contains nontextual content. If so, it automatically sets the svn:mime-type property on that file to application/octet-stream (the generic “this is a collection of bytes” MIME type). Of course, if Subversion guesses incorrectly, or if you wish to set the svn:mime-type property to something more precise—perhaps image/png or application/x-shockwave-flash—you can always remove or edit that property. (For more on Subversion's use of MIME types, see the section called “File Content Type” later in this chapter.)

	Note
	UTF-16 is commonly used to encode files whose semantic content is textual in nature, but the encoding itself makes heavy use of bytes which are outside the typical ASCII character byte range. As such, Subversion will tend to classify such files as binary files, much to the chagrin of users who desire line-based differencing and merging, keyword substitution, and other behaviors for those files.

Subversion also provides, via its runtime configuration system (see the section called “Runtime Configuration Area”), a more flexible automatic property setting feature that allows you to create mappings of filename patterns to property names and values. Once again, these mappings affect adds and imports, and can not only override the default MIME type decision made by Subversion during those operations, but can also set additional Subversion or custom properties, too. For example, you might create a mapping that says that anytime you add JPEG files—ones whose names match the pattern *.jpg—Subversion should automatically set the svn:mime-type property on those files to image/jpeg. Or perhaps any files that match *.cpp should have svn:eol-style set to native, and svn:keywords set to Id. For more details on automatic property support in the runtime configuration see the section called “General configuration”.

While automatic property support via the runtime configuration system is certainly handy, Subversion administrators might prefer a set of property definitions which all connecting clients automatically consider when operating on working copies checked out from a given server. Subversion 1.8 and newer clients support such functionality through the svn:auto-props inheritable property.

The svn:auto-props property works like the runtime configuration to automatically set properties on files when they are added or imported. The value of the svn:auto-props property is expected to be the same as the auto-props runtime configuration option (i.e. Any number of key-value pairs in the format FILE_PATTERN = PROPNAME=VALUE[;PROPNAME=VALUE ...]) Like the auto-props runtime option, the svn:auto-props property can be disregarded when using the --no-auto-props option, but unlike the config option, the svn:auto-props property is not disabled when the enable-auto-props configuration option is set to no.

For example, say you have checked out a working copy of your trunk branch and need to add a new file (let's assume that automatic properties in your runtime configuration are disabled):

$ svn st
?       calc/data.c

$ svn add calc/data.c
A         calc/data.c

$ svn proplist -v calc/data.c
Properties on 'calc/data.c':
  svn:eol-style
    native

Notice that after you place the unversioned file data.c under version control the svn:eol-style property was automatically set on it. Since we assumed that the auto-props runtime configuration option is disabled, we know that the svn:auto-props property must be set on some parent path of data.c. Using the svn propget subcommand with the --show-inherited-props option we see that this is indeed the case:

$ svn propget svn:auto-props --show-inherited-props -v calc
Inherited properties on 'calc',
from 'http://svn.example.com/repos':
  svn:auto-props
    *.py = svn:eol-style=native
    *.c = svn:eol-style=native
    *.h = svn:eol-style=native

Unlike the svn:global-ignores property and its analogous runtime configuration global-ignores, which are combined, the svn:auto-props property overrides the auto-props runtime configuration if it defines an auto-prop for the same pattern as the runtime configuration. Automatic properties inherited^[17] from one path can also override the identical pattern inherited from a different path. The hierarchy of these overrides works as follows:

Let's look at an example. Suppose you have this runtime configuration:

[miscellany]
enable-auto-props = yes
[auto-props]
*.py  = svn:eol-style=CR
*.c   = svn:eol-style=CR
*.h   = svn:eol-style=CR
*.cpp = svn:eol-style=CR

And you want to add three files in the calc directory of your working copy:

$ svn st
?       calc/data-binding.cpp
?       calc/data.c
?       calc/editor.py

Let's check what svn:auto-props apply to calc:

$ svn propget svn:auto-props -v --show-inherited-props calc
Inherited properties on 'calc',
from 'http://svn.example.com/repos':
  svn:auto-props
    *.py = svn:eol-style=native
    *.c = svn:eol-style=native
    *.h = svn:eol-style=native

Inherited properties on 'calc',
from '.':
  svn:auto-props
    *.py = svn:eol-style=native
    *.c = svn:keywords=Author Date Id Rev URL

When we add these three files what auto-props do we expect? We add the trio to version control and then check:

$ svn add calc --force
A         calc/data-binding.cpp
A         calc/data.c
A         calc/editor.py

The file data-binding.cpp has only one matching pattern, *.cpp = svn:eol-style=CR in the runtime configuration, so obviously the svn:eol-style property is set to CR:

$ svn proplist -v calc/data-binding.cpp
Properties on 'calc/data-binding.cpp':
  svn:eol-style
    CR

The file editor.py matches a single pattern in runtime config and both of the svn:auto-props properties, but by the hierarchy described above, the property explicitly set on calc, *.py = svn:eol-style=native, takes precedence. So the svn:eol-style property is set to native::

$ svn proplist -v calc/editor.py
Properties on 'calc/editor.py':
  svn:eol-style
    native

The file data.c also matches patterns in the runtime config and both of the inherited svn:auto-props properties. The svn:keywords auto-prop is only defined once, on calc, so data.c automatically gets that property. The svn:auto-props on calc don't define a svn:eol-style value however, so the nearest inherited parent, http://svn.example.com/repos, provides that value:

$ svn proplist -v calc/data.c
Properties on 'calc/data.c':
  svn:eol-style
    native
  svn:keywords
    Author Date Id Rev URL

Warning

Overriding auto-props only applies for identical patterns. If a file to be added or imported matches more than one pattern, then there is no guarantee which pattern's auto-props will be applied. For example, say you want to add the file foo.cpp in the directory bar. Further, suppose the svn:auto-props property is set on bar with the value: *.c* = svn:eol-style=native *.cpp = svn:eol-style=native;svn:keywords=Author Date Id Rev URL Since foo.cpp matches both patterns, there is no way to know if the svn:keywords property will be set on foo.cpp when it is added.

A final note on svn:auto-props. This property (along with the similar svn:global-ignores, see the section called “Ignoring Unversioned Items”) only provides a recommendation to clients that understand the meaning of the property. Older clients will ignore these properties, the --no-auto-props option will disregard them, a user might manually change or remove automatic properties after they have been set—there are numerous ways in which the recommended properties contained in svn:auto-props can be by-passed. Given this, administrators will still need to use hook scripts to validate that the properties added to and modified on files and directories match the administrator's preferred policies, rejecting commits which are non-compliant in this fashion. (See the section called “Implementing Repository Hooks” for more about hook scripts.)

In this section, we'll briefly summarize all the properties which Subversion reserves for its own use. We'll look at both types of properties—those which are associated with individual versioned files and directories, and those which are associated with revisions.