When the Teamprise Plug-in for Eclipse is installed, the Eclipse IDE will automatically detect new resources in projects and the Teamprise Plug-in will add these resources to its pending changes. Normally resources that are "derived" from another resource (build process output files, for instance) will not be sent to the Teamprise Plug-in, but some build configurations (those that perform external build steps, for example) will create resources that Eclipse does not know are derived. In order to prevent these resources from becoming pending additions to the source control repository, the Teamprise Plug-in for Eclipse (2.0 and later) consults two sets of filters to determine which resources should never be automatically added.
Eclipse 3.0 and later provides an Ignored Resources preference page under the Team preference category. This page contains a list of wildcards that apply to detected resources, and any matching resources are not added to the pending changes. The Teamprise Plug-in tests resources against this list first, so it may be used instead of the .tpignore file in many circumstances. However, because these preferences cannot be shared easily with other team members (each member must configure his own Ignored Resources preferences), and these preferences match only the last component of a resource path (the file or directory name at the end) the .tpignore file may be preferred.
The Teamprise Plug-in for Eclipse looks for a file named .tpignore at the root of Eclipse projects. This file is consulted each time Eclipse tells the Teamprise Plug-in about a new resource, and if the resource matches any of the patterns in the file, the resource is not added to the pending changes. If the resource does not match any of the patterns, it is added normally to the pending changes. Patterns in this file apply only to newly detected resources that are candidates for addition, and they apply only to resources in the Eclipse project where they reside. They do not apply to existing resources involved in non-add operations. Any files that match these exclusion patterns may always be added directly using the Teamprise Command-line Client or the Teamprise Explorer.
You do not need to restart Eclipse when you edit the .tpignore file. Your changes will take effect when the next new resource event is evaluated. The Teamprise Plug-in will also automatically load changes made to this file if a new version is retrieved from source control.
The Teamprise Plug-in never creates the .tpignore file; it must be created by a developer or manager with a text editor. By default, files beginning with a period are not displayed in the Eclipse Package Explorer, so you may need to use a tool other than Eclipse to create, edit, or delete the .tpignore file. You may also edit your Package Explorer filters to display files that begin with a period. The format of this file is described in detail below.
Once you have created a .tpignore file, you may add it to source control so other developers using the Teamprise Plug-in can use your patterns. You do not have to add the .tpignore file to source control for the Teamprise Plug-in to use it.
Patterns in the .tpignore file are Java regular expressions (see the .tpignore Format section below for more details). Matches are performed in a case-insensitive way on platforms where the filesystem matches in a case-insensitive manner, and in a case-sensitive way on platforms where the filesystem is case-sensitive.
When the Teamprise Plug-in tests an Eclipse resource path for a directory against a regular expression in the .tpignore file, it ensures the path always ends in a slash before the test is performed. This allows your regular expressions to be simpler when a directory is to be matched. Paths to resources that are files will never end in a slash.
All resource paths begin with a slash, and this is important to remember when writing your patterns.
The .tpignore file is a text file with a simple but powerful format. Each line is either a comment line or a pattern line. Each pattern line contains a single Java-style regular expression (see the Sun Java Tutorial Lesson: Regular Expressions). A newly discovered Eclipse resource path that matches any pattern in the .tpignore file is not added to the pending changes. Leading and trailing whitespace on each line is ignored when expressions are read from the .tpignore file.
The syntax of the .tpignore file represented in Backus-Naur Form:
<.tpignore> ::= { <line> }
<line> ::= <comment-line> | <pattern-line> <EOL>
<comment-line> ::= "#" <ignored-text>
<pattern-line> ::= <java-regular-expression>
Leading and trailing whitespace is ignored when parsing <line>s.
Here is an example .tpignore file. Each line is explained below.
# Lines that begin with #, like this one, are ignored.
.*/core
.*\.class
.*/[^/]+\.class
/some/path/README
/output/.*
/bin/
The first line is a comment and will be ignored. A .tpignore file may contain an arbitrary number of comment lines (including none).
The second line is a regular expression which will match any Eclipse resource path for a file that ends with the characters /core, including /core, /bin/core, and /some/long/path/core. The .* is regular expression syntax that means "match zero or more occurrances of any character." The rest of the line is literal characters to match. Resource /bin/core/main.c would not match because there are additional characters in the resource path after the literal part of the expression /core. It will not match directories because all directories end with a slash.
The third line is a regular expression which will match any Eclipse resource path for a file that ends with the characters .class. The period in the extension must be escaped because period has a special meaning in Java's regular expression syntax (it matches any character). This expression would match files named /Program.class, /some/long/path/Program.class. It will not match directories because all directories end with a slash.
The fourth line is a regular expression which will match any Eclipse resource path for a file that ends with the characters .class and has at least one character before the period in the last path component. Like in the third line, the period in the extension must be escaped. The expression syntax [^/] means "match all characters in this group, and this group contains all characters except for slash." This lets the expression match /some/long/path/File.class but not /some/long/path/.class. It will not match directories because all directories end with a slash.
The fifth line is a regular expression that uses no special syntax at all, but is still evaluated as a regular expression. It simply matches any file named exactly "/some/path/README". It would not match the directory resource "/some/path/README/", because directory resource paths always end in a slash.
The sixth line is a regular expression that matches the directory resource "/output/" and any of its children, whether they are files or directories. It will not match a file "/output" because the pattern requires a trailing slash and file paths do not have them.
The seventh line is a regular expression that matches only the directory resource "/bin/" and not its children. It does not match a file at "/bin" because it specifies a trailing slash that is only present in directory paths.
To cause the Teamprise Plug-in to start automatically adding discovered resources to the pending changes, remove or make into a comment the line or lines in the .tpignore file that match the resources you want added.