Managing versioned properties in VisualSVN Server Manager

Applies to: VisualSVN Server 6.0 and later

This article describes the concept of versioned properties in Subversion. It also describes how to view or modify such properties with VisualSVN Server Manager.

What is a versioned property?

Versioned properties are arbitrary versioned metadata that users can attach to files or directories in a repository. Each property consists of a name and a value. The property name must be a text string, while the property value can contain any type of data, such as text or binary data.

Users can set custom versioned properties with any arbitrary names and values. Users can also set standard versioned properties with reserved names that have special meanings. For example, by setting the standard svn:global-ignores and svn:ignore properties you can tell Subversion clients to ignore specific files, such as build artifacts, that should not be put under version control. For details on that and for other use cases, see What are versioned properties used for?

Ways to view or change versioned properties

Changing a versioned property in a repository is always done by committing such a property change, regardless of the tool that you use for that. Such property changes are tracked and recorded in version history, alongside other changes made to versioned files and directories. This is why such properties are called versioned.

View or change with a Subversion client

End users can view or change versioned properties with a Subversion client. For example, in a working copy, users can view or set properties on a file/directory with the help of the command-line svn client (see Manipulating Properties) or with TortoiseSVN (see Subversion Properties). Committing a property change via a Subversion client requires Write access to the item to which the property is attached.

View or change with VisualSVN Server Manager

Since VisualSVN Server 6.0, it is also possible to view or change versioned properties directly in VisualSVN Server Manager. See the respective sections below.

Viewing versioned properties in VisualSVN Server Manager

To view versioned properties that apply to a particular file or directory in a repository, do the following:

1. Start the VisualSVN Server Manager console.
2. In the left-hand pane, expand the Repositories node and navigate to the file or directory of interest.
3. Right-click the file or directory in a repository and select Properties from the context menu. You can do this for any item in a repository, including the root directory of the repository.

4. Open the Metadata tab.

   The table on the Metadata tab displays all Versioned properties that apply to the file/directory for which you opened this Properties window. Versioned properties may apply to the currently viewed file/directory in two ways:

   • Inherited from <path>. These are properties that the currently viewed file/directory inherits from any of its parent directories in the file hierarchy. The <path> is the parent directory on which the property is set. See Understanding property inheritance for details.
   • Configured on <path> are properties that are set explicitly (directly) on the currently viewed file/directory.

For example, the following screenshot displays the Metadata tab for a file MyPicture.png. This file inherits 3 webviewer properties that are set on the root directory of the repository (/). And it also has a property svn:mime-type that is set explicitly on this particular MyPicture.png file.

Understanding property inheritance

A path (file or directory) can have versioned properties set on it explicitly as well as properties that it inherits from its parent directories in the hierarchy, up to the repository root. Conversely, it means that when a property is explicitly set on a directory, it is available as an inherited property to all items contained in that directory at any nesting depth. This is a convenient mechanism for making a property retrievable on every item within a particular subtree, without needing that property to be explicitly set on all items in that subtree.

Subversion clients can distinguish between a path's explicit and inherited properties. For custom properties, users decide what inherited properties mean and how to use them. For standard properties, it depends on the property, whether it will have the same meaning when explicit and when inherited.

Effect of access restrictions on property inheritance

As a repository administrator, in VisualSVN Server Manager you will see all the properties inherited by the file or directory whose Metadata tab you are viewing.

However, for a user that accesses the repository via a Subversion client, inheritance of versioned properties depends on the user's access permissions. If the user does not have Read access to a parent path on which a property is set explicitly, then the user will not receive that property via inheritance on any child paths of that inaccessible parent directory. As a result, the property will not have its expected effect on the paths within the working copy.

Keep that in mind when setting properties that you want to apply globally via inheritance to the entire repository or to a large part of the repository. For example, when setting svn:global-ignores or webviewer properties.

Adding a new versioned property

To add a new versioned property on a particular file or directory, do the following:

1. In the Properties of that file/directory, open the Metadata tab, as described in Viewing versioned properties.
2. Click Add and select one of the options:
   • Versioned property. Allows manually adding any versioned property.
   • Auto-configured webviewer properties. Allows automatically adding webviewer properties with auto-populated names and values.

