FishEye 2.3 : SVN Tag and Branch Structure
This page last changed on Jul 08, 2010 by kburke.
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: OverviewSubversion, 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.
Jump straight to the examples, if you're already very familiar with Subversion and FishEye. Otherwise, please read on. Introduction to Subversion conventionsThe 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.
Choosing the correct configuration methodUnsure 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
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 layoutUsing 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:
You can add as many rules as you need. For any given file, the first rule that matches is used.
See the examples below for more information. ExamplesThese 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 exampleIf 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
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
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
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 customerThis 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
How Subversion worksSince 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 QuestionsWhat is the logical path prefix? What is the logical tail? How does the logical tail affect the search? |
![]() |
Document generated by Confluence on Jul 29, 2010 02:16 |