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