1. Revision Specifiers
Revision numbers in Subversion are pretty straightforward—integers that keep getting larger as you commit more changes to
your versioned data. Besides the integer revision numbers, svn allows as input some additional forms of revision specifiers: revision keywords and revision dates.
- HEAD
The latest (or “youngest”) revision in the repository. - BASE
The revision number of an item in a working copy. If the item has been locally modified, this refers to the way the item appears without those local modifications. - COMMITTED
The most recent revision prior to, or equal to, BASE, in which an item changed. - PREV
The revision immediately before the last revision in which an item changed.
Here are some examples of revision keywords in action:$ svn diff -r PREV:COMMITTED foo.c
# shows the last change committed to foo.c
$ svn log -r HEAD
# shows log message for the latest repository commit
$ svn diff -r HEAD
# compares your working copy (with all of its local changes) to the
# latest version of that tree in the repository
$ svn diff -r BASE:HEAD foo.c
# compares the unmodified version of foo.c with the latest version of
# foo.c in the repository
$ svn log -r BASE:HEAD
# shows all commit logs for the current versioned directory since you
# last updated
$ svn update -r PREV foo.c
# rewinds the last change on foo.c, decreasing foo.c's working revision
$ svn diff -r BASE:14 foo.c
# compares the unmodified version of foo.c with the way foo.c looked
# in revision 14
2. Ignoring Unversioned Items
In any given working copy, there is a good chance that alongside all those versioned files and directories are other files and directories that are neither versioned nor intended to be.
So Subversion provides two ways for telling it which files you would prefer that it simply disregard. One of the ways involves the use of Subversion’s runtime configuration system(see the section called “Runtime Configuration Area”), and therefore applies to all the Subversion operations that make use of that runtime configuration—generally those performed on a particular computer or by a particular user of a computer. The other way makes use of Subversion’s directory property support and is more tightly bound to the versioned tree itself, and therefore affects everyone who has a working copy of that tree. Both of the mechanisms use file patterns (strings of literal and special wildcard characters used to match against filenames) to decide which files to ignore.
The Subversion runtime configuration system provides an option, global-ignores, whose value is a whitespace-delimited collection of file patterns.When found on a versioned directory, the svn:ignore property is expected to contain a list of newline-delimited file patterns that Subversion should use to determine ignorable objects in that same directory. These patterns do not override those found in the global-ignores runtime configuration option, but are instead appended to that list. And it’s worth noting again that, unlike the global-ignores option, the patterns found in the svn:ignore property apply only to the directory on which that property is set, and not to any of its subdirectories.
Say you have the following output from svn status:$ svn status calc
M calc/button.c
? calc/calculator
? calc/data.c
? calc/debug_log
? calc/debug_log.1
? calc/debug_log.2.gz
? calc/debug_log.3.gz
In this example, you have made some property modifications to button.c, but in your working copy, you also have some unversioned files. And you know that you aren’t interested in seeing those log files every time you run svn status. So you use svn propedit svn:ignore calc to add some ignore patterns to the calc directory. For example, you might add this as the new value of the svn:ignore property:calculator
debug_log*
After you’ve added this property, you will now have a local property modification on the calc directory. But notice what else is different about your svn status output:$ svn status
M calc
M calc/button.c
? calc/data.c
3. Sparse Directories
By default, most Subversion operations on directories act in a recursive manner. Subversion introduces a feature called sparse dir-
ectories (or shallow checkouts) that allows you to easily check out a working copy—or a portion of a working copy—more shallowly than full recursion, with the freedom to bring in previously ignored files and subdirectories at a later time. Here are the depth values that you can request for a given Subversion operation:
- —depth empty
Include only the immediate target of the operation, not any of its file or directory children. - —depth files
Include the immediate target of the operation and any of its immediate file children. - —depth immediates
Include the immediate target of the operation and any of its immediate file or directory children. The directory children will themselves be empty. - —depth infinity
Include the immediate target, its file and directory children, its children’s children, and so on to full recursion.
4. Properties
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. And the best part about these properties is that they, too, are versioned, just like the textual contents of your files. Subversion has reserved the set of properties whose names begin with svn: as its own. You should avoid creating custom properties for your own needs whose names begin with this prefix.
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 main difference is that revision properties are not versioned.
- svn propset
$ svn propset copyright '(c) 2006 Red-Bean Software' calc/button.c |
In addition to the propset command, the svn program supplies the propedit command. This command uses the configured editor program to add or modify properties.$ 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'
The svn proplist command will list the names of properties that exist on a path. Once you know the names of the prop-
erties on the node, you can request their values individually using svn propget.$ svn proplist calc/button.c
Properties on 'calc/button.c':
copyright
license
$ svn propget copyright calc/button.c
(c) 2006 Red-Bean Software
The last property-related subcommand is propdel.$ svn propdel license calc/button.c
property 'license' deleted from 'calc/button.c'.
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. 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'