<?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" /> <link rel="home" 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" 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>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 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 <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 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" 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 file 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 global list of ignore patterns tends to be more a matter of personal taste 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> property and its 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="idp9443456" href="#ftn.idp9443456" class="footnote">18</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 </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—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 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> 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> property and <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.idp9443456" href="#idp9443456" class="para">18</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> <div xmlns="" id="svn-footer"> <hr /> <p>You are reading <em>Version Control with Subversion</em> (for Subversion 1.7), by Ben Collins-Sussman, Brian W. Fitzpatrick, and C. Michael Pilato.<br /> This work is licensed under the <a href="http://creativecommons.org/licenses/by/2.0/">Creative Commons Attribution License v2.0</a>.<br /> 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>