SVN tag and branch structure

FishEye automatic presets

FishEye provides automatic presets that match those defined in the Subversion Red Book (at http://svnbook.red-bean.com/en/1.1/ch04s07.html#svn-ch-4-sect-7.1).

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.

See Interpreting multiple rules below.

Introduction to Subversion conventions

The most common repository structure in Subversion is to 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

If you are 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 following:

1. If you point FishEye at your project root:

/PROJECT1

and you have the following structure at this level of the repository:

trunk
branches
tags

Then 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 structure:

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), then use FishEye's built-in rules for easy, one-step configuration.

3. Otherwise, you have a custom layout.

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 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. See Interpreting multiple rules below.

See the examples below for more information.

Interpreting multiple rules

See also Custom layouts above.

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 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

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

trunk(/|$) 

trunk

branches/([^/]+)

${1}

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

${2}

Custom example 2

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

core/trunk(/|$) 

trunk

core

plugins/([^/]+)/trunk(/|$) 

trunk

plugin_${1}

core/branches/([^/]+)

core-${1}

core

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

${1}-${2}

plugin_${1}

core/tags/([^/]+)

core-${1}

core

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

trunk/([^/]+) 

${1}

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

${1}-${2}

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

${1}-${2}

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.

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.