Section 6.2. Retrieving Metadata

6.2. Retrieving Metadata

Properties are retrieved via the svn propget command, which gets a keyed property from a file or directory and outputs it. The command takes a property key, and a file to retrieve the property from (which can either be a file in a working copy or a repository URL). It outputs the property's value, as in the following example.

 $ svn propget ownership.author hello_world.c William Nagel 

Subversion also allows you to pass multiple files to svn propget, in which case it will output the supplied property for each of the given files. To make it easier to differentiate the property values for the multiple files, Subversion will also prepend the name of each file in front of each value.

 $ svn propget author *.txt Cathedral_and_Bazaar.txt - Eric S. Raymond GPL.txt - Richard M. Stallman 

When outputting a property value, Subversion adds a newline at the end of the property in order to prettify the output a bit. That and svn propget's filename prepending on multiple files, however, is undesirable behavior when the property is a binary file that you want to output. In those cases, you can use the --strict option to turn off both additions. With strict output, the svn propget output is suitable for redirecting into a file.

 $ svn propget --strict advertising.poster MyFlick.mov > poster.jpg 

6.2.1. Listing Properties

To retrieve property values, it's sometimes necessary to first check to see what properties are available. With Subversion, you can list available properties using the svn proplist command. When you run svn proplist, the command will take a list of versioned files and/or directories and output all of the properties that are set for them.

 $ svn proplist svc.tex Properties on 'svc.tex':   copyright.author   copyright.date   copyright.publisher 

If you would also like to get the values of all properties associated with a file, you can run svn proplist in verbose mode with --verbose (-v). To save you from accidentally dumping the entire contents of a binary file to standard out, svn proplist will not output a binary property value. Instead, it will output ???? to let you know that the value is nonASCII.

 $ svn proplist --verbose svc.tex Properties on 'svc.tex':   copyright.author : William Nagel   copyright.publisher : Prentice Hall   img.cover : ???? 

The default svn proplist behavior is to work non-recursively. If you would like to see the properties that are set on all of the files inside a directory though, you can turn on recursive listing with the --recursive (-R) option.

 $ svn proplist --recursive trunk/book Properties on 'trunk/book/svc.tex':   copyright.author   copyright.date   img.cover Properties on 'trunk/book/chapter1.tex':   copyright.author   copyright.date 

Sometimes, you need to get the values of several properties from a collection of files. Although Subversion has no built in mechanism for finding such information directly, you can easily get the information you want by using the grep command to filter svn proplist's output. For example, say you have a directory full of image files, each with copyright information attached as a set of properties with names starting copyright. If you would like to output all of the copyright information on all of those files, you could run a command similar to the following.

[View full width]
 $ svn proplist --recursive --verbose trunk/images | grep -E '^ Properties on|^ copyright' >  copyrights.txt 

6.2.2. Outputting Multiple Binary Properties

Occasionally, you will need to retrieve the contents of multiple binary properties and put them into distinct files. If there are only a couple of files, it's easy enough to just run multiple svn propget's, and redirect them into their own files. On the other hand, if the number of files is large, individually retrieving them can be impractical. However, by using a looping construct, such as the for loop in the Bourne Again Shell (BASH), you can easily get multiple files. As an example, the following command will take a list of C files and output the Python testing scripts that are embedded in each file as a property named test.script.

 $ for FILE in *.c; > do svn propget test.script $FILE > ${$FILE/%.c/-test.py}; > done $ ls bar.c  bar-test.py  foo.c  foo-test.py 

In this example, the for FILE in *.c; tells BASH that it should loop through every file that ends in a .c and place its name in the variable FILE. It will then run the svn propget command for that file and redirect the output into a file that has the same base name as the file containing the property, but with the .c suffix replaced by -test.py. As you can see, after the command has run, both of the C files have had a test script extracted.

6.2.3. Getting Revision Properties

Revision properties are retrieved in pretty much the same manner as regular versioned properties. The only difference is that you must explicitly refer to a revision when getting a revision property, using the --revision (-r) option. As with the property setting commands, you also need to tell Subversion that you are referring to a revision property by using the --revprop option, like in the following example.

 $ svn propget --revprop --revision 4356 svn:log