3. If you chose the Versioned property option, fill in a Property name and a Property value. You can also select a Property name from the dropdown list. Click OK.

   Your pending property changes are displayed in bold in the table until you commit these changes.

4. Optionally, clicking Edit commit message below the table allows you to view or change the commit message with which the current pending property changes will be committed.
5. To commit the pending property changes, click Apply.

Editing or removing an existing versioned property

To edit or remove an existing versioned property attached to a file or directory:

1. In the Properties of that file/directory, open the Metadata tab, as described in Viewing versioned properties.
2. Select a property to modify. And then:
   • To change its value, click Edit. Edit the Property value and click OK.

   • To delete this property, click Remove.

     A property that has pending uncommitted edits is displayed in bold until you commit this change. If a removal is pending, the property is removed from the list.

     Note

     You cannot edit properties that the currently viewed file/directory inherits from a parent path. Instead, edit such properties on the parent path on which they are set.
3. Optionally, clicking Edit commit message below the table allows you to view or change the commit message with which the current pending property changes will be committed.
4. To commit the pending property changes, click Apply.

How versioned properties apply to working copies

When a versioned property is added or modified in the repository, users need to update their existing working copies to get these property changes, just as they would for receiving other changes. This also applies to properties received via inheritance.

What are versioned properties used for?

Versioned properties have a lot of uses, which can be summarized with the following categories.

Subversion's reserved properties

Subversion's reserved properties are standard properties with special meanings. Most of them (with the notable exception of svn:mergeinfo) are user-editable properties that store project-specific settings that customize the behavior of Subversion clients for the project, or for any specific paths in it.

Some of the standard properties can be set automatically by Subversion clients by default, and Subversion will rely on them for some of its functionality.

The following are just a few examples of standard properties:

• svn:ignore - when set on a directory, instructs Subversion clients to ignore certain unversioned items in that directory, based on the name or extension patterns specified in the property's value. By convention, it is applicable only to the immediate children of the directory that explicitly has this property, and has no meaning for items nested deeper. It is used to ignore unversioned files that should not be added to version control, such as temporary files created by text editors or IDEs, build artifacts, etc. See Ignoring Unversioned Items.
• svn:global-ignores - has the same general meaning as svn:ignore, but affects the directory on which it is set to the full depth, by relying on property inheritance. See Ignoring Unversioned Items.
• svn:auto-props - instructs Subversion clients to automatically add the specified versioned properties on newly added files and directories whose names match the specified pattern. It affects the directory on which it is set to the full depth, by relying on property inheritance. See Automatic Property Setting.
• svn:executable - instructs Subversion clients to automatically make the file with that explicit property executable during checkouts or exports on Unix-like operating systems. See File Executability.
• svn:mime-type - can be attached to a file to specify the file's MIME type, i.e. the format of data that the file contains. Subversion clients can set it automatically to mark non-plain-text files for which line-based merging is not possible. See File Content Type.
• svn:mergeinfo - importantly, is not intended to be edited by users. It is set and modified automatically by Subversion's merge command and is used internally for automatic merge tracking. See Mergeinfo and Previews.

For the full list of standard versioned properties, see the Versioned properties subsection in Subversion's Reserved Properties.

Third-party versioned properties

There also are versioned properties that have special meanings only for some Subversion clients:

• Webviewer properties (webviewer:revision, webviewer:pathrevision and webviewer:pathrevline) - configure integration with the repository's web interface in Subversion clients or hook scripts that support such integration. These properties are used to correctly form links to the repository web interface, such as to include links to commits in email commit notifications. See Features relying on webviewer properties.

• TortoiseSVN project properties - are a collection of properties that customize the behaviour of the TortoiseSVN client for the project where they are set. For example:

  • tsvn:logminsize - sets the minimum allowed length of the commit message.
  • tsvn:logwidthmarker - sets a vertical ruler indicating the maximum line width in the window for entering the commit message.

Custom versioned properties

Users and repository administrators are also free to come up with their own custom properties and uses for them, such as to attach arbitrary information for use in hook scripts or in other automation scripts, etc. For an example, see Why properties?

See also

Properties
KB242: Configuring Subversion properties for integration with a web interface