This page last changed on Sep 14, 2010 by tom@atlassian.com.

This page contains an 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.

On this page:

Overview

Subversion, one of the most popular source code management systems in use today, applies an interesting technology for creating branches and tags. In a Subversion repository, branches and tags can be easily copied or duplicated — this is allowed 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.

If you are following strict conventions in organising your Subversion repository (as laid out in the Subversion Red Book), FishEye has automatic presets which are compatible with your repository.

Jump straight to the examples, if you're already very familiar with Subversion and FishEye. Otherwise, please read on.

Introduction to Subversion conventions

The most common project structure in Subversion is to use a project structure and have trunk, branches and tags directories for each project, like so:

/project1/trunk/...
/project1/branches/b1
/project1/branches/b2
/project1/branches/...

/project1/tags/t1
/project1/tags/t2
/project1/tags/...

If you point your FishEye repository at a single project root, say /project1/, then to FishEye, the directory structure looks like this:

/trunk
/branches
/tags

In this case, you have one single project within the repository root. On the other hand, if you point FishEye at the repository root, you will have multiple projects visible in your FishEye view.

Note that this example follows common conventions for repository layout, as outlined in the Subversion Red Book. If you follow these conventions, your FishEye configuration will be simpler.

Choosing the correct configuration method

Unsure as to whether you can use a preset symbolic rule, or whether you need to write your own custom symbolic rules? Refer to the flowchart below for answers:

Flowchart: Choosing the correct configuration method

1. If you point FishEye at your project root:

/PROJECT1

-and you have simply the following:

trunk
branches
tags

-at this level of the repository, use FishEye's built-in rules for easy, one-step configuration.

2. If you point FishEye at the repository root, you have multiple projects and each project has the following:

trunk
branches
tags

-leading to this structure in each project:

/PROJECT1/trunk
/PROJECT1/branches
/PROJECT1/tags
/PROJECT2/trunk
/PROJECT2/branches
/PROJECT2/tags

-(and so on), use FishEye's built-in rules for easy, one-step configuration.

3. Otherwise, you have a custom layout.

Custom layouts

Regular expressions are required knowledge for creating custom repository layouts in FishEye.

You will now need to describe to FishEye how to recognise 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).

See the examples below for more information.

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.

You can add as many rules as you need. For any given file, the first rule that matches is used.

Rule Description
Regex The regular expression used to match against the start of the path. The trailing part of the path that does not match the regex is called the tail.
Name An expression used to extract a tag or branch name from the regex.
Logical Path Prefix This is an expression used to construct the logical path. The logical path is the concatenation of the result of this expression, and the tail of the regex.

See the examples below for more information.

Examples

These examples show the regular expressions used for some custom configurations. If you need more information on how these examples work, please see How Subversion Works on this page.

  • Ideal configuration example
    This 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.
  • Custom example 1
    This shows a custom project structure and the symbolic rules required.
  • Custom example 2
    This shows another kind of custom project structure and the symbolic rules required.
  • FishEye customer example.
    This is a real-world configuration used by a FishEye customer.

Ideal configuration example

If your repository is organised 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

/PROJECT1/trunk/

/PROJECT1/branches/branchname

/PROJECT1/tags/tagname

Note that this example follows common conventions, as outlined in the Subversion Red Book.

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.

Project Structure

/core/trunk/
/core/branches/
/core/tags/

/plugins/plugin1/trunk/
/plugins/plugin1/branches/
/plugins/plugin1/tags/

/plugins/plugin2/trunk/
/plugins/plugin2/branches/
/plugins/plugin2/tags/

Symbolic Rules

Applies to Regular Expression Name Logical Path Prefix
trunk
core/trunk(/|$) 
trunk
core
trunk
plugins/([^/]+)/trunk(/|$) 
trunk
plugin_${1}
branches
core/branches/([^/]+)


core-${1}
core
branches
plugins/([^/]+)/branches/([^/]+)


${1}-${2}
plugin_${1}
tags
core/tags/([^/]+)


core-${1}
core
tags
plugins/([^/]+)/tags/([^/]+)


${1}-${2}
plugin_${1}

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.

For more information on tag and branch layout, see Repository Layout in the Subversion documentation, or How Tags Work in Subversion for more background information.

Frequently Asked Questions

What is the logical path prefix?
The first part of a path, where you want to constrain to a specific origin for the paths in context.

What is the logical tail?
The last part of the path is the logical tail, that specifies the exact folders in context.

How does the logical tail affect the search?
The logical tail could be used to select every occurrence of a file called build.xml, for example, or every folder of a given name near the end of the path.

Document generated by Confluence on Apr 03, 2011 23:09