Documentation | 2025.1

# Notable minor features

## Quick URLs

Swarm handles URLs intelligently to reduce the amount of information you need to enter to quickly locate what you are looking for:

1. Enter a URL in the following format:

https://myswarm.url/<identifier>

2. Swarm checks the `<identifier>` and redirects you to the first match it finds. Swarm checks for the identifier in following order:

   - Reviews
   - Changelists
   - Depot paths
   - Projects
   - Jobs
   - Users
   - Groups
   - Depot names

- Changelist and review identifiers must be numeric.
- If you enter an identifier that does not exist for any type of resource, Swarm displays a Page Not Found error.

### Example usage

#### Display the latest version of a review

For example, to display review 124: enter the URL `https://myswarm.url/124`, Swarm redirects to `https://myswarm.url/reviews/124`.

- To display a specific version of a review, enter the full URL including reviews and append /v<n>/to the URL. For example, to display version 2 of review 124: enter `https://myswarm.url/reviews/124/v2/`
- To display a diff between two versions of a review, enter the full URL including reviews and append /v<n,n>/ the URL. For example, to display the diff between version 2 and 4 of review 124: enter `https://myswarm.url/reviews/124/v2,4/`
- To open a review with a specific tab open, append #<tab name> to the end of the URL (#<tab name> must be the last item in the URL):
  - Files tab: #files (default if #<tab name> is not specified)
  - Comments tab: #comments
  - Activity tab: #activity

#### Display a changelist

For example, to display changelist 123: enter the URL `https://myswarm.url/123`, Swarm redirects to `https://myswarm.url/changes/123`.

To open a changelist with a specific tab open, append #<tab name> to the end of the URL:

- Files tab: #files (default if #<tab name> is not specified)
- Comments tab: #comments

#### Display the latest version of a file

Enter the URL `https://myswarm.url/depot/alpha/readme.txt`, Swarm redirects to `https://myswarm.url/files/depot/alpha/readme.txt`.

- To display a specific version of a file, enter the full URL including files and append ?v=<n> to the URL. For example, to display version 2 of the depot/alpha/readme.txt file: enter `https://myswarm.url/files/depot/alpha/readme.txt?v=2`
- To open a file with a specific tab open, append #<tab name> to the end of the URL (#<tab name> must be the last item in the URL):
  - View tab: #view (default if #<tab name> is not specified)
  - Commits tab: #commits

#### Display the user profile page for jsmith

Enter the URL `https://myswarm.url/jsmith`, Swarm redirects to `https://myswarm.url/users/jsmith`.

## Links in descriptions and comments

When you write a job description, changelist description, review description, or comment, you can link to users, groups, changelists, reviews, and jobs. Swarm will attempt to automatically create links to your references to make it easy to navigate to the specified resource.

In this section:

- @mentioning users and groups

- Linking to a review

- Linking to a review, changelist, or numeric userid

- Linking to a job

### @mentioning users and groups

To link to users or groups, use `@mention` to refer to users and `@@mention` to refer to groups when you write a job description, changelist description, review description, or comment. Swarm automatically creates a link for each @mention and @@mention.

When you start a code review, including a user `@mention` or a group `@@mention` in the changelist description automatically makes them reviewers for that code review. During a code review, including a user `@mention` or group `@@mention` in a comment causes the mentioned user or group to receive notifications of code review events, even if they are not a member of your project or following you or your project.

Additional option for a user `@mention`:

- @*mention: include an asterisk (`*`) before the userid to make the user a required reviewer. See Required reviewers for details.

Additional options for a group `@@mention`:

- @@*mention: include an asterisk `*` before the groupid to make the group a required reviewer with All votes required. See Required reviewers for details.
- @@!mention: include an exclamation mark `!` before the groupid to make the group a required reviewer with One vote required. See Required reviewers for details.

- Group mailing list enabled: notifications are sent to the group email address.
- Group mailing list disabled: notifications are sent to the group members individual email addresses.

### Linking to a review

Adding #review-<reviewid> to a changelist description is a special case and does not just add a simple link to the review. It replaces all of the files in the review with the files in the changelist. For information about adding a changelist to a review, see Add a changelist to a review.

To make a simple link to the review, use review-<reviewid>.

To create a link to a review, add one of the following patterns to a job description, review description, or comment:

- #review-<reviewid>

  For example, when you include #review-12345 in a review description, Swarm automatically turns that text into a link that, when clicked, displays the Review page for review 12345.

- review-<reviewid>

  For example, when you include review-12345 in a review description, Swarm automatically turns that text into a link that, when clicked, displays the Review page for review 12345.

- review <reviewid>

  For example, when you include review 12345 in a review description, Swarm automatically turns that text into a link that, when clicked, displays the Review page for review 12345.

- @<reviewid>

  For example, when you include @12345 in a review description, Swarm automatically turns that text into a link that, when clicked, displays the Review page for review 12345.

### Linking to a review, changelist, or numeric userid

If you add #<numericid> to a job description, changelist description, review description, or comment. Swarm automatically creates a link to the page for the numeric id specified if a match exists.

Swarm checks the numeric id specified and links to the first match it finds. Swarm checks for the numeric id in the following order:

- Reviews

- Changelists

- Users

