Configuring Subversion to ignore files can sometimes cause confusion. Like most things though, if you understand the basic principles, then its not tricky at all. In this post I’ll demonstrate just how you should go about ignoring files in a subversion project.

There are two ways to ignore files in svn: global settings and local. Global settings configure the users environment with some rules for ignoring files, but generally the local ignores are more useful and will be discussed here.

Most projects have files that should be ignored and not included in the version repository. For example, in Java projects, the compiler output shouldn’t be included as these can be regenerated from the source anyway. You might also have temporary cache files being generated, or output from running unit tests that you don’t want to share too.

Ignoring files and directories

Each directory in a svn managed project has a sub-directory called .svn which contains configuration information that svn uses when working in that directory. To make svn ignore certain content within a directory you need to configure an svn:ignore property for it.

To demonstrate this let’s work with the following project directory structure:

myproject/log-2009-12-01.txt
myproject/log-2009-12-02.txt
myproject/build/classes

First let’s tell svn to ignore the log files that have been created. I’m using SVN 1.5.4 on a Mac so I’ll demonstrate this using a command line but you could do much the same using a GUI tool like Tortoise:

$ svn propset svn:ignore 'log-*.txt' myproject

The above command has used the propset command to set the svn:ignore property value to log-*.txt for the myproject directory.

Note that it is possible to use a wild-card ‘*’ as part of the file name. You can also use the ‘?’ symbol to match a single character in a file name but svn does not currently support any more powerful matching features.

Importantly note also that the file name must be quoted in order that the literal value is passed to the svn command; without this the shell will process the wild-card and pass all matching file names instead.

You can inspect the value of this property using the propget command like this:

$ svn propget svn:ignore myproject
log-*.txt

An ignore property can also be applied to directories, causing all files and sub-directories within it to be ignored. To make svn ignore the classes directory and its contents we could use the command:

$ svn propset svn:ignore 'classes' myproject/build

Setting multiple ignore rules within a directory

So far we’ve looked at how we can set an individual ignore rule within a directory using the propset command. Although both of the rules we’ve demonstrated have resulted in multiple files being ignored, either by using a wild card syntax or by specifying a directory whose content will also be ignored, we’ve not yet discussed is how these rules can be combined within a directory; for example: to ignore all log files and also a sub-directory:

/myproject/log-2009-12-01.txt
/myproject/log-2009-12-02.txt
/myproject/classes

The svn:ignore property is actually a list of file name patterns that svn must ignore. The propset command simply overwrites that list with a single line that includes the pattern you specify when you issue the command.

To create a list of file names that will be matched, use the propedit command instead:

$ svn propedit svn:ignore myproject

Your svn editor will then be started and you can edit the list of filenames that must be ignored. For our example it would need to look like this:

log-*.txt
classes

Note that each file name pattern must be on a separate line.

Ignoring versioned files and directories

You must be aware that the svn:ignore properties only apply to any files that are not under version control.

In practical terms this means if you accidentally add a file or directory to your version control, you will need to explicitly issue a svn delete command (rm) in order that svn will ignore the files.

Commands like add and import work recursively in svn, so it’s easy to accidentally add files like those mentioned above to a versioned project. For example if our log files were accidentally added we could issue this command to delete them from svn:

svn rm log*.txt

Note this time that the filename is not quoted as we want the shell to pass all log files to be deleted.

After committing the changes to the project, the files will no longer be managed by svn and the ignore properties will once again work.