<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Sparse Directories</title>
<link rel="stylesheet" type="text/css" href="styles.css" />
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1" />
<style type="text/css">
body { background-image: url('images/draft.png');
background-repeat: no-repeat;
background-position: top left;
/* The following properties make the watermark "fixed" on the page. */
/* I think that's just a bit too distracting for the reader... */
/* background-attachment: fixed; */
/* background-position: center center; */
}</style>
<link rel="home" href="index.html" title="Version Control with Subversion [DRAFT]" />
<link rel="up" href="svn.advanced.html" title="Chapter 3. Advanced Topics" />
<link rel="prev" href="svn.advanced.props.special.keywords.html" title="Keyword Substitution" />
<link rel="next" href="svn.advanced.locking.html" title="Locking" />
</head>
<body>
<div xmlns="" id="vcws-version-notice">
<p>This text is a work in progress—highly subject to
change—and may not accurately describe any released
version of the Apache™ Subversion® software.
Bookmarking or otherwise referring others to this page is
probably not such a smart idea. Please visit
<a href="http://www.svnbook.com/">http://www.svnbook.com/</a>
for stable versions of this book.</p>
</div>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Sparse Directories</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="svn.advanced.props.special.keywords.html">Prev</a> </td>
<th width="60%" align="center">Chapter 3. Advanced Topics</th>
<td width="20%" align="right"> <a accesskey="n" href="svn.advanced.locking.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="sect1" title="Sparse Directories">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="svn.advanced.sparsedirs"></a>Sparse Directories</h2>
</div>
</div>
</div>
<p>
<a id="idp10009920" class="indexterm"></a>
<a id="idp10010992" class="indexterm"></a>By default, most Subversion operations on
directories act in a recursive manner. For
example, <span class="command"><strong>svn checkout</strong></span> 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 <em class="firstterm">sparse
directories</em> (or <em class="firstterm">shallow
checkouts</em>) 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.</p>
<p>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 <span class="command"><strong>svn checkout</strong></span> operation will give us a
working copy of the whole tree:</p>
<div class="informalexample">
<pre class="screen">
$ 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.
$
</pre>
</div>
<p>Now, let's check out the same tree again, but this time
we'll ask Subversion to give us only the topmost directory
with none of its children at all:</p>
<div class="informalexample">
<pre class="screen">
$ svn checkout file:///var/svn/repos mom-empty --depth empty
Checked out revision 1
$
</pre>
</div>
<p>Notice that we added to our original <span class="command"><strong>svn
checkout</strong></span> command line a new <code class="option">--depth</code>
option. This option is present on many of Subversion's
subcommands and is similar to the
<code class="option">--non-recursive</code> (<code class="option">-N</code>) and
<code class="option">--recursive</code> (<code class="option">-R</code>) 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:</p>
<div class="variablelist">
<a id="idp10023808" class="indexterm"></a>
<a id="idp10025296" class="indexterm"></a>
<a id="idp10026784" class="indexterm"></a>
<a id="idp10028272" class="indexterm"></a>
<dl>
<dt>
<span class="term">
<code class="literal">--depth empty</code>
</span>
</dt>
<dd>
<p>Include only the immediate target of the operation,
not any of its file or directory children.</p>
</dd>
<dt>
<span class="term">
<code class="literal">--depth files</code>
</span>
</dt>
<dd>
<p>Include the immediate target of the operation and any
of its immediate file children.</p>
</dd>
<dt>
<span class="term">
<code class="literal">--depth immediates</code>
</span>
</dt>
<dd>
<p>Include the immediate target of the operation and any
of its immediate file or directory children. The directory
children will themselves be empty.</p>
</dd>
<dt>
<span class="term">
<code class="literal">--depth infinity</code>
</span>
</dt>
<dd>
<p>Include the immediate target, its file and directory
children, its children's children, and so on to full
recursion.</p>
</dd>
</dl>
</div>
<p>
<a id="idp10038608" class="indexterm"></a>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 <em class="firstterm">ambient depth</em>, 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 <span class="quote">“<span class="quote">sticky</span>”</span>. 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.</p>
<div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Tip">
<tr>
<td rowspan="2" align="center" valign="top" width="25">
<img alt="[Tip]" src="images/tip.png" />
</td>
<th align="left">Tip</th>
</tr>
<tr>
<td align="left" valign="top">
<p>You can check the recorded ambient depth of a working copy
using the <span class="command"><strong>svn info</strong></span> command. If the ambient
depth is anything other than infinite recursion, <span class="command"><strong>svn
info</strong></span> will display a line describing that depth
value:</p>
<div class="informalexample">
<pre class="screen">
$ svn info mom-immediates | grep "^Depth:"
Depth: immediates
$
</pre>
</div>
</td>
</tr>
</table>
</div>
<p>Our previous examples demonstrated checkouts of infinite
depth (the default for <span class="command"><strong>svn checkout</strong></span>) and
empty depth. Let's look now at examples of the other depth
values:</p>
<div class="informalexample">
<pre class="screen">
$ 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.
$
</pre>
</div>
<p>As described, each of these depths is something more than
only the target, but something less than full recursion.</p>
<p>We've used <span class="command"><strong>svn checkout</strong></span> as an example
here, but you'll find the <code class="option">--depth</code> option
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
<code class="option">--non-recursive</code> (<code class="option">-N</code>) and
<code class="option">--recursive</code> (<code class="option">-R</code>) options
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.</p>
<p>In addition to the <code class="option">--depth</code> option, the
<span class="command"><strong>svn update</strong></span> and <span class="command"><strong>svn switch</strong></span>
subcommands also accept a second depth-related option:
<code class="option">--set-depth</code>. 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 <strong class="userinput"><code>svn update
--set-depth <em class="replaceable"><code>NEW-DEPTH</code></em> <em class="replaceable"><code>TARGET</code></em></code></strong>:</p>
<div class="informalexample">
<pre class="screen">
$ svn update --set-depth files mom-empty
Updating 'mom-empty':
A mom-empty/kittie1.txt
A mom-empty/doggie1.txt
Updated to revision 1.
$ svn update --set-depth immediates mom-empty
Updating 'mom-empty':
A mom-empty/son
A mom-empty/daughter
Updated to revision 1.
$ svn update --set-depth infinity mom-empty
Updating '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.
$
</pre>
</div>
<p>As we gradually increased our depth selection, the
repository gave us more pieces of our tree.</p>
<p>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
<span class="emphasis"><em>any</em></span> 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 <span class="quote">“<span class="quote">sparse</span>”</span> 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).</p>
<div class="informalexample">
<pre class="screen">
$ 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
Updating 'mom-empty/son':
A mom-empty/son
Updated to revision 1.
$ svn update --set-depth empty mom-empty/daughter
Updating 'mom-empty/daughter':
A mom-empty/daughter
Updated to revision 1.
$ svn update --set-depth infinity mom-empty/daughter/granddaughter1
Updating '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.
$
</pre>
</div>
<p>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 <code class="option">--depth</code> and
<code class="option">--set-depth</code>) to the relevant subcommands. Even
<span class="command"><strong>svn update</strong></span> works as it does elsewhere when no
specific depth is provided—it updates the working copy
targets that are present while honoring their sticky
depths.</p>
<p>You might at this point be wondering, <span class="quote">“<span class="quote">So what? When
would I use this?</span>”</span> 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 (<code class="filename">trunk/project1</code>,
<code class="filename">trunk/project2</code>,
<code class="filename">trunk/project3</code>, etc.). In such
scenarios, it might be the case that you personally care
about only 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
citizens.</p>
<p>The original (Subversion 1.5) implementation of shallow
checkouts was good, but didn't support de-telescoping of working
copy items. Subversion 1.6 remedied this problem. For example,
running <strong class="userinput"><code>svn update --set-depth empty</code></strong> in
an infinite-depth working copy will discard everything but the
topmost directory.<sup>[<a id="idp10070880" href="#ftn.idp10070880" class="footnote">27</a>]</sup> Subversion
1.6 also introduced another supported value for
the <code class="option">--set-depth</code>
option: <code class="literal">exclude</code>. Using <code class="option">--set-depth
exclude</code> with <span class="command"><strong>svn update</strong></span> will cause
the update target to be removed from the working copy
entirely—a directory target won't even be left
present-but-empty. This is especially handy when there are more
things that you'd like to keep in a working copy than things
you'd like to <span class="emphasis"><em>not</em></span> keep.</p>
<p>Consider a directory with hundreds of subdirectories, one of
which you would like to omit from your working copy. Using
an <span class="quote">“<span class="quote">additive</span>”</span> approach to sparse directories, you
might check out the directory with an empty depth, then
explicitly telescope (using <strong class="userinput"><code>svn update --set-depth
infinity</code></strong>) each and every subdirectory of the
directory except the one you don't care about.</p>
<div class="informalexample">
<pre class="screen">
$ svn checkout http://svn.example.com/repos/many-dirs --depth empty
…
$ svn update --set-depth infinity many-dirs/wanted-dir-1
…
$ svn update --set-depth infinity many-dirs/wanted-dir-2
…
$ svn update --set-depth infinity many-dirs/wanted-dir-3
…
### and so on, and so on, ...
</pre>
</div>
<p>This could be quite tedious, especially since you don't even
have stubs of these directories in your working copy to deal
with. Such a working copy would also have another
characteristic that you might not expect or desire: if someone
else creates any new subdirectories in this top-level directory,
you won't receive those when you update your working
copy.</p>
<p>Beginning with Subversion 1.6, you can take a different
approach. First, check out the directory in full. Then
run <strong class="userinput"><code>svn update --set-depth exclude</code></strong> on the
one subdirectory you don't care about.</p>
<div class="informalexample">
<pre class="screen">
$ svn checkout http://svn.example.com/repos/many-dirs
…
$ svn update --set-depth exclude many-dirs/unwanted-dir
D many-dirs/unwanted-dir
$
</pre>
</div>
<p>This approach leaves your working copy with the same stuff
as in the first approach, but any new subdirectories which
appear in the top-level directory would also show up when you
update your working copy. The downside of this approach is that
you have to actually check out that whole subdirectory that you
don't even want just so you can tell Subversion that you don't
want it. This might not even be possible if that subdirectory
is too large to fit on your disk (which might, after all, be the
very reason you don't want it in your working copy).</p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25">
<img alt="[Note]" src="images/note.png" />
</td>
<th align="left">Note</th>
</tr>
<tr>
<td align="left" valign="top">
<p>While the functionality for excluding an existing item
from a working copy was hung off of the <span class="command"><strong>svn
update</strong></span> command, you might have noticed that the
output from <strong class="userinput"><code>svn update --set-depth
exclude</code></strong> differs from that of a normal update
operation. This output betrays the fact that, under the hood,
exclusion is a completely client-side operation, very much
unlike a typical update.</p>
</td>
</tr>
</table>
</div>
<p>In such a situation, you might consider a compromise
approach. First, check out the top-level directory
with <code class="option">--depth immediates</code>. Then, exclude the
directory you don't want using <strong class="userinput"><code>svn update --set-depth
exclude</code></strong>. Finally, telescope all the items that
remain to infinite depth, which should be fairly easy to do
because they are all addressable in your shell.</p>
<div class="informalexample">
<pre class="screen">
$ svn checkout http://svn.example.com/repos/many-dirs --depth immediates
…
$ svn update --set-depth exclude many-dirs/unwanted-dir
D many-dirs/unwanted-dir
$ svn update --set-depth infinity many-dirs/*
…
$
</pre>
</div>
<p>Once again, your working copy will have the same stuff as in
the previous two scenarios. But now, any time a new file or
subdirectory is committed to the top-level directory, you'll
receive it—at an empty depth—when you update your
working copy. You can now decide what to do with such newly
appearing working copy items: expand them into infinite depth,
or exclude them altogether.</p>
<div class="footnotes">
<br />
<hr width="100" align="left" />
<div class="footnote">
<p><sup>[<a id="ftn.idp10070880" href="#idp10070880" class="para">27</a>] </sup>Safely, of course. As in
other situations, Subversion will leave on disk any files you've
modified or which aren't versioned.</p>
</div>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="svn.advanced.props.special.keywords.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="svn.advanced.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="svn.advanced.locking.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Keyword Substitution </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Locking</td>
</tr>
</table>
</div>
<div xmlns="" id="vcws-footer">
<hr />
<img src="images/cc-by.png" style="float: right;" />
<p>You are reading <em>Version Control with Subversion</em> (for
Subversion 1.8), by Ben Collins-Sussman, Brian W. Fitzpatrick,
and C. Michael Pilato.</p>
<p>This work is licensed under
the <a href="http://creativecommons.org/licenses/by/2.0/">Creative Commons Attribution License v2.0</a>.</p>
<p>To submit comments, corrections, or other contributions to the
text, please visit <a href="http://www.svnbook.com/">http://www.svnbook.com/</a>.</p>
</div>
</body>
</html>
distrib
>
Mageia
>
6
>
x86_64
>
media
>
core-updates
>
by-pkgid
>
e8fe8188cee5592550f08a19b470186d
>
files
>
41
