On this page

In this section

Related content

Still need help?

This page provides a brief explanation of how Subversion works, how Fisheye interacts with it, and examples of how to configure Fisheye to work with Subversion according to your needs.

In a Subversion repository, branches and tags can be easily copied or duplicated — this is done by creating a form of pointer or reference from one location to another, avoiding the need to duplicate a lot of information. The disadvantage of this is that Subversion repositories can be confusing to administer at times and its internal complexity can be problematic for applications such as Fisheye that need to finely process its contents. As a result, Fisheye may require some in-depth configuration with Subversion.

Fisheye automatic presets

If your repository structure strictly follows either of the Subversion conventions then these presets will be suitable.

To apply a preset, go to the repository configuration page (click the repository name on the 'Repositories' screen) and choose a preset from the And then Apply the Following Rules list.

However if you have defined your svn structure via the custom symbolic rules, then you should set "Use In-built Symbolic Rules" to no.

The Use Built-in Symbolic Rules checkbox applies another regex which does a deep search for trunk, tag and branch directories. If your structure exactly matches the selected symbolic rule set, then it is safe to uncheck this.

Note that the preset rules are case-sensitive – if your SVN folder structure doesn't use all lowercase naming then you will need to define your own symbolic rules based on the defaults.

Custom layouts

If you have a custom repository structure, that is your repository structure does not follow SVN conventions, you need to configure Fisheye to recognize the paths in your repository. What you are telling Fisheye is which paths within the repository are related, i.e. which are operations on the same file in different branches and which are tags of a file. You must also tell Fisheye how to determine the branch name or the tag name. Most custom layouts are variations on the one of the two standard layouts described above. The best approach to creating your custom configuration is to use one of the appropriate entries from the drop down list. This can serve as a template for you, which you can then customize. Once you have selected the appropriate template, select the "Custom" entry from the drop down list. Now, you will be able to edit the entries (or add entries).

How to set a custom layout

Using Regular Expressions, you can describe any custom tag or branch structure that you have. You should use one of the common layouts (from the drop down list) as a basis, firstly select it, then select 'Custom' to edit or add rules.

When looking at a file on a branch, or a file that was tagged, Fisheye needs to determine a name for the branch or tag. Fisheye does this by matching a regular expression against the file's path, and extracting the name based upon the match. Fisheye also needs a name for files on the trunk. In effect, this is the name of the trunk 'branch'.

For any file that matches a trunk/branch/tag regular expression, a logical path is calculated. Two different files with the same logical path are considered to be related. For example, using the second type of common repository layout:

The file project1/trunk/dir1/foo.txt would have a logical path of project1/dir1/foo.txt.

The file project1/tags/BUILD123/dir1/foo.txt would have a logical path of project1/dir1/foo.txt and the name of the tag would be project1-BUILD123.

Both these files have the same logical path, and so are considered related. By looking at the revision where the directory-copy for project1/tags/BUILD123/dir1/foo.txt occurred, Fisheye can determine to what revision the tag project1-BUILD123 applies.

Interpreting multiple rules

To find which rule to apply, Fisheye creates three sets of rules and tries them in this order: branches, tags, trunk.

For each set of rules, it finds the closest match within that set. If any rule in the set matches, Fisheye will not try the next set. If multiple rules within a set match then Fisheye will use the best match. The best match is the rule with the smallest logical tail (the trailing part of the path that does not match the regex).

Examples

These examples show the regular expressions used for some custom configurations. If you need more information on how these examples work, please see SVN tag and branch structure on this page.

Ideal configuration exampleThis shows a best-case near "zero configuration" project structure that is instantly compatible with Fisheye.In this case, you have trunk, branches and tags as the base folders in your repository.

Fisheye customer example.This is a real-world configuration used by a Fisheye customer.

Ideal configuration example

If your repository is organized in this way, simply select the In-Built symbolic rules option. Fisheye will then be fully connected to your repository (you do not need to write a regular expression, or choose anything from a list).

Project structure

Custom example 1

Whenever you have a custom project structure in Subversion, you will need to write a regular expression.

Say you have an additional directory you use for tagging releases, which is different from the everyday tags you create in the tags directory:

Project structure

/trunk/
/branches/branchname
/tags/tagname
/releases/releasename

Symbolic rules

Regular Expression

Name

Logical Path Prefix

trunk(/|$)

trunk

N/A

branches/([^/]+)

${1}

N/A

(tags|releases)/([^/]+)

${2}

N/A

Custom example 2

Whenever you have a custom project structure in Subversion, you will need to write a regular expression.

In this example, there is a "core" project area and then a number of separate plugins. the core contains its own trunk/branches/tags structure while the plugins are in a named directory which contains their trunk/branches/tags directory. We want to have the core and all the plugins visible in a single Fisheye repository.

In this example, the Logical Path Prefix has been configured to distinguish files with the same name in different plugins. For example, the file build.xml may exist in all plugins but such files are not related even though they have the same name. The Logical Path Prefix is used to tell Fisheye to which "logical group" the files belong.

Example from a Fisheye customer

This is real-world example from a Fisheye customer. This is a slightly non-standard project structure. The correct symbolic rules for this project structure are shown below:

Project structure

/trunk/PROJECT1
/branches/PROJECT1/branchname
/tags/PROJECT1/tagname

Symbolic rules

Regular Expression

Name

Logical Path Prefix

trunk/([^/]+)

${1}

N/A

branches/([^/]+)/([^/]+)

${1}-${2}

N/A

tags/([^/]+)/([^/]+)

${1}-${2}

N/A

How Subversion works

Since tags and branches are implemented via directory copies in Subversion, they are not really first-class concepts. This means that Fisheye has to determine branch and tag information by examining the paths involved in Subversion operations and matching these against branch and tag conventions used in the repository. Since these conventions are not fixed, you may need to tell Fisheye what conventions you use in your repository. By default Fisheye has some inbuilt rules which handle the most common conventions typically used in most Subversion sites. If, however, you've decided to use a custom convention, you can define custom rules to describe what your tag/branch structure looks like. These settings can be edited on the 'Add Repository' or 'Edit Repository' pages in the Fisheye Administration pages.

The symbolic setup tells Fisheye how to classify each path it encounters as it indexes the repository. Each path is classified as either a trunk, branch, tag or root path. The trunk, branch and tag categories are the normal conventions used in SCMs. The root category is used when a path does not match any of the given trunk/branch/tag settings and is mostly treated in the same way as trunk paths. For example, the branches directory itself does not belong to the trunk, a particular branch or a tag and is classified as a root path.

The symbolic settings do not exclude any paths from consideration by Fisheye. To exclude paths you should set up appropriate 'allow' rules. If your symbolic setup does not match a path, that path will be classified as a root path and processed by Fisheye accordingly.

If you change these trunk/branch/tag settings, you would normally perform a complete re-scan of the repository to ensure Fisheye's index is consistent with the settings. Fisheye will suggest this when you make changes and you can also do this manually from the Indexer option. If you don't want to re-index, you can also choose to ignore this suggestion.