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 whose names 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 do not use property names that begin with the prefix svn: as 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 the section called “Subversion's Reserved Properties”.

Note

While Subversion automatically attaches properties (svn:date, svn:author, svn:log, and so on) to revisions, it does not presume thereafter the existence of those properties, and neither should you or the tools you use to interact with your repository. Revision properties can be deleted programmatically or via the client (if allowed by the repository hooks) without damaging Subversion's ability to function. So, when writing scripts which operate on your Subversion repository data, do not make the mistake of assuming that any particular revision property exists on a revision.

In this section, we will 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.

Why Properties?

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.
$

Manipulating Properties

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.

Properties and the Subversion Workflow

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”).

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.

Inherited Properties

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.

Automatic Property Setting

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:

  • An auto-prop, for a given pattern, defined in svn:auto-props overrides the same auto-prop for the identical pattern in the auto-props runtime configuration.

  • If an auto-prop, for a given pattern, is inherited from more than one parents' svn:auto-props property, the nearer path-wise parent overrides the more distant parents.

  • An auto-prop, for a given pattern, defined in a svn:auto-props property explicitly set on a path overrides the same auto-prop(s) for the identical pattern inherited from any parents.

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.)

Subversion's Reserved Properties

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.

Versioned properties

These are the versioned (or node) properties that Subversion reserves for its own use:

svn:auto-props

If present on a directory, the value is a set of automatic property definitions which apply to all files under the directory, See the section called “Automatic Property Setting”.

svn:executable

If present on a file, the client will make the file executable in Unix-hosted working copies. See the section called “File Executability”.

svn:mime-type

If present on a file, the value indicates the file's MIME type. This allows the client to decide whether line-based contextual merging is safe to perform during updates, and can also affect how the file behaves when fetched via a web browser. See the section called “File Content Type”.

svn:ignore

If present on a directory, the value is a list of unversioned file patterns to be ignored by svn status and other subcommands. See the section called “Ignoring Unversioned Items”.

svn:global-ignores

If present on a directory, the value is a list of unversioned file patterns to be ignored by svn status and other subcommands. Unlike svn:ignore these patterns apply to all unversioned subtrees under the directory, not just the directory's immediate file children. See the section called “Ignoring Unversioned Items”.

svn:keywords

If present on a file, the value tells the client how to expand particular keywords within the file. See the section called “Keyword Substitution”.

svn:eol-style

If present on a file, the value tells the client how to manipulate the file's line-endings in the working copy and in exported trees. See the section called “End-of-Line Character Sequences” and svn export.

svn:externals

If present on a directory, the value is a multiline list of other paths and URLs the client should check out. See the section called “Externals Definitions”.

svn:special

If present on a file, indicates that the file is not an ordinary file, but a symbolic link or other special object.[18]

svn:needs-lock

If present on a file, tells the client to make the file read-only in the working copy, as a reminder that the file should be locked before editing begins. See the section called “Lock Communication”.

svn:mergeinfo

Used by Subversion to track merge data. See the section called “Mergeinfo and Previews” for details, but you should never edit this property unless you really know what you're doing.

Unversioned properties

The following are the unversioned (or revision) properties that Subversion reserves for its own use. Most of these appear on every revision in the repository, carrying important information about the origin and nature of the changes made in that revision.

svn:author

If present, contains the authenticated username of the person who created the revision. (If not present, the revision was committed anonymously.)

svn:autoversioned

If present, the revision was created via the autoversioning feature. See the section called “Autoversioning”.

svn:date

Contains the UTC time the revision was created, in ISO 8601 format. The value comes from the server machine's clock, not the client's.

svn:log

Contains the log message describing the revision.

Certain auxiliary tools in the Subversion toolchain—namely, svnrdump and svnsync—also use unversioned properties for their own accounting purposes. These properties are found only on revision 0 of repositories on which these tools are operating. For more about svnrdump and svnsync and the functionality they offer, see Chapter 5, Repository Administration. The following are the properties created and managed by these tools.

svn:rdump-lock

Used to temporarily enforce mutually exclusive access to the repository by svnrdump load. This property is generally only observed when such an operation is active—or when an svnrdump command failed to cleanly disconnect from the repository. (This property is only relevant when it appears on revision 0.)

svn:sync-currently-copying

Contains the revision number from the source repository which is currently being mirrored to this one by the svnsync tool. (This property is only relevant when it appears on revision 0.)

svn:sync-from-uuid

Contains the UUID of the repository of which this repository has been initialized as a mirror by the svnsync tool. (This property is only relevant when it appears on revision 0.)

svn:sync-from-url

Contains the URL of the repository directory of which this repository has been initialized as a mirror by the svnsync tool. (This property is only relevant when it appears on revision 0.)

svn:sync-last-merged-rev

Contains the revision of the source repository which was most recently and successfully mirrored to this one. (This property is only relevant when it appears on revision 0.)

svn:sync-lock

Used to temporarily enforce mutually exclusive access to the repository by svnsync mirroring operations. This property is generally only observed when such an operation is active—or when an svnsync command failed to cleanly disconnect from the repository. (This property is only relevant when it appears on revision 0.)



[13] If you're familiar with XML, this is pretty much the ASCII subset of the syntax for XML Name.

[14] Fixing spelling errors, grammatical gotchas, and just-plain-wrongness in commit log messages is perhaps the most common use case for the --revprop option.

[15] The one noteable exception to this being the svn:mergeinfo property, which is inheritable—see the section called “Mergeinfo and Previews”

[16] Currently, libmagic is the support library used to accomplish this.

[17] Remember that users can only inherit properties from paths for which they have read access. So if an administrator sets svn:auto-props on some high-level parent path (e.g. the repository root), they need to be sure all users have read access to that path or the desired automatic property setting won't kick in.

[18] As of this writing, symbolic links are indeed the only special objects. But there might be more in future releases of Subversion.