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 (.
).[8]
In addition to the propset command, the svn program supplies the propedit command. This command uses the configured editor program (see Config) 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.[9] 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 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 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.