By default, most Subversion operations on directories act in a recursive manner. For example, svn checkout creates a working copy with every file and directory in the specified area of the repository, descending recursively through the repository tree until the entire structure is copied to your local disk. Subversion 1.5 introduces a feature called sparse directories (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.
For example, say we have a repository with a tree of files and directories with names of the members of a human family with pets. (It's an odd example, to be sure, but bear with us.) A regular svn checkout operation will give us a working copy of the whole tree:
$ svn checkout file:///var/svn/repos mom A mom/son A mom/son/grandson A mom/daughter A mom/daughter/granddaughter1 A mom/daughter/granddaughter1/bunny1.txt A mom/daughter/granddaughter1/bunny2.txt A mom/daughter/granddaughter2 A mom/daughter/fishie.txt A mom/kitty1.txt A mom/doggie1.txt Checked out revision 1. $
Now, let's check out the same tree again, but this time, we'll ask Subversion to give us only the top-most directory with none of its children at all:
$ svn checkout file:///var/svn/repos mom-empty --depth empty Checked out revision 1 $
Notice that we added to our original svn
checkout command line a new
option. This option is present on many of Subversion's
subcommands and is similar to the
-R) options. In
fact, it combines, improves upon, supercedes, and ultimately
obsoletes these two older options. For starters, it expands the
supported degrees of depth specification available to users,
adding some previously unsupported (or inconsistently supported)
depths. Here are the depth values that you can request for a
given Subversion operation:
Include only the immediate target of the operation, not any of its file or directory children.
Include the immediate target of the operation and any of its immediate file children.
Include the immediate target of the operation and any of its immediate file or directory children. The directory children will themselves be empty.
Include the immediate target, its file and directory children, its children's children, and so on to full recursion.
Of course, merely combining two existing options into one hardly constitutes a new feature worthy of a whole section in our book. Fortunately, there is more to this story. This idea of depth extends not just to the operations you perform with your Subversion client, but also as a description of a working copy citizen's ambient depth, which is the depth persistently recorded by the working copy for that item. Its key strength is this very persistence—the fact that it is sticky. The working copy remembers the depth you've selected for each item in it until you later change that depth selection; by default, Subversion commands operate on the working copy citizens present, regardless of their selected depth settings.
You can check the recorded ambient depth of a working copy using the svn info command. If the ambient depth is anything other than infinite recursion, svn info will display a line describing that depth value:
$ svn info mom-immediates | grep '^Depth:' Depth: immediates $
Our previous examples demonstrated checkouts of infinite depth (the default for svn checkout) and empty depth. Let's look now at examples of the other depth values:
$ svn checkout file:///var/svn/repos mom-files --depth files A mom-files/kitty1.txt A mom-files/doggie1.txt Checked out revision 1. $ svn checkout file:///var/svn/repos mom-immediates --depth immediates A mom-immediates/son A mom-immediates/daughter A mom-immediates/kitty1.txt A mom-immediates/doggie1.txt Checked out revision 1. $
As described, each of these depths is something more than only-the-target, but something less than full recursion.
We've used svn checkout as an example
here, but you'll find the
present on many other Subversion commands, too. In those other
commands, depth specification is a way to limit the scope of an
operation to some depth, much like the way the older
behave. This means that when operating on a working copy of
some depth, while requesting an operation of a shallower depth,
the operation is limited to that shallower depth. In fact, we
can make an even more general statement: given a working copy of
any arbitrary—even mixed—ambient depth, and a
Subversion command with some requested operational depth, the
command will maintain the ambient depth of the working copy
members while still limiting the scope of the operation to the
requested (or default) operational depth.
In addition to the
--depth option, the
svn update and svn switch
subcommands also accept a second depth-related option:
--set-depth. It is with this option that you
can change the sticky depth of a working copy item. Watch what
happens as we take our empty-depth checkout and gradually
telescope it deeper using svn update
$ svn update --set-depth files mom-empty A mom-empty/kittie1.txt A mom-empty/doggie1.txt Updated to revision 1. $ svn update --set-depth immediates mom-empty A mom-empty/son A mom-empty/daughter Updated to revision 1. $ svn update --set-depth infinity mom-empty A mom-empty/son/grandson A mom-empty/daughter/granddaughter1 A mom-empty/daughter/granddaughter1/bunny1.txt A mom-empty/daughter/granddaughter1/bunny2.txt A mom-empty/daughter/granddaughter2 A mom-empty/daughter/fishie1.txt Updated to revision 1. $
As we gradually increased our depth selection, the repository gave us more pieces of our tree.
In our example, we operated only on the root of our working copy, changing its ambient depth value. But we can independently change the ambient depth value of any subdirectory inside the working copy, too. Careful use of this ability allows us to flesh out only certain portions of the working copy tree, leaving other portions absent altogether (hence the “sparse” bit of the feature's name). Here's an example of how we might build out a portion of one branch of our family's tree, enable full recursion on another branch, and keep still other pieces pruned (absent from disk).
$ rm -rf mom-empty $ svn checkout file:///var/svn/repos mom-empty --depth empty Checked out revision 1. $ svn update --set-depth empty mom-empty/son A mom-empty/son Updated to revision 1. $ svn update --set-depth empty mom-empty/daughter A mom-empty/daughter Updated to revision 1. $ svn update --set-depth infinity mom-empty/daughter/granddaughter1 A mom-empty/daughter/granddaughter1 A mom-empty/daughter/granddaughter1/bunny1.txt A mom-empty/daughter/granddaughter1/bunny2.txt Updated to revision 1. $
Fortunately, having a complex collection of ambient depths
in a single working copy doesn't complicate the way you interact
with that working copy. You can still make, revert, display,
and commit local modifications in your working copy without
providing any new options (including
--set-depth) to the relevant subcommands. Even
svn update works as it does elsewhere when no
specific depth is provided—it updates the working copy
targets that are present while honoring their sticky
You might at this point be wondering, “So what? When
would I use this?” One scenario where this feature
finds utility is tied to a particular repository layout,
specifically where you have many related or codependent
projects or software modules living as siblings in a single
repository location (
trunk/project3, and so on). In such
scenarios, it might be the case that you personally care only
about a handful of those projects—maybe some primary
project and a few other modules on which it depends. You can
check out individual working copies of all of these things, but
those working copies are disjoint and, as a result, it can be
cumbersome to perform operations across several or all of them
at the same time. The alternative is to use the sparse
directories feature, building out a single working copy that
contains only the modules you care about. You'd start with an
empty-depth checkout of the common parent directory of the
projects, and then update with infinite depth only the items you
wish to have, like we demonstrated in the previous example.
Think of it like an opt-in system for working copy
Subversion 1.5's implementation of shallow checkouts is good but does not support a couple of interesting behaviors. First, you cannot de-telescope a working copy item. Running svn update --set-depth empty on an infinite-depth working copy will not have the effect of discarding everything but the top-most directory—it will simply error out. Secondly, there is no depth value to indicate that you wish an item to be explicitly excluded. You have to do implicit exclusion of an item by including everything else.