<?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" 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.file-portability.html" title="File Portability" />
<link rel="next" href="svn.advanced.props.special.keywords.html" title="Keyword Substitution" />
</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">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" title="Ignoring Unversioned Items">
<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 that are neither versioned nor intended
to be. Text editors litter directories with backup files.
Software compilers generate intermediate—or even
final—files that 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>
<a id="idp9761056" class="indexterm"></a>
<a id="idp9762096" class="indexterm"></a>
<a id="idp9763584" class="indexterm"></a>So Subversion provides several 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 that make use
of that runtime configuration—generally those performed on
a particular computer or by a particular user of a computer.
Two other methods make use of Subversion's directory property
support and are more tightly bound to the versioned tree itself,
and therefore affects everyone who has a working copy of that
tree. All of these mechanisms use <em class="firstterm">file
patterns</em> (strings of literal and special wildcard
characters used to match against filenames) to decide which
files to ignore.</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. The
Subversion client checks these patterns against the names of the
files that are candidates for addition to version control, as
well as to unversioned files that 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 such as Emacs' <code class="literal">*~</code> and
<code class="literal">.*~</code> files.</p>
<div class="sidebar" title="File Patterns in Subversion">
<div class="titlepage">
<div>
<div>
<p class="title">
<strong>File Patterns in Subversion</strong>
</p>
</div>
</div>
</div>
<p>File patterns (also called <em class="firstterm">globs</em> or
<em class="firstterm">shell wildcard patterns</em>) are strings of
characters that are intended to be matched against filenames,
typically for the purpose of quickly selecting some subset of
similar files from a larger grouping without having to
explicitly name each file. The patterns contain two types of
characters: regular characters, which are compared explicitly
against potential matches, and special wildcard characters,
which are interpreted differently for matching
purposes.</p>
<p>There are different types of file pattern syntaxes, but
Subversion uses the one most commonly found in Unix systems
implemented as the <code class="function">fnmatch</code> system
function. It supports the following wildcards, described here
simply for your convenience:</p>
<div class="variablelist">
<dl>
<dt>
<span class="term">
<code class="literal">?</code>
</span>
</dt>
<dd>
<p>Matches any single character</p>
</dd>
<dt>
<span class="term">
<code class="literal">*</code>
</span>
</dt>
<dd>
<p>Matches any string of characters, including the
empty string</p>
</dd>
<dt>
<span class="term">
<code class="literal">[</code>
</span>
</dt>
<dd>
<p>Begins a character class definition terminated by
<code class="literal">]</code>, used for matching a subset of
characters</p>
</dd>
</dl>
</div>
<p>You can see this same pattern matching behavior at a Unix
shell prompt. The following are some examples of patterns
being used for various things:</p>
<div class="informalexample">
<pre class="screen">
$ ls ### the book sources
appa-quickstart.xml ch06-server-configuration.xml
appb-svn-for-cvs-users.xml ch07-customizing-svn.xml
appc-webdav.xml ch08-embedding-svn.xml
book.xml ch09-reference.xml
ch00-preface.xml ch10-world-peace-thru-svn.xml
ch01-fundamental-concepts.xml copyright.xml
ch02-basic-usage.xml foreword.xml
ch03-advanced-topics.xml images/
ch04-branching-and-merging.xml index.xml
ch05-repository-admin.xml styles.css
$ ls ch* ### the book chapters
ch00-preface.xml ch06-server-configuration.xml
ch01-fundamental-concepts.xml ch07-customizing-svn.xml
ch02-basic-usage.xml ch08-embedding-svn.xml
ch03-advanced-topics.xml ch09-reference.xml
ch04-branching-and-merging.xml ch10-world-peace-thru-svn.xml
ch05-repository-admin.xml
$ ls ch?0-* ### the book chapters whose numbers end in zero
ch00-preface.xml ch10-world-peace-thru-svn.xml
$ ls ch0[3578]-* ### the book chapters that Mike is responsible for
ch03-advanced-topics.xml ch07-customizing-svn.xml
ch05-repository-admin.xml ch08-embedding-svn.xml
$
</pre>
</div>
<p>File pattern matching is a bit more complex than what
we've described here, but this basic usage level tends to suit
the majority of Subversion users.</p>
</div>
<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 that Subversion should
use to determine ignorable objects in that
<span class="emphasis"><em>same</em></span> 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>
<p>Subversion 1.8 provides a more powerful version of the
<code class="literal">svn:ignore</code> property, the
<code class="literal">svn:global-ignores</code> property. Like the
<code class="literal">svn:ignore</code> property,
<code class="literal">svn:global-ignores</code> can only be set
on a directory and contains file patterns Subversion uses to
determine ignorable objects.<sup>[<a id="idp9794016" href="#ftn.idp9794016" class="footnote">21</a>]</sup> These ignore patterns are also
appended to any patterns defined in the
<code class="literal">global-ignores</code> runtime configuration option
together with any <code class="literal">svn:ignore</code> defined patterns.
Unlike <code class="literal">svn:ignore</code> however, the
<code class="literal">svn:global-ignores</code> property is inheritable
<sup>[<a id="idp9799888" href="#ftn.idp9799888" class="footnote">22</a>]</sup>
and applies to <span class="emphasis"><em>all</em></span> paths under the directory on
which the property is set, not just the immediate children of the
directory.</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>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>
</td>
</tr>
</table>
</div>
<div class="sidebar" title="Ignore Patterns for CVS Users">
<div class="titlepage">
<div>
<div>
<p class="title">
<strong>Ignore Patterns for CVS Users</strong>
</p>
</div>
</div>
</div>
<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 to the
<span class="command"><strong>svn propset</strong></span> command:</p>
<div class="informalexample">
<pre class="screen">
$ svn propset svn:ignore -F .cvsignore .
property 'svn:ignore' set on '.'
$
</pre>
</div>
<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 ignore patterns in the <code class="literal">global-ignores</code>
runtime configuration option tend to be more a
matter of personal taste<sup>[<a id="idp9811744" href="#ftn.idp9811744" class="footnote">23</a>]</sup> and ties 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> and
<code class="literal">svn:global-ignores</code> properies and their
uses.</p>
<p>Say you have the following output from <span class="command"><strong>svn
status</strong></span>:</p>
<div class="informalexample">
<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>
</div>
<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
logfiles. Now, you know that your build system always results
in the <code class="filename">calculator</code> program being
generated.<sup>[<a id="idp9822224" href="#ftn.idp9822224" class="footnote">24</a>]</sup> And you know that your test suite
always leaves those debugging logfiles 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 you are pretty sure that
nobody else is interested in them either. So you use
<strong class="userinput"><code>svn propedit svn:ignore calc</code></strong> to add some
ignore patterns to the <code class="filename">calc</code>
directory.</p>
<div class="informalexample">
<pre class="screen">
$ svn propget svn:ignore calc
calculator
debug_log*
$
</pre>
</div>
<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>
<div class="informalexample">
<pre class="screen">
$ svn status
M calc
M calc/button.c
? calc/data.c
</pre>
</div>
<p>Now, all that cruft is missing from the output! Your
<code class="filename">calculator</code> compiled program and all those
logfiles are still in your working copy; Subversion just isn't
constantly reminding you that they are present and unversioned.
And now with all the uninteresting noise removed from the
display, you are left with more intriguing 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>
<div class="informalexample">
<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
I calc/wip.1.diff
</pre>
</div>
<p>All of your previously hidden unversioned paths are once
again shown, but now with the <code class="literal">'I' Ignored</code>
status. But wait, what about <code class="filename">wip.1.diff</code>?
The <code class="literal">svn:ignore</code> property on
<code class="filename">calc</code> doesn't include any pattern that
matches that filename, so why is it ignored?<sup>[<a id="idp9837680" href="#ftn.idp9837680" class="footnote">25</a>]</sup> The answer lies in the third method by which
Subversion can disregard unversioned paths, the inheritable
<code class="literal">svn:global-ignores</code> property. Using the
<span class="command"><strong>svn propget</strong></span> subcommand with the
<code class="option">--show-inherited-props</code> option, you see that
the <code class="literal">svn:global-ignores</code> property is set on the
root of your working copy, and sure enough, it defines a
matching ignore pattern:</p>
<div class="informalexample">
<pre class="screen">
$ svn pg svn:global-ignores calc -v --show-inherited-props
Inherited properties on 'calc',
from '.':
svn:global-ignores
*.diff
*.patch
</pre>
</div>
<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—the global, per-directory, and inherited
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 to disregard
its ignores list and operate on all the files and directories
present.</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>Even if <code class="literal">svn:ignore</code> or
<code class="literal">svn:global-ignores</code> is set, you may run
into problems if you use shell wildcards in a command. Shell
wildcards are expanded into an explicit list of targets before
Subversion operates on them, so running <strong class="userinput"><code>svn
<em class="replaceable"><code>SUBCOMMAND</code></em> *</code></strong> is just like
running <strong class="userinput"><code>svn <em class="replaceable"><code>SUBCOMMAND</code></em>
file1 file2 file3 …</code></strong>. In the case of the
<span class="command"><strong>svn add</strong></span> command, this has an effect similar
to passing the <code class="option">--no-ignore</code> option. So
instead of using a wildcard, use <strong class="userinput"><code>svn add --force
.</code></strong> to do a bulk scheduling of unversioned things for
addition. The explicit target will ensure that the current
directory isn't overlooked because of being already under
version control, and the <code class="option">--force</code> option will
cause Subversion to crawl through that directory, adding
unversioned files while still honoring the
<code class="literal">svn:ignore</code> and
<code class="literal">svn:global-ignores</code> properties and the
<code class="literal">global-ignores</code> runtime configuration
variable. Be sure to also provide the <code class="option">--depth
files</code> option to the <span class="command"><strong>svn add</strong></span>
command if you don't want a fully recursive crawl for things
to add.</p>
</td>
</tr>
</table>
</div>
<div class="footnotes">
<br />
<hr width="100" align="left" />
<div class="footnote">
<p><sup>[<a id="ftn.idp9794016" href="#idp9794016" class="para">21</a>] </sup>The ignore patterns
in the <code class="literal">svn:global-ignores</code> property may be
delimited with any whitespace (similar to the
<code class="literal">global-ignores</code> runtime configuration option),
not just newlines (as with the <code class="literal">svn:ignore</code>
property).</p>
</div>
<div class="footnote">
<p><sup>[<a id="ftn.idp9799888" href="#idp9799888" class="para">22</a>] </sup>Of course only a 1.8 or newer Subversion client
will recognize the inheritability and special meaning of the
<code class="literal">svn:global-ignores</code> property!</p>
</div>
<div class="footnote">
<p><sup>[<a id="ftn.idp9811744" href="#idp9811744" class="para">23</a>] </sup>Despite being a matter
of personal taste, if you don't explicitly set the
<code class="literal">global-ignores</code> runtime
configuration option—either to your preferred set of
patterns or to an empty string—Subversion uses a default
value. See the <code class="literal">global-ignores</code> entry in
<a class="xref" href="svn.advanced.confarea.html#svn.advanced.confarea.opts.config" title="General configuration">the section called “General configuration”</a></p>
</div>
<div class="footnote">
<p><sup>[<a id="ftn.idp9822224" href="#idp9822224" class="para">24</a>] </sup>Isn't that the whole point of a build
system?</p>
</div>
<div class="footnote">
<p><sup>[<a id="ftn.idp9837680" href="#idp9837680" class="para">25</a>] </sup>
Let's assume that you don't have a matching pattern anywhere
in your <code class="literal">global-ignores</code> runtime configuration.
</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>
<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
>
i586
>
media
>
core-updates
>
by-pkgid
>
d32d95698a59acd37b394f83dfc217c6
>
files
>
39
