This documentation relates to an earlier version of FishEye.
View this page in the current documentation or visit the current documentation home.

Skip to end of metadata
Go to start of metadata

Welcome to FishEye 101, an introductory guide to FishEye and a tour of the most interesting FishEye features. Use this page to guide your evaluation process or quickly get up to speed with FishEye.

FishEye 101

Thanks for taking the time to try FishEye. To help you make the most of your time, we've taken the liberty of compiling some easy instructions for configuring and using FishEye. 

Software developers are the intended audience for this document.

FishEye 20 Minute Setup

Setting up FishEye takes less than half an hour.

1. Install

First things first, if you haven't already got FishEye up and running carry out the relevant steps below:

  For Windows: (click to expand)

Check Supported Platforms before you begin.

  1. Download FishEye from the Atlassian Download Center
  2. Unzip the downloaded package to the desired installation directory: c:\fisheye (see the documentation if you need help with this).
  3. Launch FishEye from the command line, typing start.bat. A FishEye console window will appear, listing the startup progress. Give it a few minutes to complete its process. When the message "server started" is displayed, you can continue.
    (info) You will also receive a warning in the console output about a 'missing license'. This is normal.
  4. On the same machine go to http://localhost:8060/ (or type the hostname or IP address in place of localhost from another machine) in your web browser. You will be prompted to enter a license key (obtained at http://my.atlassian.com) and set the admin password. (Tip: you can just use one Crucible evaluation license key to try both FishEye & Crucible.)

It should only take you a few minutes to have a running instance of FishEye. If you have any difficulty during the installation process (i.e. it takes longer than twenty minutes) please contact our support team for assistance. They're ready to help at any time.

  For Linux: (click to expand)

Check Supported Platforms before you begin.

  1. Download FishEye from the Atlassian Download Center
  2. Unzip the downloaded package to the desired installation directory: /opt/fecru-x.x.x (see the documentation if you need help with this).
  3. Launch FishEye from the command line, typing ./run.sh . Console output will appear, listing the startup progress. Give it a few moments to complete its process. When the message "server started" is displayed, you can continue.
    (info) You will also receive a warning in the console output about a 'missing license'. This is normal.
  4. On the same machine go to http://localhost:8060/ (or type the hostname or IP address in place of localhost from another machine) in your web browser. You will be prompted to enter a license key (obtained at http://my.atlassian.com) and set the admin password. (Tip: you can just use one Crucible evaluation license key to try both FishEye & Crucible.)

It should only take you a few minutes to have a running instance of FishEye. If you have any difficulty during the installation process (i.e. it takes longer than twenty minutes) please contact our support team for assistance. They're ready to help at any time.

2. Scan

  FishEye's fast performance is built on the way it scans repositories. (click to expand)

Once installed, FishEye needs to do an initial index, where it accesses, indexes and organizes a view of your repository (including all historical items) back to the earliest commit.

(info) FishEye operates in a completely read-only mode, so your repository data is safe. Also, always run FishEye on an SCM account that is limited to read-only access.

Click on the 'Administration' link in the footer bar to access the administration interface, then click 'Add Repository'.

There are lots of options when adding a repository, but in most situations you should be able to run with the defaults. For evaluation purposes, we recommend that you just index one project, which is usually a subset of your whole repository (rather than everything). If you choose to index your entire repository, just be aware that this can take a long time (possibly days) for massive or complex repositories and can be more complex to set up (especially for Subversion). Indexing just one project, you can have FishEye up and running quickly for evaluation. The basic process is slightly different for each SCM type. Carry out the respective process for your SCM below:

  • Subversion set the Path field to a subdirectory that includes the directories trunk, branches, tags for your project
  • Perforce & Git set the Path to a subdirectory that contains your project's source.
  • CVS set the CVS dir to point to your project.

The default indexing settings can have challenges digesting non-standard SCM configurations. If the initial index appears to hang, please call support as this usually indicates you have a configuration problem, that can be quickly resolved by our friendly support engineers.

3. Add Users

  You can automatically import users from an LDAP directory or similar. (click to expand)

FishEye was designed to improve team communication through sharing SCM artifacts, so you will probably want to add accounts for all your team members.  There are a few approaches that you can take to adding users:

  1. Leave FishEye in anonymous mode. There are two downsides here, anyone who can see FishEye, can see all the source and you won't be able to use email watches or save preferences.
  2. Built-in users with "public sign up". Anyone can create an account, but not especially secure.
  3. Built-in users. This is simple to set up for a small user base, however adding each user manually is not recommended for large-scale systems with many users.
  4. External authentication. This includes sources such as LDAP, Active Directory or similar.
    1. Atlassian Crowd. If you already have a Crowd server, this is a snap to set up.
    2. LDAP/Active Directory. You can point FishEye at your existing corporate directory. If you are familiar with LDAP, this should be easy.
    3. Host/PAM Authentication. You can use the local accounts from the physical machine FishEye is running on.

If you opt for accounts, be sure to make yourself and other relevant users FishEye administrators. You may also be interested in pre-loading users from LDAP/Crowd and setting repository level access control based on groups.

