Section 11.3. Taking Advantage of Metadata

11.3. Taking Advantage of Metadata

Subversion provides a wealth of metadata about version files, which can be leveraged when writing scripts to automate things in Subversion, both on the client and server side. By knowing what information is available, and how to effectively get at it, you will greatly increase your ability to write scripts that will help to automate Subversion's integration into your software development process.

11.3.1. The Subversion Commands

There are two Subversion programs that you will commonly use when accessing a Subversion repository from your scripts, svn and svnlook. The choice generally depends on whether you are running server side or client side. In a client-side script, you must use svn, because svnlook requires direct access to the actual repository, rather than access through svnserve or Apache. On the server side, though, you are often better off using svnlook because it makes a lot of metadata easier to retrieve, and protects you from accidentally modifying a repository in a hook scripts (where such modifications should not occur but are allowed by the system).

svn

The details of using svn are described in detail in Chapter 5, "Working with a Working Copy," so I won't repeat them here. I will, however, briefly review the commands that are useful for examining repository metadata, as well as the specific metadata that you'll be able to retrieve using each of the commands.

svn blame Allows you to retrieve the author responsible for each line in a file, as well as the revision where that line was last modified. In most cases, this is a useful command when run by itself, to provide information to a developer. The author/revision metadata can be useful though, and you may find instances where this is a useful command to use in an automated script.

