Files

Helix Core Server's primary task is to version files, so Swarm makes it easy to browse the depot A file repository hosted on the Helix Core Server. A depot is the top-level unit of storage for versioned files, which are also known as depot files, archive files, or source files. It contains all versions of all files ever submitted to the depot, including deleted files (but not obliterated files). There can be multiple depots on a single installation.. Start browsing by clicking Files in the menu.

Swarm displays a list of breadcrumb links to help you quickly navigate to higher level directories quickly.
Links with folder icons represent directories of files within the depot. Click a directory link to display the contents of that directory.
Click the .. link with the up-arrow icon , when it appears, to navigate to the current directory's parent.
Links with dog-eared page icons represent individual files within the depot. See File display for more information.
Click the Commits tab to display the list of changes made to files in the current directory, or any directories it contains. See Commits for more information:

Swarm creates links for files and directories wherever they appear in the Swarm UI.

Note

Directories that start with a period, for example .foo, are sorted to appear at the end of the list of directories. The .. link, when it appears, always appears first.

Similarly, files that start with a period, for example .htaccess, are sorted to appear at the end of the list of files.

Browsing deleted files and folders

When the Show Deleted Files button is clicked, Swarm toggles the inclusion of deleted folders and files in the file display.

Deleted folders and files are presented slightly muted compared to non-deleted entries:

File display

When Swarm is asked to display a file, if the file is a type that Swarm can display, Swarm presents the file's contents.

Buttons: the actual buttons displayed depends on the file type you are viewing.

Click the Shorten URL button to display a short-link to the file.
Click the Blame button to add a column to the display that identifies the userid responsible for each line of the file.
Click the Open button to display the file content with no surrounding page markup.
Click the Edit button to edit the file, see File edit.
Click the Download .zip button to download a compressed version of the file, see Download files as a ZIP archive.
Click the Download button to download the file.

When a file is opened it will by default be truncated to 1 MB in size. This limit can be increased (or removed) via the Swarm configurables. See Files configuration for details. This limit does not apply to downloaded files.

Along with the file name, Swarm displays the version number for the currently displayed file in the breadcrumb. For example, the following breadcrumb indicates that version 2 of Jam.html is being displayed:

If the version of a file being previewed has been deleted, the version number is displayed in red.

Every version of a file is available on the Commits tab.

Text files

Swarm displays the contents of text files (including the Helix Core Server filetypes unicode and UTF16) with line numbers. When possible, syntax highlighting is applied to make identification of various elements within the file easier.

For more information on the supported extensions for syntax highlighting in the Review page, see Supported syntax highlighting in the Review page.

For more information on Helix Core Server filetypes, see File Types in Helix Core Command-Line (P4) Reference.

Tip

Swarm can be configured to display some non-UTF8 characters, see Non-UTF8 character display for details.

Click Blame to add a column to the display that identifies the userid responsible for each line of the file:

Each userid presented is a link that, when clicked, displays the changelist that provided the associated text. Muted userids indicate that the associated text is from the same changelist as the line above. For example, the userid allison.c is responsible for lines 1, 10, and 12 in the screenshot above.

When you hover your pointer over a userid in the blame column, a tooltip appears displaying the associated changelist description:

The changelist associated with the current line

When there are no lines displayed, for example when you are viewing empty or shelved files, the Blame button is disabled.

Markdown files

Swarm displays Markdown files in two tabs:

Markdown: by default, Markdown content is displayed but it is limited to prevent the execution of raw HTML and JavaScript content. This can be configured by the Swarm administrator, see Markdown. This tab is only displayed for Markdown files.
View: displays the contents of Markdown files as plain text in the same way as Text files are displayed.

Tip

Valid Markdown file extensions are: md, markdown, mdown, mkdn, mkd, mdwn, mdtxt, mdtext.

Markdown tab

Click the Markdown tab to view the file content in Markdown:

Image of a Markdown tab

View tab

Click the View tab to view the Markdown file in plain text:

Image of the View tab for a Markdown file

Images

Swarm displays web-safe images:

The checkerboard background in this example is not part of the logo; it helps identify where transparency exists.

Many browsers can display SVG images with no additional plugins, so Swarm attempts to display SVG images rather than displaying the image's definition. When you use a browser that cannot natively display SVG images, you see the broken image icon.

When imagick (an optional module that integrates ImageMagick into PHP) is installed, Swarm can also display the following image formats: BMP, EPS, PSD, TGA, TIFF.

3D models

Important

You can view the 3D model file types only in the classic view of the Swarm review page. Use Helix DAM, a digital asset management software solution by Perforce to view 3D model files. For more information about how to use Helix DAM, see Helix DAM User Guide.