For example, when you include #12345 in a comment, Swarm turns it into a link to the page for either review 12345, change 12345, or user 12345, depending on which of them exists.

### Linking to a job

To create a link for a job, add jobnnnnn or @jobnnnnn to a job description, changelist description, review description, or comment. Swarm automatically creates a link to the job page if a match is found.

For example, when you include @job12345 in a comment, Swarm turns that text into a link that, when clicked, displays the Job page for job12345.

If your job numbers are not formatted as jobnnnnn, your Swarm admin can configure Swarm to recognize other keywords in addition to job. For example, if your job numbers are formatted as defectnnnnnn. For instructions on adding a new job keyword to Swarm, see Job keywords.

## Search

Swarm can search for users, groups, projects, and file paths. Enter keywords or path elements into the search box in the Swarm header. Navigate the results with the ↑ (up arrow) and ↓ (down arrow) keys. To display the details for a result, press Enteror click the search result.

Full-content searching is only available if your Swarm administrator installs the Helix Core Server Search Tool. See Search for details.

Swarm updates the search results as you type. Some results should appear within a second or two. You may have to wait a few seconds for final results to be incorporated into the results list. When Swarm does not yet have any results, it indicates such.

## Jira integration

Swarm ships with a Jira module that can:

- create links to Jira when Swarm displays Jira issue identifiers in changelists, jobs, reviews, etc. Jira links in comments are only supported in the classic Swarm review page.
- add links within Jira back to Swarm, for Jira issues associated with reviews or committed changes. These links reflect the current status of associated code reviews.

By default, the Jira module is disabled. For instructions about enabling Jira integration, see Jira.

## Avatars

Each event in an activity stream includes an avatar, an image that represents the user responsible for the event. Avatars help to visually tie together various events and personalize the history presented in the stream.

Based on the email address entered in a user's or group's Helix Core Server account, Swarm attempts to fetch an avatar from gravatar.com. Swarm selects an avatar from its collection of default avatars if an avatar is not returned from gravatar.com.

Hover your mouse over an avatar to display the fullname of the user or group.

## Following

Whenever you see a Follow button, for example when you are viewing a project page or user profile, clicking the button causes Swarm to send you notifications whenever there is activity generated by the current resource.

This is useful if, in the case of a project, you are not a project member but want to know what's happening in the project. Or, in the case of a user, you want to see what activity that user generates.

To stop receiving notifications, visit the project page or user profile and click the Unfollow button.

## Time

Swarm typically displays the time of an event, such as when a file was created, as about X units ago. Hover your mouse pointer over a time display to see a tooltip displaying the exact date and time of the event.

Configure Swarm to display the exact time and date of events by setting Time Display to Timestamp on your user Settings tab.

## Keyboard shortcuts

Swarm provides the following file control keyboard shortcuts:

Keyboard shortcut | Usage
--- | ---
Alt + H | Opens the shortcut dialog that displays a list of all the keyboard shortcuts for Swarm. See Show the shortcut help dialog.
Shift + Alt + L | Toggles to open or close the file list. See File list.
Shift + Alt + S | Toggles to open or close the Information panel. See Information panel.
Alt + R | Marks a file as read. See Mark file as read.
Alt + T | Opens file in a new tab. See Open content in a new tab.
Alt + N | Scrolls to the next file in the list while viewing a review. See Navigate to the next file.
Alt + P | Scrolls to the previous file in the list while viewing a review. See Navigate to the previous file.
Shift + Alt + F | Toggles to expand the Diff view to full screen or collapse the Diff view. See Expand the Diff view to full screen.
Shift + Alt + E | Toggles to expand or collapse all files in a review. See Expand or collapse all files in a review.
Alt + L | Toggles to show diffs in-line or side-by-side. See Show diffs in-line or side-by-side for a file.
Alt + W | Toggles to show or hide whitespace and tab characters for all text files in a review. See Show or hide whitespace and tab characters for all files in a review.
Alt + D | Toggles to show or hide whitespace diffs for all files in a review. See Show or hide whitespace diffs for all files in a review.
Alt + C | Toggles to show or hide all the inline file comments. See Show or hide all in-line comments for all files in a review.
N | Scrolls to the next difference while viewing Diffs.
P | Scrolls to the previous difference while viewing Diffs.
ESC | Closes the dialog while you are viewing a dialog. Stops text entry while you are entering text into a text area.

## About Swarm

You can discover the version of Swarm you are using:

1. Log in to Swarm.

2. Click your userid, found at the right of the main toolbar, and select About Swarm.

   A dialog appears displaying the Swarm version.

## Custom error pages

If Swarm encounters an error during processing, such as when a Quick URLs is used that points to a non-existent resource, Swarm displays a custom error page.

## Short links

Swarm provides a short link feature that creates shorter URLs than normal to make sharing specific views within Swarm easier. It is also possible to register or configure an alternate, shorter hostname to have even shorter URLs. See Short links for details.

Conceptually, this is identical to TinyURL, or the Twitter feature t.co domain, but is restricted to Swarm URLs on a hostname you control.

Swarm displays a bookmark button when viewing files or folders in the depot.

Click the button to display a popup containing the short link. Press CTRL+C (on Windows and Linux), or Command+C (on macOS), to copy the short link. You can then paste the short link anywhere you'd like to share the current file or folder view in Swarm.

Your search for returned results