4. Configure Mail (optional)

  Email notifications are a great way to keep up with FishEye activity. (click to expand)

FishEye can deliver email feeds based on user configured parameters. For example, you can watch the contributions of a specific colleague or changes to a branch of code you're working on. To take advantage of this feature, you will need to tell FishEye about your SMTP server.

5. Configure JIRA (optional)

  FishEye integrates with JIRA, Atlassian's enterprise issue tracker. (click to expand)
  1. If you already have a JIRA server set up, you can go ahead and set up integration between the two. Once established, activity on relevant JIRA issues will appear in the FishEye activity stream. JIRA issue keys will also be hyperlinked, also a small information window will load when you mouse-over JIRA issue keys.
  2. Visit the FishEye documentation for instructions on how to set up JIRA integration in FishEye.

6. Setup Complete!

  Your FishEye instance is now established. (click to expand)

Congratulations! Our support records indicate that over 80% of support calls happen during this installation phase. Once you have made it this far, the rest of the evaluation ought to flow smoothly.

If you do need assistance, our support team is ready to help. Create an issue at our support system under the FishEye project.

There are heaps of tweaks and configuration options that you can experiment with. Check out the FishEye Administrator's Guide for more information.


Browsing Your Code Repository

In essence, FishEye is a tool that lets you view the contents of your Source Code Management (SCM) repository as a web page. Everything in your SCM is accessible in your web browser, quickly and easily.

7. Browsing & History

  Power-browse your repository. (click to expand)

Fisheye's Windows Explorer-style interface allows you to efficiently navigate your source tree and view the depths of your repository in a structured way. Select a file to view its entire revision history. See the documentation for more.

8. Full Source View

  View the full source of any file revision. (click to expand)

See the blame information associated with every line (allowing you to pinpoint who is responsible for every change). Author and age can be displayed as an aid to annotation. See the documentation for more.

9. Changesets & Diffs

  See every change and collaborate anywhere on the web. (click to expand)

Every commit and any diff can be viewed and easily linked to. This removes ambiguity from discussions in other mediums (such as discussions held via instant messaging, wiki pages, email, issue trackers and so on). See the documentation for more.


Activity & People

FishEye adds a modern social web dimension to the usually impersonal data stored in your Source Code Management (SCM) repository.

10. Activity Streams

  You can see commits and updates from the users in FishEye rolling by. (click to expand)

This information appears as a stream on the Dashboard and other index pages, sorted chronologically showing you the latest changes. Updates can be viewed as an inline stream or RSS feed. See the documentation for more.

11. People Lists

 In FishEye, you can view useful updates and statistics from your team. (click to expand)

On the People index page, you can see the commit history in global lines of code (LOC) that each person has contributed (expressed as a line graph) and their total number of commits. Also, the most recent piece of activity is shown as a clickable item. See the documentation for more.

12. People Pages

  Each person who makes code changes has a page. (click to expand)

You can click on a person's name to see detailed information about their additions to the repository, showing details of their work and summaries of their activity. Additionally, you can see their work on tracked issues and code reviews if using FishEye with Crucible and JIRA integration is set up. See the documentation for more.

13. Your Personal Dashboard

  See your own work at a glance and a stream of work items that are relevant to you. (click to expand)

Click the 'Dashboard' tab to see a stream of all your own activity; your personal code commits; your reviews (if you are using Crucible) and your tracked issue updates (if you are using JIRA). See the documentation for more.

14. Filtering The Changelog

  Quickly find what you're looking for. (click to expand)

Find the changes that you're seeking by filtering commits based on log message, path, author, date, branch (and other fields). This control is a snappy filter button under the Source tab.
See the documentation for more.


Reports & Search

Aggregate, audit and present your repository data with FishEye's powerful search and report functions.

15. Embedded Charts

  FishEye now shows charts in various locations. (click to expand)

