![[S] Subversion](/images/svn-name-banner.svg)
This article is mirrored with permission from the original location http://blogs.collab.net/subversion/the-road-to-repository-dictated-configuration-day-2-autoprops. Inactive links have been removed or updated.
Author: Paul Burba
Posted: 2013-06-25
In part 1 I talked about the new inheritable properties feature in Subversion 1.8. I promised that this feature would pave the way for repository dictated configuration (RDC). Today I’ll show you the first part of 1.8′s RDC related features, the new svn:auto-props property.
Subversion provides an extensive set of user configurable options which control various aspects of a Subversion client’s operations. For repositories with only a small handful of committers in the same location, manually synchronizing these configurations is probably not too difficult. For larger and/or distributed groups however, ensuring that everyone has the same configuration becomes increasingly cumbersome. Subversion provides a mechanism to enforce some of this configuration via hook scripts. Hook scripts however, by their very nature, provide only after-the-fact enforcement — a hook script can deny a commit to an improperly configured user, but it won’t correct the user’s configuration.
A better solution are repository dictated 1 configurations that seamlessly supplement the client’s configuration with repository-wide settings that apply to operations directly on the repository and indirectly via the repository’s working copies. One of the most commonly requested features in this realm is for repository dictated values for automatic property setting, which Subversion 1.8 provides with the new reserved svn:auto-props property.
This is a high level refresher, for more detail see the Version Control with Subversion book.
In Subversion 1.7 when you add a file to version control with the svn add or svn import subcommands, Subversion attempts to set common properties on that file automatically. Some of these properties (e.g. svn:executable, svn:mime-type) are set regardless of configuration, while others (e.g. svn:eol-style) 2 depend on the particulars of your individual run-time configuration. These configurations can be overridden at the command line with the –config-option and –config-dir options.
The configuration section of interest to us today is auto-props. In this section you can define properties which automatically get set on added/imported files. For example, say we have this configuration 3:
### Set enable-auto-props to 'yes' to enable automatic properties ### for 'svn add' and 'svn import', it defaults to 'no'. ### Automatic properties are defined in the section 'auto-props'. enable-auto-props = yes ### Section for configuring automatic properties. [auto-props] ### The format of the entries is: ### file-name-pattern = propname[=value][;propname[=value]...] ### The file-name-pattern can contain wildcards (such as '*' and ### '?'). All entries which match (case-insensitively) will be ### applied to the file. Note that auto-props functionality ### must be enabled, which is typically done by setting the ### 'enable-auto-props' option. *.c = svn:eol-style=native *.cpp = svn:eol-style=native *.h = svn:keywords=Author Date Id Rev URL;svn:eol-style=native *.dsp = svn:eol-style=CRLF *.dsw = svn:eol-style=CRLF *.sh = svn:eol-style=native;svn:executable *.txt = svn:eol-style=native;svn:keywords=Author Date Id Rev URL; *.png = svn:mime-type=image/png *.jpg = svn:mime-type=image/jpeg Makefile = svn:eol-style=native
Given the above configuration, when we place a file with the .c extension under version control, the file will automatically have the svn:eol-style property set on it with a value of native:
1.8.0>svn st ? src\panel.c 1.8.0>svn add src\panel.c A src\panel.c 1.8.0>svn proplist src\panel.c --verbose Properties on 'src\panel.c': svn:eol-style native
Nice, but if we are a repository administrator, we must rely on all of our users manually setting up their configuration this way 4. It would be better if there was a way to push the desired auto-prop definitions for a repository (or a project within a repository) to the users 5…
…Enter the new svn:auto-props property. The value of this new property should have the same format as the auto-props runtime configuration option: Any number of newline separated key-value pairs in the format FILE_PATTERN = PROPNAME=VALUE[;PROPNAME=VALUE ...]).
We might have the svn:auto-props property set on the root of our repository with a value very much like that in our runtime configuration from previous example:
1.8.0>svn pg svn:auto-props http://svn.example.com/repos --verbose Properties on 'http://svn.example.com/repos': svn:auto-props *.c = svn:eol-style=native *.cpp = svn:eol-style=native *.h = svn:keywords=Author Date Id Rev URL;svn:eol-style=native *.dsp = svn:eol-style=CRLF *.dsw = svn:eol-style=CRLF *.sh = svn:eol-style=native;svn:executable *.txt = svn:eol-style=native;svn:keywords=Author Date Id Rev URL; *.png = svn:mime-type=image/png *.jpg = svn:mime-type=image/jpeg Makefile = svn:eol-style=native
The value of the svn:auto-props property defines automatic properties for any path added or imported to a directory location which inherits the property.
Lets look at a very simple example of how the new property works to set automatic properties. Lets assume we have no auto-props defined in our runtime configuration:
### Set enable-auto-props to 'yes' to enable automatic properties ### for 'svn add' and 'svn import', it defaults to 'no'. ### Automatic properties are defined in the section 'auto-props'. enable-auto-props = no
Further, lets assume our repository administrator previously set the svn:auto-props property on the root of the repository 6:
1.8.0>svn propget svn:auto-props --verbose -R http://svn.example.com/repos Properties on 'http://svn.example.com/repos': svn:auto-props *.c = svn:eol-style=native *.h = svn:eol-style=native *.py = svn:eol-style=native
We checkout a new working copy for our current project:
1.8.0>svn co http://svn.example.com/repos/calc/trunk calc-trunk-wc A calc-trunk-wc\doc A calc-trunk-wc\src A calc-trunk-wc\doc\INSTALL A calc-trunk-wc\FAQ A calc-trunk-wc\src\button.c A calc-trunk-wc\src\integer.c A calc-trunk-wc\src\real.c A calc-trunk-wc\src\main.c A calc-trunk-wc\Makefile A calc-trunk-wc\README U calc-trunk-wc Checked out revision 480.
After doing some work, we have a new file we want to put under version control:
1.8.0>svn st calc-trunk-wc ? calc-trunk-wc\src\bindings.h 1.8.0>svn add calc-trunk-wc\src\bindings.h A calc-trunk-wc\src\bindings.h
When we do that, sure enough, the svn:auto-props property, inherited from the root of the repository, results in an automatically set svn_eol-style property on the added file:
1.8.0>svn pg svn:auto-props -v --show-inherited-props calc-trunk-wc\src\bindings.h Inherited properties on 'calc-trunk-wc\src\bindings.h', from 'http://svn.example.com/repos': svn:auto-props *.c = svn:eol-style=native *.h = svn:eol-style=native *.py = svn:eol-style=native 1.8.0>svn pl -v calc-trunk-wc\src\bindings.h Properties on 'calc-trunk-wc\src\bindings.h': svn:eol-style native
The previous example is probably the simplest case involving svn:auto-props that you will encounter. But what happens if:
foo/bar.bat and foo inherits multiple svn:autoprops from different parents and those properties have different values for the same file pattern?--config-options or --config-dir options?In those cases the following rules apply:
A) svn:auto-props override the runtime configuration’s auto-props: An automatic property, for a given pattern, defined in svn:auto-props overrides the same auto-prop for the identical pattern in the auto-props runtime configuration 7.
B) Nearer svn:auto-props take precedence: If an automatic property, for the same pattern, is inherited from more than one parents’ svn:auto-props property, the nearer path-wise parent overrides the more distant parents.
C) Explicit svn:auto-props take precedence over those that are inherited: An automatic property, 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.
D) No guarantees if a file matches multiple patterns: Like the auto-props runtime configuration option, if a file matches more than one file pattern which defines a value for the same property, then there is no guarantee which pattern’s value will be automatically applied. For example, if and added file foo.py inherits both these values,
*.py = svn:eol-style=native *.p* = svn:eol-style=CRLF
then there is no guarantee which eol-style will be set on the added file foo.py.
E) --no-auto-props means NO automatic properties: Like the auto-props runtime option, svn:auto-props property is disregarded when using the --no-auto-props option on the command line.
F) Disabling automatic properties in the runtime configuration doesn’t affect RDC: svn:auto-props is not disabled when the enable-auto-props runtime configuration option is set to no.
<pre>### Set enable-auto-props to 'yes' to enable automatic properties ### for 'svn add' and 'svn import', it defaults to 'no'. ### Automatic properties are defined in the section 'auto-props'. ### Note: Setting this option to 'no' has no effect on the behavior of ### the svn:auto-props property enable-auto-props = no</pre><
Remember, svn:auto-props is inheritable. So typically you will only need to set the property on the root of the repository. If your repository has several different projects that require different configurations, then you can put the property on the root folder of each project 8. Remember, less is more when it comes to inherited properties — If you are setting svn:auto-props such that a given repository path inherits the same values from multiple parents, then you are probably doing more than you need to.
Full disclosure: The repository “dictated” configurations discussed here are truly only suggestions to well-behaved 1.8+ clients. Older clients will obviously not understand the new dictates. Even with newer clients it is relatively easy for a user to modify a client to ignore server-side suggestions — Subversion is open source after all! Given this reality, server-side enforcement of desired behaviors via hook scripts is still recommended if you need 100% guaranteed compliance. ↩
svn:mime-type actually falls into both these categories — it can be set via the run-time configuration, but if nothing is defined there, then Subversion will attempt to automatically set the mime type via a set of hard-coded rules. ↩
I confess to a simplification here — there isn’t just a single user configuration, it can be defined in up to 4 locations:
Lower numbered configurations take precedence over higher numbered ones. In this blog’s examples, for the purposes of simplicity, we’ll assume configs #2 through #4 are empty and our entire configuration is defined in #1 only. ↩
Subversion sets no auto-props in its default configuration ↩
i.e. Repository Dictated Configuration! ↩
Note that the svn:auto-props property can only be set on directories. ↩
Either the standard runtime configuration or that pointed to by the --config-dir option. ↩
Recall from part 1 that all users must have read access to whatever directory you set svn:auto-props on, otherwise they won’t be able to inherit from that path. ↩
Paul Burba is a committer on the Apache Software Foundation's Subversion project and has worked on Subversion for the past nine years. He works as a software engineer for Collabnet from his home in New Hampshire and when not coding he can usually be found skiing with his nephews, mountain biking with friends, or traveling with his wife. Some time in the distant past Paul graduated from the University of New Hampshire with a degree in Business. Somewhat more recently he obtained a masters in computer science from Boston University.