Swarm includes support for displaying select 3D model file types in the browser:

Supported file types include:

DAE - including any referenced web-safe texture images.
STL - both binary and ASCII versions of the format.
OBJ - including any referenced MTL files, and web-safe texture images.

When Swarm can display a 3D model, it renders a generic grid stage and places the model in the center, scaled to make viewing straightforward. A toggle control appears in the top right: when enabled, you can control the view with the mouse, and when not enabled, permits auto-rotation to occur (when possible).

Click and hold the left mouse button to begin rotating the view. Drag while holding the left mouse button to rotate the view.
Click and hold the right mouse button to begin panning the view. Drag while holding the right mouse button to pan the view.
Roll the mouse wheel up or down to adjust the magnification of the view.

When possible, a second control appears allowing you to toggle between showing the model with surfaces, or just showing the model's wireframe.

Note

For systems with hardware acceleration, if your browser supports WebGL and hardware acceleration is enabled, Swarm renders the model and enables auto-rotation.

For systems without hardware acceleration or WebGL, but your browser supports HTML5 canvas elements and JavaScript TypedArrays, Swarm renders the model but auto-rotation is disabled. Rendering is likely to be slow and rendering quality is likely to be low.

For browsers without HTML5 canvas elements and JavaScript TypedArrays, no rendering is attempted; instead, users see a message indicating that the browser is not supported.

Other file types

It is possible to view other file types in Swarm, through the addition of additional modules, or by installing LibreOffice on the Swarm host.

When the file is a type that Swarm cannot display, Swarm presents the file's history, along with the Download button:

Image of a file that cannot be displayed

File edit

Important

File edit is a Technology Preview feature.

Features offered in Technology Preview are experimental and not guaranteed to always work as expected. If you have feedback and functionality suggestions, email techpreview@perforce.com.

Note

Requirements:

You must have permissions to edit the file.
If the file version changes while you are editing it or if you are not editing the Head The most recent revision of a file within the depot. Because file revisions are numbered sequentially, this revision is the highest-numbered revision of that file. revision of the file, committing your file changes will overwrite the current head revision of the file.

If you are unsure, shelving your change is a safer option because it will not overwrite the head revision of the file and you can do a manual resolve when you commit the shelf.

File edit from the Files browser page is enabled by default but can be disabled by your Swarm administrator, see allow_edits.

You can edit a file from the Swarm Files browser page and shelve or commit your file changes.

To edit a file from the Swarm Files page:

Navigate to the file on the Files page.
Click the Edit button above the file to open the file editor.

Image of the Edit file dialog

Edit the file and add a Changelist description.

Tip

Optional: you can create a review for your change or add it to an existing review by including a review keyword in the Change description. For instruction on creating a review and adding a changelist to a review using review keywords, see Create a review and Add a changelist to a review.

Click Commit to commit the file or Shelve to shelve the file.

To discard your changes, click Discard changes and confirm that you want to discard your changes when requested.

Download files as a ZIP archive

The Download .zip button is used to download the selected files or folders in the Helix Core Server as a ZIP archive. This makes it easy to get a copy of files without having to setup a client.

Note

The Download zip option is not displayed if the zip command-line tool is not installed on the Swarm server. For information about installing, and configuring the zip command-line tool, see Zip archive.

When you select the Download zip option, Swarm performs the following steps:

Scans the files/folders:
- Checks that you have permission to access their contents, according to the Helix Core Server protections.
- Checks that the total file size is small enough to be processed by Swarm.
Syncs the file contents to the Swarm server from the Helix Core Server.
Creates the ZIP archive by compressing the file content.
Starts a download of the generated ZIP archive.

Note

You might not see all of the above steps; Swarm caches the resulting ZIP archives so that repeated requests to the same files/folders can skip the sync and compress steps whenever possible.
If an error occurs while scanning, syncing, or compressing, Swarm indicates the error.

Supported syntax highlighting in the Review page

This section outlines a list of all the supported extensions for syntax highlighting in the Review page.

File type	File extension
c	c, h
java	java
python	py
cpp	cc, cpp, hpp
csharp	cs, dotnet
actionscript for flash	fla, as
batch	bat
powershell	ps1, psm1, ps, psm
yaml	yaml, yml
markup	xml, htm, html, phtml, md, markdown
visualBasic	vb
javascript	js, javascript
jsx	jsx
php	php
matlab	mat
lua	lua
vhd1	vhd1
rust	rust, rs, rlib
docker	dockerfile
shell	sh
ruby	rb
perl	pl
typescript	ts
tcl	tcl
unreadscript	uc