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.
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 feature 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 svn add and svn import 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 svn status 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.
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 the section called “Runtime Configuration Area”), 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 file patterns (strings of literal and special wildcard characters used to match against filenames) to decide which files to ignore.
The Subversion runtime configuration system provides an
option, global-ignores, 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 svn
status 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' *~ and
.*~ files.
When found on a versioned directory, the
svn:ignore 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
global-ignores runtime configuration option,
but are instead appended to that list. And it's worth noting
again that, unlike the global-ignores option,
the patterns found in the svn:ignore
property apply only to the directory on which that property is
set, and not to any of its subdirectories. The
svn:ignore 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.
Subversion 1.8 provides a more powerful version of the
svn:ignore property, the
svn:global-ignores property. Like the
svn:ignore property,
svn:global-ignores can only be set
on a directory and contains file patterns Subversion uses to
determine ignorable objects.[21] These ignore patterns are also
appended to any patterns defined in the
global-ignores runtime configuration option
together with any svn:ignore defined patterns.
Unlike svn:ignore however, the
svn:global-ignores property is inheritable
[22]
and applies to all paths under the directory on
which the property is set, not just the immediate children of the
directory.
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 always notices all of its versioned objects.
The ignore patterns in the global-ignores
runtime configuration option tend to be more a
matter of personal taste[23] 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 svn:ignore and
svn:global-ignores properies and their
uses.
Say you have the following output from svn status:
$ 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
In this example, you have made some property modifications
to button.c, but in your working copy, you
also have some unversioned files: the latest
calculator program that you've compiled
from your source code, a source file named
data.c, and a set of debugging output
logfiles. Now, you know that your build system always results
in the calculator program being
generated.[24] 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
svn status, and you are pretty sure that
nobody else is interested in them either. So you use
svn propedit svn:ignore calc to add some
ignore patterns to the calc
directory.
$ svn propget svn:ignore calc calculator debug_log* $
After you've added this property, you will now have a local
property modification on the calc
directory. But notice what else is different about your
svn status output:
$ svn status M calc M calc/button.c ? calc/data.c
Now, all that cruft is missing from the output! Your
calculator 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 data.c that you
probably forgot to add to version control.
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 --no-ignore option to Subversion:
$ 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
All of your previously hidden unversioned paths are once
again shown, but now with the 'I' Ignored
status. But wait, what about wip.1.diff?
The svn:ignore property on
calc doesn't include any pattern that
matches that filename, so why is it ignored?[25] The answer lies in the third method by which
Subversion can disregard unversioned paths, the inheritable
svn:global-ignores property. Using the
svn propget subcommand with the
--show-inherited-props option, you see that
the svn:global-ignores property is set on the
root of your working copy, and sure enough, it defines a
matching ignore pattern:
$ svn pg svn:global-ignores calc -v --show-inherited-props
Inherited properties on 'calc',
from '.':
svn:global-ignores
*.diff
*.patch
As mentioned earlier, the list of file patterns to ignore is
also used by svn add and svn
import. 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
--no-ignore option to tell Subversion to disregard
its ignores list and operate on all the files and directories
present.
Even if svn:ignore or
svn:global-ignores 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 svn
is just like
running SUBCOMMAND *svn . In the case of the
svn add command, this has an effect similar
to passing the SUBCOMMAND
file1 file2 file3 …--no-ignore option. So
instead of using a wildcard, use svn add --force
. 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 --force option will
cause Subversion to crawl through that directory, adding
unversioned files while still honoring the
svn:ignore and
svn:global-ignores properties and the
global-ignores runtime configuration
variable. Be sure to also provide the --depth
files option to the svn add
command if you don't want a fully recursive crawl for things
to add.
[21] The ignore patterns
in the svn:global-ignores property may be
delimited with any whitespace (similar to the
global-ignores runtime configuration option),
not just newlines (as with the svn:ignore
property).
[22] Of course only a 1.8 or newer Subversion client
will recognize the inheritability and special meaning of the
svn:global-ignores property!
[23] Despite being a matter
of personal taste, if you don't explicitly set the
global-ignores runtime
configuration option—either to your preferred set of
patterns or to an empty string—Subversion uses a default
value. See the global-ignores entry in
the section called “General configuration”
[24] Isn't that the whole point of a build system?
[25]
Let's assume that you don't have a matching pattern anywhere
in your global-ignores runtime configuration.