<?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>Ignoring Unversioned Items</title><link rel="stylesheet" href="styles.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><link rel="start" href="index.html" title="Version Control with Subversion" /><link rel="up" href="svn.advanced.html" title="Chapter 3. Advanced Topics" /><link rel="prev" href="svn.advanced.props.file-portability.html" title="File Portability" /><link rel="next" href="svn.advanced.props.special.keywords.html" title="Keyword Substitution" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Ignoring Unversioned Items</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="svn.advanced.props.file-portability.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.props.special.keywords.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="svn.advanced.props.special.ignore"></a>Ignoring Unversioned Items</h2></div></div></div><p>In any given working copy there is a good chance that
alongside all those versioned files and directories are other
files and directories which are neither versioned nor intended
to be. Text editors litter directories with backup files.
Software compilers generate intermediate—or even
final—files which you typically wouldn't bother to
version. And users themselves drop various other files and
directories wherever they see fit, often in version control
working copies.</p><p>It's ludicrous to expect Subversion working copies to be
somehow impervious to this kind of clutter and impurity. In
fact, Subversion counts it as a <span class="emphasis"><em>feature</em></span>
that its working copies are just typical directories, just like
unversioned trees. But these not-to-be-versioned files and
directories can cause some annoyance for Subversion users. For
example, because the <span class="command"><strong>svn add</strong></span> and <span class="command"><strong>svn
import</strong></span> commands act recursively by default, and don't
know which files in a given tree you do and don't wish to
version, it's easy to accidentally add stuff to version control
that you didn't mean to. And because <span class="command"><strong>svn
status</strong></span> reports, by default, every item of interest in
a working copy—including unversioned files and
directories—its output can get quite noisy where many of
these things exist.</p><p>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 <a class="xref" href="svn.advanced.confarea.html" title="Runtime Configuration Area">the section called “Runtime Configuration Area”</a>), and
therefore applies to all the Subversion operations which 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, 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.</p><p>The Subversion runtime configuration system provides an
option, <code class="literal">global-ignores</code>, whose value is a
whitespace-delimited collection of file patterns (also known as
<em class="firstterm">globs</em>). The Subversion client checks
these patterns against the names of the files which are
candidates for addition to version control, as well as to
unversioned files which the <span class="command"><strong>svn status</strong></span>
command notices. If any file's name matches one of the
patterns, Subversion will basically act as if the file didn't
exist at all. This is really useful for the kinds of files that
you almost never want to version, such as editor backup files
like Emacs' <code class="literal">*~</code> and <code class="literal">.*~</code>
files.</p><p>When found on a versioned directory, the
<code class="literal">svn:ignore</code> property is expected to contain a
list of newline-delimited file patterns which Subversion should
use to determine ignorable objects in that same directory.
These patterns do not override those found in the
<code class="literal">global-ignores</code> runtime configuration option,
but are instead appended to that list. And it's worth noting
again that, unlike the <code class="literal">global-ignores</code> option,
the patterns found in the <code class="literal">svn:ignore</code>
property apply only to the directory on which that property is
set, and not to any of its subdirectories. The
<code class="literal">svn:ignore</code> property is a good way to tell
Subversion to ignore files that are likely to be present in
every user's working copy of that directory, such as compiler
output or—to use an example more appropriate to this
book—the HTML, PDF, or PostScript files generated as the
result of a conversion of some source DocBook XML files to a
more legible output format.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Subversion's support for ignorable file patterns extends
only to the one-time process of adding unversioned
files and directories to version control. Once an object is
under Subversion's control, the ignore pattern mechanisms no
longer apply to it. In other words, don't expect Subversion
to avoid committing changes you've made to a versioned file
simply because that file's name matches an ignore
pattern—Subversion <span class="emphasis"><em>always</em></span> notices
all of its versioned objects.</p></div><div class="sidebar"><p class="title"><b>Ignore Patterns for CVS Users</b></p><p>The Subversion <code class="literal">svn:ignore</code> property is
very similar in syntax and function to the CVS
<code class="filename">.cvsignore</code> file. In fact, if you are
migrating a CVS working copy to Subversion, you can directly
migrate the ignore patterns by using the
<code class="filename">.cvsignore</code> file as input file to the
<span class="command"><strong>svn propset</strong></span> command:</p><pre class="screen">
$ svn propset svn:ignore -F .cvsignore .
property 'svn:ignore' set on '.'
$
</pre><p>There are, however, some differences in the ways that CVS
and Subversion handle ignore patterns. The two systems use
the ignore patterns at some different times, and there are
slight discrepancies in what the ignore patterns apply to.
Also, Subversion does not recognize the use of the
<code class="literal">!</code> pattern as a reset back to having no
ignore patterns at all.</p></div><p>The global list of ignore patterns tends to be more a
matter of personal taste, and tied more closely to a user's
particular tool chain than to the details of any particular
working copy's needs. So, the rest of this section will focus
on the <code class="literal">svn:ignore</code> property and its
uses.</p><p>Say you have the following output from <span class="command"><strong>svn
status</strong></span>:</p><pre class="screen">
$ 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
</pre><p>In this example, you have made some property modifications
to <code class="filename">button.c</code>, but in your working copy you
also have some unversioned files: the latest
<code class="filename">calculator</code> program that you've compiled
from your source code, a source file named
<code class="filename">data.c</code>, and a set of debugging output log
files. Now, you know that your build system always results in
the <code class="filename">calculator</code> program being generated.
<sup>[<a id="id360056" href="#ftn.id360056" class="footnote">14</a>]</sup>
And you know that your test suite always leaves those debugging
log files lying around. These facts are true for all working
copies of this project, not just your own. And you know that
you aren't interested in seeing those things every time you run
<span class="command"><strong>svn status</strong></span>, and pretty sure that nobody else
is interested in them either. So you use <span class="command"><strong>svn propedit
svn:ignore calc</strong></span> to add some ignore patterns to the
<code class="filename">calc</code> directory. For example, you might add
this as the new value of the <code class="literal">svn:ignore</code>
property:</p><pre class="programlisting">
calculator
debug_log*
</pre><p>After you've added this property, you will now have a local
property modification on the <code class="filename">calc</code>
directory. But notice what else is different about your
<span class="command"><strong>svn status</strong></span> output:</p><pre class="screen">
$ svn status
M calc
M calc/button.c
? calc/data.c
</pre><p>Now, all that cruft is missing from the output! Of course,
your <code class="filename">calculator</code> compiled program and all
those logfiles are still in your working copy. Subversion is
simply not reminding you that they are present and unversioned.
And now with all the uninteresting noise removed from the
display, you are left with more interesting items—such as
that source code file <code class="filename">data.c</code> that you
probably forgot to add to version control.</p><p>Of course, this less-verbose report of your working copy
status isn't the only one available. If you actually want to
see the ignored files as part of the status report, you can pass
the <code class="option">--no-ignore</code> option to Subversion:</p><pre class="screen">
$ svn status --no-ignore
M calc
M calc/button.c
I calc/calculator
? calc/data.c
I calc/debug_log
I calc/debug_log.1
I calc/debug_log.2.gz
I calc/debug_log.3.gz
</pre><p>As mentioned earlier, the list of file patterns to ignore is
also used by <span class="command"><strong>svn add</strong></span> and <span class="command"><strong>svn
import</strong></span>. Both of these operations involve asking
Subversion to begin managing some set of files and directories.
Rather than force the user to pick and choose which files in a
tree she wishes to start versioning, Subversion uses the ignore
patterns—both the global and the per-directory
lists—to determine which files should not be swept into
the version control system as part of a larger recursive
addition or import operation. And here again, you can use the
<code class="option">--no-ignore</code> option to tell Subversion ignore
its ignores list and operate on all the files and directories
present.</p><div class="footnotes"><br /><hr width="100" align="left" /><div class="footnote"><p><sup>[<a id="ftn.id360056" href="#id360056" class="para">14</a>] </sup>Isn't that the whole point of a build system?</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.file-portability.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.props.special.keywords.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">File Portability </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Keyword Substitution</td></tr></table></div></body></html>
