The Files tool displays the files in the active terminal's current directory, as reported by termy-server. The Files tool also displays the current directory itself, a count of files and directories, the name of the selected file (if any), and optional git information in a "banner" line at the bottom of the tool. If the FileColorize profile setting is enabled, filenames are shown using the configured Dircolors. If FileGittify is enabled, git status information for each file will be shown as a character whose color can be customized using extended dircolors. Note that termy-server must have libgit2 support enabled for git status information to be reported.

The Files tool provides access to filesystem actions such as download, upload, open, delete, rename, and more. Through the TermySequence protocol, these file operations work regardless of whether the active terminal is on a local or remote server, and regardless of how many hops separate your machine from the server. It's even possible to mount remote files using FUSE and edit them directly using local desktop applications. Install termy-server in your containers and on your remote servers; you won't miss typing in scp(1) commands from scratch.

Files are displayed in ls-like format; either short or long, depending on the FileDisplayFormat profile setting. The display format can be changed from the context menu or Tools menu or by calling SetFileListingFormat or ToggleFileListingFormat. Further settings for the Files tool are located under the Files/Files Tool category in the Global settings and under the Files category in the Profile settings. Via global settings, certain actions can be configured to run on a double-click, Control-click, Shift-click, or middle-click of a file.


The Files tool does not work across plain ssh(1) connections made directly from the command line. In this case, the current directory of the SSH client itself will be shown, not the current directory on the remote server. qtermy will attempt to detect this condition by matching the hostname reported by shell integration with the hostname of the terminal's server. For best results, install termy-server on remote machines and use TermySequence connections.

The Files tool is both navigable and searchable, having a current selection that can be moved and acted upon using generic or tool-specific actions. Searches entered into the tool search bar will filter the list of files, showing only those files whose names match the search string. Files can be sorted in ascending or descending order by name, size, modification time, and several other fields from the context menu or Tools menu, or by calling SetFileListingSort. In long format only, click a table column header to sort, drag table column headers to reorder them, and use the header's context menu to show and hide individual columns. If the table header is not visible, show it using Tools→Display or ToggleToolTableHeader.

termy-server and qtermy support OSC 8 hyperlinks, which can be produced by recent versions of GNU ls using the --hyperlink argument. For versions of ls without hyperlink support, the LsPlugin semantic parser plugin distributed with qtermy creates semantic regions having the same effect. Both of these solutions provide access to the same file actions as the Files tool directly within the terminal viewport itself.

If a file has been selected either within the Files tool or by clicking a semantic region with an associated file:// URL, it will be shown in the banner line alongside or in place of the current directory. The Files tool can be configured to autoraise itself when the selected file changes. Any semantic region within the terminal viewport whose URL matches the selected file in the Files tool will be displayed with a "selected" border.


It's possible for the selected file in the Files tool to be located outside of the active terminal's current directory. This can occur when clicking on a semantic region with a file:// URL. When this happens, the notation "not in cwd" will be displayed in the banner line.

The nearby figures show the Files tool in a typical situation. In the first figure, a git working tree is shown in short display format using the Default Dark theme. Note the git status characters displayed next to some files which are modified, staged, or ignored. In the second figure, the same directory is shown in long display format using the Solarized Light theme.

Picture of Files tool showing files in short display format.

Example of a typical Files tool in short display format with git status information.

Picture of Files tool showing files in long display format.

Example of a typical Files tool in long display format with git status information.

If a mouse click type is configured in the Global settings to "Open file or write cd command to terminal," a cd command will be written to the terminal if a directory is clicked within the Files tool, including pathname components shown in the banner area. By default, this feature is set as the action for double-click (your Global settings may differ) and allows directory navigation to be performed without typing cd commands. Note that this feature does not apply to semantic regions within the terminal viewport itself.

To ensure reasonable performance, termy-server's directory monitor has a size limit configurable via the DirectorySizeLimit profile setting. If the number of files in the current directory exceeds this limit, the Files tool will display a message allowing the limit to be raised on a case-by-case basis.

Changes to individual files may be reported by the server if it supports filesystem event monitoring (on Linux, inotify(7) is used for this purpose). If the FileChangeEffect profile setting is enabled, a brief animation will be displayed in the Files tool when a change notification is received for a file. Removal notifications are also supported; they will cause files to be removed from the list.