svn info Provides a variety of pieces of metadata information about an individual versioned file or directory in a working copy (svn info won't work with a URL). Much of this information is useful for automation, and can be easily retrieved from svn info's output. The individual entries that can be retrieved are

• Path (directory, file). This is the path, relative to the base of the repository, where the file or directory is found.

• Name (file). This is the name of the file by itself, without preceding path information.

• URL (directory, file). This is the URL to the file or directory in the repository.

• Repository UUID (directory, file). This is a unique identifier, which identifies which repository the file came from, regardless of URL. It allows the Subversion client to identify a unique repository, regardless of whether the URL is of the form svn://, http://, or something else entirely.

• Revision (directory, file). This is the current revision of the given file in the working copy.

• Node Kind (directory, file). This identifies whether the item being examined is a file or a directory.

• Schedule (directory, file). This is used to identify files that are scheduled for addition or deletion from the repository.

• Last Changed Author (directory, file). This is the last user to make a change to the file or directory.

• Last Changed Rev (directory, file). This is the last revision in which the directory or file was modified.

• Last Changed Date (directory, file). This is the date and time of the last modification to the file or directory.

• Text Last Updated (file). This is the date of the last time the svn update command changed the file's text in the working copy.

• Properties Last Updated (file). This is the date of the last time the svn update command changed a property of the file in the working copy.

• Checksum (file). This is a checksum of the file checked out into the working copy. It can be used to make sure that the correct file was downloaded, or to see if the local file has been modified.

svn log You can use this command to retrieve the log history of a file or directory. This is most useful in automated scripts if the log files are structured, so that a script can parse them for useful information. For instance, you might have developers enter the issue tracker ticket number for a commit in a predictable manner, such that an automated script would be able to read through the logs and find all of the revisions that applied to a particular issue.

svn status This command is useful for finding the current state of a repository or working copy. It outputs status in a very strict, easily parsed format, making retrieval of specific items of information fast and trivial.

In addition to these metadata retrieval commands, you can also get information about custom metadata (i.e., properties) using the svn property commands.

svn propget With this command, you can get the individual values of individual properties from a file or directory. The usefulness of any individual property in automation can vary wildly, but well-chosen properties can be extremely useful. On the client side, scripts that validate the state of all project-required properties can be a useful tool for developers, allowing them to see if a commit will be allowed before actually attempting it (which should also give the developer more useful error output if the file doesn't pass).

svn proplist This command allows you to see all of the properties set on a particular file or directory, which can be useful in a client-side automated script to verify the existence of certain properties, and act accordingly. For example, a script could retrieve all of the properties available and process the file based on which properties are there. If there are a lot of optional properties, this is almost certainly faster than testing each property for existence individually.

svnlook

The svnlook command is easily one of the more useful tools available to you when writing scripts that will run on the server, with local access to the repository. It provides you with the ability to inspect a variety of aspects of the repository, including transactions that have not yet been fully committed to the repository. Some of its commands mirror those available in svn (albeit with slightly different inputs and outputs), but many provide information that is difficult to get using the client (or in a form better suited to using with a script).

The svn mirrored commands cover the query commands that don't affect the repository itself in any way. For the most part, they work similar to their equivalent commands in svn, with the addition of a --TRansaction (or -t) argument that allows you to inspect a transaction instead of a revision, given the transaction number. The transaction number is supplied as an argument to the pre-commit and pre-revprop-change hook scripts, or can be found by running svnadmin lstxns. Additionally, the svnlook commands take the local path to the repository, instead of a URL, and won't work with a working copy.

svnlook cat This command works exactly the same as the svn version. It takes a repository and the path to a file in the repository and outputs that file's contents.

 $ svnlook cat --revision 1492 /var/svnrepos /repos/trunk/groceries.txt One Gallon Milk A Dozen Eggs Steak Apples Hamburgers Bread 

svnlook diff This diff command is similar to the svn diff command, but with fewer options. Unlike the svn diff command, svnlook diff is only meant to show the differences that were applied to a repository in a given revision, rather than giving the differences between two arbitrary versions. Therefore, the following example would output all of the changes that were applied in revision 1972, using the GNU diff format. Changes are shown across all files that were changed in that revision. There is no way to specify individual files.

 $ svnlook diff --revision 1972 /var/svnrepos Modified: trunk/ParseTree.h ================================================================== --- trunk/ParseTree.h     2004-09-28 05:15:43 UTC (rev 1971) +++ trunk/ParseTree.h     2004-09-28 05:52:14 UTC (rev 1972) @@ -2,33 +2,51 @@ #define PARSE_TREE_H #include "ParsedElem.h" +#include "UnparsedElem.h" #include <string> #include <list> 

svnlook info Instead of giving information about a particular file, this command gives information about a particular revision in the repository. Specifically, it gives the user who committed the revision, the date of the revision, the revision number, and the log entry for that revision.

 $ svnlook info --revision 1000 /var/svnrepos bill 2004-05-11 14:30:43 -0500 (Tue, 11 May 2004) 27 Added ready status output. 

svnlook log The svnlook log command is identical to the svn log command, except it only gives a single log entry for a specific revision or transaction.

 $ svnlook log --transaction 34 /var/svnrepos Implemented a logging algorithm. 

svnlook propget This command gives exactly the same output as the svn propget command. You just need to feed it a repository, a property name, and a path to a file in the repository.

 $ svnlook propget --revision 356 /var/svnrepos svn:ignore /trunk/src *.o *.so *.a 

svnlook proplist Similarly, the proplist command works identically to the svn proplist command, and lists all of the properties associated with a file, at the supplied revision.

 $ svnlook proplist --revision 558 /var/svnrepos /trunk/src svn:ignore svn:keywords 

If you would like, you can also see the values of each property by passing the --verbose (or -v) parameter.

In addition to the commands that more or less mirror commands from svn, svnlook provides a number of commands that are not available in the Subversion client, but which can be very useful when writing hook scripts, and other server-side automation tools.

svnlook author This command prints the username of the person who committed the designated revision or transaction.

 $ svnlook author --revision 17834 /var/svnrepos dwnorth 

svnlook changed With this command, you are able to see exactly which files have been changed for a particular revision, in a manner similar to the output of svn status. Each file that was modified in that revision is shown, with its full path relative to the root of the repository, preceded by two columns of output that tell what has changed in the file.

 $ svnlook changed --revision 238 /var/svnrepos U   trunk/etc/csh.login A   trunk/etc/httpd.conf D   trunk/etc/profile.env _U  trunk/etc/passwd 

The first column shows changes that have been made to the contents of the file.

U: The file's contents were modified.

A: The file was added to the repository.

D: The file was removed.

Additionally, the second column indicates files that have had a property modified, with a U.

svnlook date The date command outputs the date that a revision was created.

 $ svnlook date /var/svnrepos 2004-09-29 18:33:13 -0500 (Wed, 29 Sep 2004) 

svnlook dirs-changed This command outputs all of the directories that were changed in a given revision or transaction. Changed directories include directories that had a property modified or directories that contain files which were modified. Directories that had a subdirectory added or removed are also shown.

 $ svnlook dirs-changed --transaction 19 /var/svnrepos trunk/ branches/release_1_0_1 

svnlook history This command allows you to examine the path that a file has taken, through copies and moves. When you run svnlook history with the path to a file or directory in your repository, it outputs the revision history of that file, showing every revision where that file or directory was modified, along with the path to the file at that revision.

 $ svnlook history /var/svnrepos /tags/release_1_0 REVISION   PATH --------   ----     5630   /tags/release_1_0     5407   /branches/release_candidate     5304   /branches/release_candidate     5207   /branches/release_candidate     5206   /trunk     5205   /trunk      ...      3     /trunk      2     /trunk      1     /trunk 

If you give svnlook history an explicit revision (using --revision, or -r), it only outputs the history of the given file up to that point.

 $ svnlook history --revision 4 /var/svnrepos /tags/release_1_0 REVISION   PATH --------   ----        4   /trunk        3   /trunk        2   /trunk        1   /trunk 

svnlook tree You can examine the hierarchy of files in your repository by using the svnlook tree command. If you run the command with no path argument, it shows the entire tree of files in your repository at the supplied revision. If, instead, you provide the command with a path into the repository, it shows that directory and all files/subdirectories contained within.

 $ svnlook tree /var/svnrepos /branches/release_1_0 release_1_0/  hello_world/   hello_world.c   Makefile  docs/   README.txt 

svnlook uuid Each repository has a unique ID that allows it to be identified independent of the URL used to access it. You can output this ID by running svnlook uuid.

 $ svnlook uuid /var/svnrepos 8ebba8bb-42e5-0310-8fa5-bfaad3eac2b1 

svnlook youngest You can find the most recently committed revision of a repository by running this command. It has no options, and just takes the path to a repository. Because its output is simply the revision number, it is especially useful in scripts.

 $ svnlook youngest /var/svnrepos 2592