Throughout the user interface, there are visualisations to help you view the activity in this area. The ubiquitous chart in FishEye plots net lines of code (that's just lines not NLOC for those who are interested) on the top and commit volume (the number of files committed) on the bottom. Note that this chart is generated on the fly based on what you are looking at, from the root down to individual files. On the changelog page the green bar shows you the period that is covered by the changesets on the page you are viewing. Clicking on the chart takes you to that point in time in your changelog.

See the documentation for more.

16. Custom Charts

  You can define specific metrics to be charted within FishEye. (click to expand)

To start using the more complex charts, click on the Chart tab on the right of the header, or "jump to detailed chart" on any of the baby charts. There is a lot of really cool stuff in these charts.

Some things to try:

  • Find out who your biggest contributors are - select "Show by Author" as a Pie chart.
  • See what file types you have committed - select "Show by Extension" then select your user ID as in the Author field.
  • See who has been changing the most lines in the last month - clear your selections and select "Show by Author" and a date a month prior in the "Start Date" field. If you have a lot of source the chart will probably be flat. If so, change the chart type to "Change", this will zero the line count at the start date.
  • Compare your changes against another person - pick yourself and another author (hold the 'control' key to select multiple) in the author list. This isn't very useful but can be a bit of fun!

Note that the committer gets a line for each line they add or change. The previous owner of a modified or deleted line loses one. Currently any change, even whitespace, counts.

See the documentation for more.

17. Plugin Reports

  FishEye is extensible, allowing you to create your own reports. (click to expand)

You can create your own report as a plugin and have it appear in the menu, under the 'Source' tab, and the 'Reports' sub-tab. For example, the 'Code Metrics' option that appears in the user interface is actually a plugin, added in to FishEye. You can use this plugin as a basis to create your own custom reports and add them in to FishEye. See the FishEye developer documentation for more.

18. Quick Search

  FishEye supports some powerful search commands. (click to expand)

The box in the top right corner of every page can be used to quickly search the repository. You can use syntax like author:anna to immediately return results which have "anna" in the author field. See the documentation for more.

19. Running Queries & EyeQL

  You can create complex queries with FishEye's own query language. (click to expand)

Clicking 'Search' on the top navigation bar opens the Simple Search screen. Here, you have access to a wide range of powerful searching functionality including file content searching, and grouping results by changeset, revision, file or directory.

Sometimes, you need data from your repository retrieved and sorted in ways that are unique to your own situation, beyond what the pre-fab GUI can give you. From the Simple Search screen, click 'Switch to Advanced Search'. Here, you can build searches using FishEye's powerful embedded query language, called EyeQL.
See the search documentation and EyeQL Reference Guide for more.

20. Leveraging CSV and the REST API

  You can export data and extend FishEye programmatically. (click to expand)

When you need to extract repository data for a report, you can export the results of FishEye searches to a CSV (comma-separated values) file which imports directly into spreadsheets and other office applications. Simply select the radio buttons at the bottom of the Simple Search dialog and the CSV file will be generated automatically, prompting you to save the file.

With its own API (Application Programming Interface), FishEye is extensible. If you need FishEye to do more than it ships with and you've got programming chops of your own, the API allows you to build extensions to the application to suit your needs. See the API documentation for more.


Tips and Suggestions

Learn about some of the smart labour-saving features in FishEye.

21. Quick Nav

  When you type in the search box, matches are instantly shown below. (click to expand)

You can quickly find what you are looking for by typing one word or part of the name of what you are looking for. FishEye's Quick Nav feature will immediately show matches and suggestions below, before you've even pressed Enter or activated a proper search. Try typing a CSID to go directly to that page. See the documentation for more.

22. Favorites as Bookmarks

  Everything in FishEye can be bookmarked. (click to expand)

See the documentation for more.

23. Context Windows

  A number of context windows appear when hovering your mouse over links. (click to expand)

Try hovering your mouse over the following links in FishEye to see the context windows:

24. Subscribe to SCM Updates

  Keep track of FishEye activity when your FishEye session is closed. (click to expand)

Every user can keep an eye on changes from RSS Feeds and Email Watches to the source directories that interest them or even individual files. The idea is to encourage people to subscribe to the level of notifications that suits them so the signal isn't lost in the noise. Here are two ways to test this out:

1. Set up a customised feed by going navigating to the changelog page. On the upper right hand corner of the changelog box, click on the Customised Feed URL. Fill in the feed attributes and use the constraints to get data about a specific users contributions to a specific branch of code. Select to subscribe either as an RSS feed or an email watch. For fun, you can comment on their code the moment they commit until they can't take it anymore.

2. Simulate a spontaneous watch request by surfing through the directories. Once you find an interesting contribution, hit the RSS button on the upper right hand corner of the changelog box to get updated on that particular file.

See the documentation for more.

25. Send Links to Your Code

  Everything in FishEye can be linked. (click to expand)

A changeset, a diff, even a specific line in a specific revision can be linked. You'll find a lot of stuff is underlined. Keep this in mind as you evaluate FishEye, there are plenty of links that are crying out to be copied to clipboard and sent on to your teammates.

If you look at the URL structure, you'll see that FishEye URLs are very predictable and hence can be easily generated by hand. There are also some extra wrinkles that are great for bookmarks.

Useful Hacks:

  • Every line in an annotation is a permalink to that line, clicking the revision number in the gutter takes you to that line in the revision it was last changed (even when the line number is different). Add a post commit hook in your SCM that gives developers the FishEye link as soon as they commit.
  • Using the keyword HEAD will give you the latest version of file.
  • Use branch or tag names in place of revision numbers in diffs.
    See the documentation for more.


Advanced Features to Try

26. Advanced Configuration Options

  FishEye has bucketloads of configuration options. (click to expand)

The FishEye developers try and set sensible defaults so that everything "just works" in most situations. However, if you are a power user, there are lots of knobs to twiddle. Check out the documentation below to learn about the nitty gritty.


Thank you for reading this guide.

Thanks for taking the time to evaluate FishEye using this guide. To help continue your journey, our support staff are always ready to answer your questions in the FishEye Forum, or solve specific problems at our support portal http://support.atlassian.com.

  • No labels