SpaceFM

Homepage
Downloads
News
Wiki
Report Issues
README
User's Manual
 SpaceFM User's Manual

This manual uses your browser's default settings for fonts, font sizes, and colors.

TIP: For help within SpaceFM, right-click on a menu item and select Help. Or, highlight the menu item (hover your mouse cursor over it) and press F1. Some dialogs also include a Help button which links to this manual.


DISCLAIMER
While the authors, copyright holders, and maintainers of this software endeavour to keep all content up to date and valuable, we make no representations or warranties of any kind, express or implied, about the completeness, accuracy, reliability, suitability or availability with respect to the software or the information, communications, products, services, or related graphics for any purpose. Any reliance you place on such content is therefore strictly AT YOUR OWN RISK.


Table Of Contents

Introduction Installation Invocation Quick Start GUI Devices Tasks Design Mode Plugins Handlers Dialog Sockets Program Files
Introduction
Contents Highlights

SpaceFM is a multi-panel tabbed file and desktop manager for Linux with built-in VFS, udev- or HAL-based device manager, customisable menu system, and bash integration. SpaceFM aims to provide a stable, capable file manager with significant customisation capabilities.

  • Flexible - Can appear very simple or very complex depending on configuration
    Inspired by the simplicity and clarity of PCManFM's interface, SpaceFM's GUI aims to be simple and uncluttered, while still providing extensive capabilities for power users and flexibility in window components, behavior, and appearance.
    • Each window may contain up to four independently configured, interactive browser panels *
    • Each panel supports multiple folder tabs
    • Optional side panes in each panel can show Devices, Bookmarks, and a Directory Tree
    • How many panels you want displayed, how they are arranged and sized, what each panel contains, and what fonts and icons are used is largely up to you. SpaceFM can be a window containing icons of a single folder's contents, or a multi-panel, tabbed arrangement of detailed file lists, devices, bookmarks, and folder trees. screenshots

  • Feature-Rich - Subtle power features to improve efficiency and abilities
    • Extensive file management features to move, copy, link, plus configurable drag-n-drop and unique clipboard functions
    • Video and image thumbnails
    • Find-As-You-Type search to quickly locate a file with a case-sensitive/insensitive search of filenames - just type a few letters, or use a wildcard pattern *
    • System management features to safely perform convenient commands as root: edit, copy, move, and delete files and folders as root, change permissions, and create links, or run a root instance
    • In-program archive creation and extraction (or use an external app)
    • File search - flexibly search system-wide for file names, sizes, content, etc. with no daemon required
    • Extended Rename dialog allows not only renaming, but moving, copying, and creating links, with optional root priviledges, and allows creation of new files and folders from templates *
    • Roomy dialogs for easy editing and viewing of long filenames, paths, and commands
    • Extended Path Bar uses tab completion and allows entry of full bash commands with substitution *
    • Powerfully manage how files are opened *
    • Sort options allow a natural sort and a case sensitive sort. Folders in the file list may be placed before or after files, or mixed with files, and hidden files may be placed before or after regular files.
    • Custom date display format; binary or SI decimal file sizes and copy speeds
    • Easily customise window titles and program icon

  • Extensible - Design Mode allows you to create your own file manager
    SpaceFM's unique extensible GUI rivals the flexibility and capabilities of the Linux command line. Using SpaceFM and making gradual adjustments as you go, you become the designer of your own version of the file manager.
    • Almost every built-in menu and toolbar item can be renamed or hidden from view, bound to any keyboard shortcut, and given a custom icon *
    • Add your own custom menu items and submenus to any position in most menus. Like word processor macros, custom menu items allow you to easily run commonly used programs or automate tasks using SpaceFM's unique integration with the bash scripting language, with file manager data exported as ready-to-use bash variables *
    • The Bookmarks menu and side pane can contain not only bookmarks, but submenus, custom commands to be run, and applications. *
    • With the built-in SpaceFM Dialog tool - a zenity-like tool but with much greater power - easily create, use, and control custom dialogs or mini-apps. *
    • Make your custom commands respond to window events and manipulate the GUI directly using socket commands *.
    • Monitor the stdout/stderr output of custom commands in a dialog, with error detection and popup control, or automatically run commands in a terminal or as an independent process. *
    • Plugins are available to extend SpaceFM's functions *, and creating or sharing a plugin is as simple as exporting any custom menu item you have created. *

  • Lightweight & Independent - Written in C with GTK+, udev and inotify support
    • Written entirely in C - super fast with low resource usage
    • Independent of particular distributions and desktop environments
    • Builds easily on almost all Linux systems
    • Builds with any version of GTK+ ranging from 2.18 to 3.x; relies only on stock GTK+ icons
    • Built-in virtual filesystem (VFS) code uses core C kernel functions for speed and reliability, with no dependence on gvfs, etc.
    • Interfaces directly with udev (or eudev) for device support, with no dependency on udisks; can also be built with deprecated HAL support instead of libudev
    • Built-in support for inotify-capable kernels (>=2.6.13), meaning there are no dependencies on file alteration monitors (fam, gamin, gvfs, etc). (For rare kernels without inotify support, can easily be built with deprecated fam/gamin support.)

  • Task Manager & Queue - Centralized multi-task queue and popup control
    • Rather than opening a popup dialog and making you wait while a copy or other task runs, SpaceFM's Task Manager lists all the tasks running in the current window (including copy speed and other statistics), freeing you to continue working *
    • Popup dialogs are shown when errors occur, or can be configured to be shown for all tasks *
    • To optimize performance, SpaceFM's task queue smartly pauses some tasks which involve devices already in use, or you can manually pause, queue, resume or stop any task *
    • Includes extended overwrite, auto-rename, and error handling options *
    • Provides a common interface to multiple su and graphical su programs, terminals, and editors - you simply select which tools you want to use, and SpaceFM handles the details of running your commands as other users, in a terminal, etc.

  • Device Manager * - Programmable device management
    • Single-click mounting and unmounting of devices *
    • Optional automatic mounting and opening of devices on insert *
    • Programmable event-based manager runs any commands or apps you specify on device or media insertion, mount, and removal *
    • customisable root functions to format, backup and restore partitions and MBRs, check filesystems, and change volume labels *
    • Custom format of display names for devices *, and hide or show any device *
    • Built-in udev (or eudev) support - can be used with udevil (a mount tool designed specifically for SpaceFM), pmount, udisks, or your custom mount solution *
    • When used without udisks, there is no need for policykit, consolekit, devicekit, gvfs, and other troublesome components susceptible to frequent breakage and misconfiguration
    • Add custom Device and Protocol handlers, and mount options based on fstype or device *

  • Desktop Manager - Includes a built-in, lightweight DM daemon
    Based on LXDE's former desktop manager, SpaceFM can conveniently manage the icons and wallpaper on your desktop, and supports a transparent background. Works great with Openbox and other WMs, and can be extended with custom menu items. *

  • Daemon Mode - Keep SpaceFM always running
    Run SpaceFM in the background as a daemon to auto-mount and auto-open devices, and quickly open browser windows on demand. *

  • Network Support - Mounts network filesystems and ISO files
    Conveniently mount network URLs (nfs:// ftp:// smb:// ssh://) and ISO files using the highly configurable udevil. Or, configure a custom protocol handler to mount networks using any external tools you choose, plus create custom protocols of your own. * NOTE: Network share support in SpaceFM is ad hoc by design. This means there aren't many built-in functions pertaining to networks, and SpaceFM does not make network connections itself. Network discovery and other functions are handled via plugins and your custom commands.



Contents History

SpaceFM was originally developed from a fork of the legacy PCManFM file manager. When PCManFM reached version 0.5.2 (aka 'the legacy version'), the original author (Hon Jen Yee) abandoned it for a major rewrite which made later versions (the 0.9.x series) dependent on gvfs and other components. At about this same time, PCManFM-Mod was created as a minor fork of the legacy version which added features, addressed bugs, and kept the legacy version alive for those who prefered it for its light dependencies and added features.

PCManFM-Mod was later used as a base for developing SpaceFM, which included an extensible user interface, multiple panel support, a new udev device manager, inotify support, and removed dependencies on fam/gamin and HAL. Much of the internal virtual filesystem (VFS), which had been developed and debugged in legacy PCManFM and PCManFM-Mod, was retained and extended, providing SpaceFM with a reliable VFS to build upon.

Due to the extensive changes in many parts of the project, SpaceFM was released with its new name as an alpha test version in January 2012.

With version 0.7.5 in April 2012, SpaceFM replaced udisks with direct udev support for device detection and information, and support for multiple mount solutions including udevil (a mount program developed specifically for SpaceFM), pmount, udisks v1 or v2, or any program you specify. When used with udevil or a custom protocol handler, this update also added support for network filesystems.

In 2012, the GTK3 version of SpaceFM was introduced. Rather than abandoning GTK2, users can choose what version of the GTK+ library (2.18 thru 3.x) they want to use with SpaceFM.

In 2013-2014, improvements included extending the features of SpaceFM's Desktop Manager, a new Item Properties dialog for adding and customising menu items, socket commands for interacting with a running instance, and an improved panel configuration memory.

In 2014-2015, customisable handlers were added, greatly extending SpaceFM's ability to open devices and protocols, and handle archives and files. Also, a new Bookmarks side pane was added to include submenus and more powerful bookmarks. Other changes included the addition of video thumbnails and a transparent desktop background mode.

Installation
Contents Downloads

SpaceFM is included in most distro repositories. To find packages, forum threads, and other info for your distro, see the Distros Wiki. If there are no packages for your distro, or you prefer to build SpaceFM with custom build options, a net installer is available. For manual installation, or to create a custom Debian package, please see SpaceFM's detailed README file.

SpaceFM's source code is distributed from Github.

You can also check the homepage, latest news and report issues.

The SpaceFM Wiki contains user-contributed plugins, help, and information. Everyone is encouraged to contribute to the wiki.

Contents Net Installer

If there are no packages for your distro, or you prefer to build SpaceFM with custom build options, a net installer is available. The installer MUST be run in a terminal. It automatically downloads, builds and installs, and will work with most distros.

From README: 

    Install required build dependencies (below are Debian package names -
    packages names on your distro may vary but should be similar):

        autotools-dev bash build-essential intltool pkg-config fakeroot
        shared-mime-info desktop-file-utils libc6 libcairo2 libglib2.0-0
        libglib2.0-dev libpango1.0-0 libx11-6 libx11-dev libudev1
        libudev-dev libffmpegthumbnailer-dev

    Also, if using GTK2: libgtk2.0-0 (>=2.18) libgtk2.0-dev libgtk2.0-bin

    OR, if using GTK3:   libgtk-3-0 libgtk-3-dev libgtk-3-bin

    Also, if you want to use startup notification: libstartup-notification0-dev
    
    RECOMMENDED: udevil|pmount|udisks gksu|kdesu|ktsuss|lxqt-sudo eject lsof
                 wget 

    For additional mounting support: fuseiso curlftpfs jmtpfs gphotofs ifuse

    To download the installer:

    wget https://raw.github.com/IgnorantGuru/spacefm/next/spacefm-installer
    # OR using curl:
    curl -L -o spacefm-installer \
           https://raw.github.com/IgnorantGuru/spacefm/next/spacefm-installer

    To run the installer (MUST be run in a terminal):

        bash spacefm-installer

    Most users can press Enter to accept default values at both prompts.

    The installer will display dependencies for your chosen build.  If
    any dependencies are missing, examine the error, install missing packages,
    and try again.

    If you have already downloaded the source, the installer can be run from
    within the source directory to automatically build and install:

        ./spacefm-installer

    When SpaceFM is installed, the installer is also installed to /usr/bin.
    For automated options, run:  spacefm-installer --help

    To reinstall or upgrade, just run the installer again.  For example, to
    upgrade to the latest rolling release, just run:

        spacefm-installer --version=next --prefix=/usr

    To uninstall:
	
        spacefm-installer --uninstall

    Note: When using older distros, enabling kernel polling may be required. If
    you insert a CD and SpaceFM still says 'no media', please see the ENABLE
    KERNEL POLLING section in README.


Contents Uninstall

If you installed from a package, use your package manager to remove SpaceFM. Or, use the installer to uninstall: 

    spacefm-installer --uninstall
Otherwise, run these commands AS ROOT:

(these commands assume you installed with the default --prefix=/usr - adjust as needed) 

    rm /usr/bin/spacefm /usr/bin/spacefm-auth  /usr/bin/spacefm-installer
    rm -r /usr/share/spacefm
    rm /usr/share/pixmaps/spacefm.png
    rm /usr/share/pixmaps/spacefm-*.png
    rm /usr/share/icons/hicolor/*/apps/spacefm.png
    rm /usr/share/icons/hicolor/*/apps/spacefm-*.png
    rm /usr/share/icons/Faenza/apps/48/spacefm.png
    rm /usr/share/icons/Faenza/apps/48/spacefm-*.png
    rm /usr/share/locale/*/LC_MESSAGES/spacefm.mo
    rm /usr/share/applications/spacefm*.desktop
    rm /usr/share/mime/packages/spacefm-mime.xml
    update-mime-database /usr/share/mime > /dev/null
    update-desktop-database -q
    gtk-update-icon-cache -q -t -f /usr/share/icons/hicolor


Invocation
Contents Command Line

To see SpaceFM's command line usage run spacefm --help 

Usage:
  spacefm [OPTION...] [DIR | FILE | URL | DEVICE]... 

Help Options:
  -h, --help                   Show help options
  --help-all                   Show all help options
  --help-gtk                   Show GTK+ Options

Application Options:
  -t, --new-tab                Open folders in new tab of last window (default)
  -r, --reuse-tab              Open folder in current tab of last used window
  -n, --no-saved-tabs          Don't load saved tabs
  -w, --new-window             Open folders in new window
  -p, --panel=P                Open folders in panel 'P' (1-4)
  --desktop                    Launch desktop manager daemon
  --desktop-pref               Show desktop settings
  --show-pref=N                Show Preferences ('N' is the Pref tab number)
  -d, --daemon-mode            Run as a daemon
  -c, --config-dir=DIR         Use DIR as configuration directory
  -f, --find-files             Show File Search
  --set-wallpaper              Set desktop wallpaper to FILE
  -g, --dialog                 Show a custom dialog (See -g help)
  -s, --socket-cmd             Send a socket command (See -s help)
  --profile=PROFILE            No function - for compatibility only
  --no-desktop                 No function - for compatibility only
  --version                    Show version information
  --display=DISPLAY            X display to use

Normally, your session file and other user files are saved in ~/.config/spacefm/ To make SpaceFM read and save your files in another folder (~/.config/spacefm-alt in this example), stop ALL instances of SpaceFM and run: 

    # first stop all instances:
    killall spacefm

    # then:
    spacefm --config-dir ~/.config/spacefm-alt

IMPORTANT: The config directory path may not contain spaces or other special characters - keep it simple. Also, if /etc/xdg/spacefm/ exists, its contents will be copied to the config directory if it doesn't exist at startup.

Contents Opening Windows

To open an initial SpaceFM window, run 'spacefm' with or without a folder specification: 

    spacefm

    # or to open a folder:
    spacefm /home

    # or to open several folders in tabs:
    spacefm /home /usr/bin

    # or to not open saved tabs:
    spacefm -n

To open an additional folder in a new tab of the last used SpaceFM window on the current workspace: 

    spacefm /etc

To open a folder in the current tab of the last used SpaceFM window on the current workspace: 

    spacefm -r /etc

To simply bring the SpaceFM window to the top of other windows: 

    spacefm -r

To open a second window: 

    spacefm -w

    # or to open a specified folder in a second window:
    spacefm -w /boot

    # or to open a second window without loading saved tabs:
    spacefm -wn

To open a File Search window: 

    spacefm --find-files

SpaceFM maintains a socket for each user/display combination, so when you open multiple windows using the same user and display, all windows are run from a single instance of SpaceFM. Unless a daemon or the desktop manager is running, SpaceFM will exit when all windows are closed.

When a window is closed, the current folder tabs are saved to your session file if option File|Save Tabs is checked. The next time you run SpaceFM, these folder tabs will be re-opened in addition to opening tabs for any folders you specify on the command line (unless you specify -n on the command line).

To specify a specific panel in which to open a folder: 

    # open a folder in panel 2:
    spacefm --panel=2 /usr/bin

To simply show and focus panel 2 in the last used window: 

    spacefm --panel=2

As a more advanced example, consider wanting to open multiple SpaceFM windows, each containing different folder tabs in each panel, using a single command. For this, use a script like this to start SpaceFM: 

    #!/bin/bash

    # open new window with two tabs in panel 1
    spacefm -wn --panel=1 /etc /usr &
    sleep 0.2
    # add two tabs to panel 2
    spacefm -rn --panel=2 /bin /lib
    sleep 0.2
    # open second window with two tabs in panel 1
    spacefm -wn --panel=1 /boot /media
    sleep 0.2
    # add two tabs to panel 2 of second window
    spacefm -rn --panel=2 /sbin /var
The sleep commands give time for the socket to be created and the newly created window to become the last used window. A shorter sleep time of 0.1 may also work on your system.

Contents Opening Files, URLs, and Devices

If you specify a file rather than a folder on the command line, SpaceFM will open the file using the default MIME application for this file type (File Handlers are not used), but will not open a SpaceFM window: 

    # open a file:
    spacefm /etc/fstab
To open a URL (see Protocol Handlers): 
    spacefm ftp://ftp.us.debian.org/debian/
To mount and open a device (see Device Handlers), or open an already mounted device: 
    spacefm /dev/sdd1


Contents GTK Themes

The GTK theme you're using may have a significant impact on SpaceFM's performance, and a non-working theme may create dysfunctional behavior. Because multiple panels in SpaceFM use many GUI elements, some themes cause SpaceFM to run more slowly. For example, the Clearlooks GTK2 theme has been observed to be very slow with SpaceFM, while the Raleigh theme is quite fast.

SpaceFM may be built to use GTK v2 or v3. To see if your installed copy of SpaceFM is using GTK2 or GTK3 themes, run spacefm --version

GTK 2
When using GTK2, it is possible to use a specific theme just for SpaceFM, overriding your default theme. For example, to use the Raleigh theme (if installed), run SpaceFM like this: 

    GTK2_RC_FILES=/usr/share/themes/Raleigh/gtk-2.0/gtkrc spacefm

You can also test SpaceFM's speed with no theme, which should be faster than any theme: 

    GTK2_RC_FILES="" spacefm

To specify a GTK2 theme within a desktop file, copy SpaceFM's desktop file to your home folder: 

    mkdir -p ~/.local/share/applications
    cp /usr/share/applications/spacefm.desktop ~/.local/share/applications/
    # OR
    cp /usr/local/share/applications/spacefm.desktop ~/.local/share/applications/
Then open ~/.local/share/applications/spacefm.desktop in your editor and set the Exec= line using env. For example:
Exec=env GTK2_RC_FILES=/usr/share/themes/Raleigh/gtk-2.0/gtkrc spacefm

GTK 3
When using GTK3, theme choice becomes especially important because themes are often broken with every minor GTK3 release, and a theme not made specifically for your current version of GTK3 can cause memory leaks, GUI glitches, and other severe problems visible in SpaceFM. To determine if your theme is the cause of problems, run SpaceFM in a terminal to see any warnings, and also compare behavior with Adwaita (default GNOME theme).

Contents Desktop Manager

SpaceFM includes a lightweight desktop manager to manage desktop icons and show wallpaper (or a transparent background). SpaceFM's DM works well with Openbox, for example, which doesn't include a desktop manager. To start a desktop manager daemon, first terminate any other software which is managing your desktop, then run: 

    spacefm --desktop

You can also run spacefm --desktop from your login script. For example, if you're using Openbox, add this line to ~/.config/openbox/autostart.sh: 

    ( spacefm --desktop ) &

While managing the desktop, SpaceFM's volume monitor will also be running, meaning that if configured to do so, it will automount devices.

To set the wallpaper from the command line, run a command like: 

    spacefm --set-wallpaper /home/user/wallpaper.jpg

To open the desktop preferences window from the command line run: 

    spacefm --desktop-pref

To stop management of the desktop prematurely (before logoff), send spacefm a quit signal: 

    killall spacefm
Like other menus in SpaceFM, Design Mode may be used in the desktop's right-click menu to add custom menu items and set key shortcuts (which will be active when the desktop has focus).

Contents Daemon Mode

If you want SpaceFM always running in the background, ready to quickly open windows and automount volumes, but don't want it to manage the desktop, start a daemon instance of SpaceFM: 

    spacefm -d

No window will open in this case, but an instance will be started if not already running, and it will continue running for the duration of your X login session. You can also start the daemon from your login script. For example, if using Openbox, add this line to ~/.config/openbox/autostart.sh: 

    (sleep 2 && spacefm -d) &

One particular use for daemon mode is to make sure leftover folders in /media are removed. SpaceFM can unmount removable devices on exit to prevent folders remaining in /media at shutdown (if you check option Settings|Auto-Mount|Unmount On Exit). If running as a normal instance, this means devices will be unmounted whenever you close the last SpaceFM window. When running as a daemon (or as a desktop manager daemon), devices won't be unmounted until you logoff.

To stop a daemon mode instance, send SpaceFM a quit signal: 

    killall spacefm


Quick Start
Contents Frequently Asked Questions

GUI
Contents Panels

SpaceFM includes up to four file manager panels in each window. Each panel represents a complete file manager, including tabbed directory contents and optionally shown side panes, toolbars, path bar, and status bar. Each panel can be hidden or shown via the View menu, or via the Panel Bar located to the right of the main menu bar.

If shown, panels 1 and 2 are next to each other in the top half of the window, and panels 3 and 4 are in the bottom half. This allows horizontally arranged panels, vertically arranged panels, and combinations of both.

NOTE: SpaceFM's main menu bar (File, View, etc.) is mostly used for program-wide settings and functions. Most adjustments for an individual panel's appearance can be made by right-clicking on the file list and selecting the View context menu (also available in the main View menu). This View menu will allow you to set which side panes and toolbars are visible in a panel, add and remove file list columns, set the list style and font, set the sort method, etc.

Panel Memory

The best way to use SpaceFM's memory for panel configurations is to select the panels you want visible, then arrange each panel as you want it to appear. Hide or show side panes and adjust their sizes, choose file list columns and adjust their widths, choose which toolbars are visible, etc. Each time you select a different combination of panels, you may need to do some further configuration until SpaceFM gets to know all the combinations you use and how you like them arranged.

How It Works

Many settings in each panel are specific to that panel. For example, a different font can be set for the file list or other panes in each panel. Also, each panel may have a different view style (Detailed, Compact, or Icons), different file list columns visible, different side panes visible, etc.

Some panel settings use a four-state memory, and these settings may be different depending on the panel's relationship to other panels in the window. The four states are:

  • panel is shown by itself in the window
  • panel has a horizonal neighboring panel
  • panel has a vertical neighboring panel
  • panel has both horizontal and vertical neighboring panels

The four-state memory of each panel allows SpaceFM to remember how you configured each panel in combination with other panels. This makes it easier to show and hide panels on the fly without having to readjust columns, side panes, etc. SpaceFM will remember the selected columns (visibility), column widths, side pane visibility and sizes, and toolbar visibility for each state of each panel.

For more advanced users, note that socket commands can be used to adjust panel configurations from a command or script. When set as event handlers, adjustments can be made automatically when GUI or other events occur, such as showing/hiding a panel or changing window size.

Maximized & Fullscreen

If you maximize the SpaceFM window, any changes to column widths are not remembered (in any panel or in the task manager). This means that you can change column widths while maximized, and when you return to an unmaximized window state, your columns widths will revert to their original sizes.

However, if you exit SpaceFM while the window is maximized, your column widths will be saved. When you restart SpaceFM it will open maximized, and any changes to column widths thereafter will be remembered while maximized (unless you unmaximize and maximize again).

In fullscreen mode, neither changes to column widths nor to side pane heights are remembered. When you return to non-fullscreen mode, these will revert to their original sizes.

Focus Highlighting
SpaceFM is designed so that for most purposes, it is not necessary to know which panel has the focus. By right-clicking in a panel, the context menu shown will be specific to that panel. (Window level commands and settings are available via the main menu bar.)

However, sometimes it is necessary to know which panel has focus, such as when using keyboard shortcuts on selected files, or using a custom command or plugin in the main menus. For this purpose, SpaceFM provides an icon at the right of each panel's status bar. This icon will be enabled for the panel which has focus.

If you would like a more prominent reminder, it is possible to set custom highlight colors for the focused panel's status bar text and background. To set highlight colors, right-click on the status bar of the panel and select Highlight Text or Highlight Bar. Each panel may use different highlight colors, or the same.

Contents Path Bar

SpaceFM's Path Bar (location bar) is located in each panel above the file list in the panel's main toolbar. At its simplest, the Path Bar allows you to see the current folder's path, and you can enter a new path and press Enter to change to another folder.

TIP: To place the cursor in the Path Bar, you can use Go|Focus|Path Bar, accessed from the right-click menu of the file list. By default, this is assigned to key shortcut Ctrl+L.

In addition to displaying and accepting a folder path, SpaceFM's Path Bar has additional methods and uses as detailed below.

Editing Keys
When the cursor is in the Path Bar, the following editing key combinations can be used:

Key Combo Result
Shift+Backspace Clear the entry
Ctrl+Backspace Backspace to the previous separator
Ctrl+Left Jump to previous separator
Ctrl+Right Jump to next separator
Tab Complete entry

When the Path Bar has focus, it will steal the following keypresses (even if they are set as key shortcuts): visible characters without a modifier key, Enter, Home, Shift+Home, End, Shift+End, Delete, Tab, Backspace, Left, Shift+Left, Right, Shift+Right.

Auto Seek
By default, the Path Bar will auto seek, which means that as you type in the Path Bar, the current directory will change automatically, and any partial filename typed will select the first matching directory or file found in the file list. You can turn off auto seek by right-clicking on the Path Bar and unchecking option Auto Seek. In this case, you will need to press the Enter key to change to the directory entered.

To locate files within the current directory, use Find-As_You-Type Search or Actions|Select By Pattern.

Completion
As you're entering a directory path in the Path Bar, completion will be active. For example, if you enter "/us", a drop down box will appear listing /usr (and any other directories that may begin with "/us" on your system). You can press Tab to complete the entry automatically ("/us" will be completed to "/usr/", or as much as possible if there are multiple matches). If multiple possibilities are listed, press Down Arrow to select the desired completion and press Enter (or select it using the mouse).

Breadcrumbs
The Breadcrumbs feature allows you to Ctrl+Click on a portion of the path in the Path Bar to trim the path back. This will also immediately change to the new path. For example, if the path is currently /usr/share/spacefm/plugins and you Ctrl+Click on the name 'share', the path will change to /usr/share. This provides a convenient way to go up to a specific directory.

Middle-Click Auto Seek
A middle-click in the Path Bar will replace the contents of the Path Bar with the contents of the primary clipboard, and will seek to the location. The primary clipboard is set simply by selecting text in any application. For example, if you select the text "/etc/fstab" in your editor, then middle click in SpaceFM's path bar, the directory will change to /etc and the 'fstab' file will be selected. If you don't want to replace the contents of the Path Bar, and merely want to insert the primary clipboard text (the usual behavior of middle-click), hold down a modifier key while you click, such as Ctrl or Shift.

File Path or Device
The path to a file may be entered or pasted in the Path Bar. When you press Enter, SpaceFM will change to the directory containing the file and will select the file in the file list.

Also, a device file (eg /dev/sdd1) may be entered in the path bar. The device will be mounted if needed, and the mount point directory of the device will be opened.

Protocol URL
Any entry in the Path Bar which looks like a protocol, such as ftp://mirrors.kernel.org/, will be opened with the associated protocol handler. If a fileystem is mounted, SpaceFM will usually open the mount point directory automatically. If the Devices List has option Settings|Show|Mounted Networks checked, the filesystem may be listed.

Regardless of the protocol, most of SpaceFM's default protocol handlers accept URLs in the format: 

    PROTOCOL://USERNAME:PASSWORD@HOST:PORT/SHARE

WARNING: Including a password in the URL is a very unsafe mode of use, as your password is included in the command line and may be written to temporary and/or system files by SpaceFM or mount helpers. See documentation specific to the filesystem for other authentication methods offered, or enter your password when prompted.

Some parts of the above URL format may be omitted. Examples include: 

    ftp://mirrors.kernel.org
    smb://user:pass@10.0.0.1:50/docs
    ssh://user@sys.domain
    mtp://
NFS and Samba (cifs) URLs may also be in the alternate formats: 
    NFSHOST:/SHARE
    //SAMBAHOST/SHARE
For additional URL examples, see URL protocols and formats handled by udevil, which natively uses the same URL formats supported by SpaceFM.

In addition, custom protocol handlers may be added which accept URLs in the above formats, or in any format you prefer.

URLs may also be opened via the main menu bar's File|Open URL item, which is equivalent to entering them in the Path Bar, or on the command line.

TIP: You can sometimes right-click on a mounted network in the Devices List and select Bookmark to bookmark the URL for future use. Or, right-click on the Path Bar containing a URL and select New Bookmark. Or, edit an existing bookmark to contain a URL target.

Command Line
In addition, a bash command line can be entered in the Path Bar. This is a convenient way to run a command without having to manually open a terminal.

One or more command prefixes are required to tell SpaceFM how to run your command:

Prefix Result
$ run as task
& run and forget
+ run in terminal
! run as root

A Path Bar entry is interpreted as a command only if at least one of the above prefixes preceeds the command. A space after the prefix(es) is optional. For example, enter in the Path Bar: 

    $ ls
When you press Enter, ls will be run for the current directory, and a dialog will open showing the output. When using prefix '$', the command is run as a task (it will be listed in the Task Manager if it takes longer than a half second to run), and a popup dialog will open only if the command produces output or an error.

In addition, the substitution variables defined in Command Line, and the bash script variables described in Command Script may also be used in Path Bar command lines.

For example, to open a dialog showing the path of the current directory: 

    $ echo Current Directory: %d
Or to run umount in a terminal (+) as root (!) passing it the currently selected device (%v): 
    +! umount %v

When a plus sign (+) prefix is included, the command is run in a terminal, not as a task. When an exclamation point (!) prefix is included, the command is run as root.

If the ampersand (&) prefix is included, the command is run and forgotten (no error or output will be shown). This is useful for starting an application. For example: 

    & firefox
For a reminder of prefixes and substitution variables, enter a lone dollar sign ($) in the Path Bar and press Enter. Or press F1 while the Path Bar has focus to open this manual.

Command History
SpaceFM also keeps a command history. As you enter a command, any commands previously entered will be shown in a popup. Use Up/Down Arrow keys to select a previous command and press Enter, or click it.

Select By Pattern
If a percent sign (%) prefix is entered in the Path Bar, SpaceFM treats the rest of the text as a file selection pattern. This function is equivalent to right-clicking on the file list and selecting Actions|Select By Pattern. For example, enter in the Path Bar: 

    % *.avi
When you press Enter, all filenames in the file list ending in ".avi" will be selected, and all other files will be unselected. If your pattern contains any uppercase characters, the matching will be case sensitive. For additional wildcard characters and pattern specifics, see IEEE Pattern Matching Notation.

See also: Find-As-You-Type Search.

Font
The font used in the Path Bar can be customised (this is a per panel setting). Right-click on the Path Bar and select Font.

Contents Find-As-You-Type Search

When the file list has focus (click on the file list), pressing an alphanumeric key will open the Find-As-You-Type search box in the lower right corner of the file list, allowing you to quickly jump to a file. Press down or up arrow, or scroll wheel up/down, to go to the next or previous matched filename.

In addition, Find-As-You-Type Search supports the following modes:

  • Pattern Mode: If the search key contains at least one asterisk (*) or question mark (?), a glob substring search is used. (An asterisk is automatically added before and after your key before testing.) For pattern usage see IEEE Pattern Matching Notation.

  • Non-Pattern Mode: If your key does not contain an asterisk (*) or question mark (?), a normal substring search is performed, with the following new special characters recognized:

    • If the search key begins with a caret (^), or the search key is less than three characters, the search will match names beginning with your key.
    • If the search key is longer than two characters and doesn't begin with a caret (^), a case insensitive substring search is conducted (this means if you type any part of a filename, the cursor will select the first filename which contains that string of characters.)
    • If your key ends with a dollar sign ($), the search will match names ending with your key.
    • You can use both a caret and dollar sign to constrain both. (Other regex characters and wildcards are not supported in this mode.)

  • Anytime you use an uppercase letter anywhere in your search key, the search mode becomes case sensitive.

  • Regardless of mode, you can press down or up arrow, or scroll wheel down/up, to go to the next or previous matched filename.

See also: Select By Pattern.

Contents Rename Dialog

SpaceFM's Rename Dialog, accessed by right-clicking on a file and selecting Rename, does much more than rename files. It can move, copy, or create a link to the selected file or directory. It can also copy the target of a selected link, or create a new link to the target. By checking As Root, the function will be performed as the root user.

The Option button allows you to add and remove fields from the dialog. The selected fields, which are extra-large for easy editing of long filenames, show different parts of the selected path, such as the name and extension, full filename, parent, or path. As you edit the file's path, you will be advised if the entered path already exists. If you use a path which doesn't exist, SpaceFM will create the necessary parents automatically. The Confirm Create option determines if you will be prompted before parents are created.

The Browse button allows you to browse for a filename, parent, or path, and insert it into the dialog.

TIPS: To select all the text in an entry, click the entry's label (eg 'Filename:'), press the Alt key shortcut, or use Tab. To quickly copy an entry's text to the clipboard, double- or middle-click on the entry's label (eg 'Filename:'). Multiple files can be selected in the file browser to rename a batch of files.

Contents New File/Folder Dialog

The New File/Folder Dialog is opened by right-clicking on the file list and selecting New|File, Folder, or Link. This dialog works similarly to the Rename Dialog, allowing you to create files and folders in other paths, create as root, create relative links (eg a link to ../filename.txt), and create new files and folders using templates.

SpaceFM looks in $XDG_TEMPLATES_DIR/, ~/Templates/, or ~/.templates/ to find template files. Templates are simply empty or partially filled files (of any type) used to create new files, so instead of an empty file you get a copy of the template file. You can place any files or links to files in your Templates folder. Subfolders in the templates folder can also be used to create new folders pre-filled with a set of files, or to organize templates.

After you have finished entering the path for your new file or folder, you can press Create to create it, or the '& Open' button to create and open the file or folder in one step.

Contents Bookmarks

SpaceFM's main Bookmarks menu works like most other menus - you can right-click in the menu to add custom menu items, and to cut, copy, and paste items to other menus. Custom menu items may be bookmarks which open folders, but they may also run commands or applications. This means that items in SpaceFM's bookmarks can run socket commands to open folders in specific panels, change view settings, run external programs, and perform other automated tasks.

Bookmarks Side Pane

Items added to the Bookmarks menu may be shown in the Bookmarks side pane of each panel. To show the Bookmarks pane, select Show Bookmarks from the main Bookmarks menu, or right-click on a file and select View|Bookmarks.

Right-click in the Bookmarks pane and enter the Settings submenu to adjust behavior. The Single Click option determines if a single- or double-click is required to open an item. New Tab, if checked, will open bookmarks in a new tab. Bookmark Icon and Submenu Icon are used to set the default icons used in the list, and individual item icons can also be configured via their Properties. The Font setting adjusts the font and font size used in the Bookmarks side pane.

Finally, the Follow Dir option will cause the Bookmarks pane to follow the current directory. If a bookmark matches the current directory, it will be highlighted. If the matching bookmark is in a submenu, the submenu will be opened.

Follow Dir is a per-panel setting. For example, you can turn it on in the Bookmarks pane of Panel 1, and turn it off in Panel 2. When Follow Dir is off, the bookmark selection will not change automatically.

Tips:

  • If you don't want SpaceFM to select a bookmark via Follow Dir, prefix the bookmark's target with a semicolon (;). Also note that SpaceFM's bookmarks can target multiple directories, URLs, and devices. Only the first target is used by the Follow Dir function.

  • To reorder items in the Bookmarks pane, drag them. Note that drag-n-drop in this pane currently only allows items to be reordered, not moved to other locations. To move an item to a submenu, or to another SpaceFM menu or toolbar, you must use Cut and Paste, or Export/Import.

  • The Open item in the context menu of the Bookmarks pane (seen by right-clicking in the pane) will obey the reverse of the New Tab setting. For example, if New Tab is enabled, choosing Open will not open a new tab. Opening a bookmark by clicking on it with the middle mouse button also reverses New Tab behavior.

  • The Open item and the Settings submenu of the context menu of the Bookmarks pane can have custom items added after them or within Settings using Design Mode. Click once on the Settings submenu to close it, then right-click on it for the design menu, or right-click on the Open item, or on one of the items within the Settings submenu.

  • Selecting Copy on any item of type Bookmark (in any menu or in the side pane) will also copy the bookmark target to the text and primary clipboards (in addition to copying the menu item to the design clipboard for pasting into another menu or toolbar).

Adding A Bookmark

To add a new bookmark targeting the current directory, select New Bookmark from the Bookmarks menu (a key shortcut may also be assigned to this item - right-click on it to set one), or right-click in the Bookmarks pane or menu and select New|Bookmark (which will ask you to select a directory target).

To bookmark a single selected file or directory, or otherwise the current directory, right-click on the file list and select New|Bookmark.

To bookmark a mounted URL, in some cases you can right-click on the URL in the Devices List and select Bookmark. Or, a URL or file/dir path in the Path Bar may be bookmarked by right-clicking on the Path Bar and selecting New Bookmark.

To view or adjust the properties of a bookmark, right-click on it and select Properties.

Note: The Properties dialog of all custom menu items includes a Context tab which determines when and how menu items are displayed based on the file browser's current context. Note that Context settings do not affect display of bookmarks in the Bookmarks side pane, which always shows all bookmarks. The Context settings WILL affect how items are shown in the main Bookmarks menu.

Exporting Bookmarks

Any single item or submenu of items in Bookmarks may be exported to a SpaceFM plugin file by right-clicking on the item and selecting Export. Plugin files created in this way can also be imported into any other menu.

To export all items in Bookmarks, right-click on "Bookmarks" - the top item in the Bookmarks side pane - and select Export. This will create a special plugin file named "Bookmarks.spacefm-bookmarks.tar.gz". This file may then be imported into any SpaceFM menu, or into the Bookmarks side pane, by right-clicking and selecting Import|File. Note that this bookmarks plugin file CANNOT be installed or imported via the main Plugins menu.

Importing GTK Bookmarks

Some GNOME applications store bookmarks in GTK's bookmarks file (~/.config/gtk-3.0/bookmarks or the older ~/.gtk-bookmarks). This is a plain text file which can be edited manually. While SpaceFM is not a GNOME application and does not store its bookmarks in this file (the format of the file cannot store SpaceFM's specialized bookmarks and submenus), SpaceFM can import the contents of this file. To do so, right-click on an item in the Booksmarks side pane and select New|Import|GTK Bookmarks. All bookmarks will be imported into the current submenu (or, if you right-clicked on a submenu, then into the selected submenu).

IMPORTANT: Note that importing hundreds of bookmarks into SpaceFM is not recommended. Due to their integration with the menu system, this may cause performance lags in the GUI. If you have many GTK bookmarks, you may wish to edit the file before importing it, or import them into a submenu and keep only those you need.

In addition to importing GTK's bookmarks, these bookmarks are also shown in the GTK file and folder chooser dialogs used in SpaceFM. You will see the GTK bookmarks listed in the upper-left 'Places' pane of these dialogs, and you can use the plus (+) and minus (-) buttons there to add or remove bookmarks from that list (which will update the ~/.config/gtk-3.0/bookmarks file). Changing bookmarks in this 'Places' list has no effect on SpaceFM's Bookmarks menu.

Devices
Contents Introduction

SpaceFM includes a programmable udev-based device manager which lists device volumes, allows you to mount and unmount devices, and detects changes, insertions, and removals. On events, SpaceFM can auto-mount and auto-open devices, and run commands you specify. In addition, perform-as-root commands allow you to mount and unmount as root; change volume labels; and check, format, erase, backup, and restore partitions. Like most parts of SpaceFM, the behavior and appearance of the device manager is customisable.

Whenever SpaceFM is running, whether a window is visible or not, a volume monitor is running to monitor device events and take actions. The volume monitor requires the udevd daemon to be running for device event detection, and enabling kernel polling is recommended.

SpaceFM mounts and unmounts devices using customisable Device Handlers which can use udevil (a mount program developed specifically for SpaceFM), pmount, the udisks command line tool (v1 or v2), or any program you specify. To troubleshoot behavior, you can run the same command lines in a terminal that SpaceFM uses, or create your own custom handlers or menu items to manipulate devices.

NOTE: If you choose to use udisks with SpaceFM, note that SpaceFM does not configure udisks. It merely runs the udisks command line tool to mount and unmount devices (unless you install udevil, pmount or specify another program). If you receive the common 'Not Authorized' or other similar errors from udisks when mounting, or you are prompted for a password, this indicates that udisks (and policykit, etc.) are not properly installed or configured. This must be corrected in your system configuration, not in SpaceFM. Installing udevil is the quickest way to solve such problems.

Deprecated HAL support can also be used in SpaceFM (alternate build required). However, SpaceFM's HAL device manager is far less capable than the udev-based version. It can only be used to manually mount and unmount devices. Thus the udev-based version is recommended, and this manual deals exclusively with the udev-based device manager.

To have the device manager always running, responding to events even while no SpaceFM windows are open, run SpaceFM as a daemon or desktop manager.

When testing the device manager, it may be useful to run the initial instance of SpaceFM in a terminal so that you can see additional diagnostic output as it's running. Just open a terminal window and run spacefm.

Contents List

Each panel or tab in SpaceFM can display a Devices list to show devices and permit configuration of the underlying volume monitor. A Devices list is one interface to the volume monitor's information and actions. Even if multiple Devices lists are displayed or multiple SpaceFM windows are open, only one volume monitor will be running.

To show or hide a Devices list in each panel, right-click on the file list and check or uncheck option View|Devices. You can also show or hide the list using the 'Devices' toggle tool item on a toolbar.

The Devices list will display only removable and optical devices. If your Devices list is empty, this means there are no removable or optical devices with media, the udevd daemon is not installed or is not working properly on your system, or you may need to enable kernel polling for media detection. To show or hide additional devices, use the Show submenu.

You can mount and open a device in the Devices list by simply left-clicking on it. The behavior of a left-click will vary depending on options New Tab and Single Click.

Right-click on a device to show the Devices context menu.

Middle-clicking on a device is equivalent to right-clicking on the device and selecting Remove / Eject. Thus to quickly remove a device, just middle-click on it.

Contents Menu

Similar to the Devices List, SpaceFM's main menu bar and the desktop menu include Devices menus which list currently shown devices. Click on a device to mount and open it, or right-click on a device for additional options. Right-clicking on a device in these menus or in the Devices List shows the context menu described below. As in the Devices List, you can also middle-click on a device in the menu to 'Remove / Eject'.

Like most menus in SpaceFM, to see the help for any menu item, hover your mouse cursor over the menu item and press F1. Alternatively, right-click on the menu item and select Help in the Design Menu.

The Devices context menu includes: (not all items may be shown)

Remove / Eject
The 'Remove / Eject' item is used to remove a device and eject media. When you click 'Remove / Eject', first a full sync is performed to ensure all data has been commited to all disks. If the sync takes longer than about one half second, the Task Manager will auto-show and will list the Remove command as running. Do not remove a device until the Task Manager shows this command has finished, or data may not be properly written, which can cause data loss. (If using 'Remove / Eject' from the Devices menu on the desktop, a popup dialog will show removal progress.) Note that if all other filesystems don't sync immediately, this may prolong the Remove command. In that case, you can use Unmount instead, which only does a filesystem-specific sync.

Next, if the volume is mounted, it will be unmounted, and if the device is ejectable, it will be ejected. If the device is removable, it is safe to remove it once the 'Remove / Eject' command has completed without errors, and any lights on the device indicate activity has stopped. (Even after the sync and unmount has finished, it may take a second or two for the device to stop flashing due to hardware caches. If the device has no activity indicator, it is best to wait 5 seconds before removing it.)

If you click 'Remove / Eject' and nothing seems to happen, this also indicates the device is ready to be removed.

When a device is removed or unmounted, any tabs showing directories on the device may be automatically closed.

Middle-clicking on a device in the Devices list is equivalent to right-clicking the device and selecting 'Remove / Eject'. Thus to quickly remove a device, just middle-click on it.

NOTE: SpaceFM does NOT disable or power-down usb ports or spin down disks when removing a device, it merely performs a sync to ensure data is written. Usually this is sufficient to prevent data loss. If powering down is required for your device, you must add a custom command to the Devices menu, or add the applicable command or option to the unmount handler.

Reload
Reload is used to unmount, eject if necessary, and reload a device's media tray in one step, and can also be used to close an already open media tray. The Reload item is similar to Remove / Eject - the device will be synced, unmounted, and if possible, ejected. After this, if ejected the tray will be closed. The device will not be mounted unless auto-mount is set.

Unmount
Unmount will simply run an unmount command on the selected device. The unmount command from the appropriate Device Handler will be run- by default, udevil, pumount, or the udisks command line tool will be used. No general sync is performed (but a filesystem-specific sync is performed by umount). If the command takes longer than about one half second, the Task Manager will auto-show and the Unmount command will be listed until finished. Do not remove a device until the Task Manager shows this command has finished, or data may not be properly written, which can cause data loss. (If using 'Unmount' from the Devices menu on the desktop, a popup dialog will show removal progress.) (Even after the unmount has finished, it may take a second or two for the device to stop flashing due to hardware caches. If the device has no activity indicator, it is best to wait 5 seconds before removing it.)

Sync
Sync merely runs a sync command to commit all data to all disks. If the command takes longer than about one half second, the Task Manager will auto-show and the Sync command will be listed until finished.

Open
Selecting Open will cause the selected device to be mounted if it is not already mounted, and then the mount point directory of the device will be opened in the current tab. If an error occurs, the error will be shown. If the command takes longer than about one half second, the Task Manager will auto-show and the Open command will be listed until finished.

You can also open a device by simply left-clicking on it. The behavior of a left-click will vary depending on options New Tab and Single Click.

To mount, SpaceFM runs the mount command from the appropriate Device Handler for the selected device. By default, udevil, pmount, or the udisks command line tool will be used. The mount point will be determined automatically by the mount program or handler, usually an automatically created subfolder in /media or /run/media/$USER. If it was automatically created, this subfolder will be automatically removed when the device is unmounted.

If the device has an entry in /etc/fstab, that mount point may be used instead, and its mount directory will not be removed when unmounted.

The device will generally be mounted using SpaceFM's Mount Options. If the device has an fstab entry, options specified there may take precedence, depending on your mount program, which may also automatically add or change some mount options.

pmount does not support conventional mount options, so when using pmount as the mount command, options set in Mount Options will be ignored. Instead, you can include pmount's command line options in the device handler. Open In Tab works similarly to open, except that the device's mount point directory will be opened in a new tab, instead of reusing the current tab. This is also the default behavior of a left-click on a device if option New Tab is checked. Again, a left-click will not display an error, while selecting Tab will.

Mount
Mount will simply run a mount command on the selected device. The mount command from the appropriate Device Handler will be run - by default, udevil, pumount, or the udisks command line tool will be used. The mount point will be determined automatically by the mount program or handler, usually an automatically created subfolder in /media or /run/media/$USER. If the command takes longer than about one half second, the Task Manager will auto-show and the Mount command will be listed until finished.

The device will generally be mounted using SpaceFM's Mount Options. If the device has an fstab entry, options specified there may take precedence. The mount program may also automatically add or change some mount options.

pmount does not support conventional mount options, so when using pmount as the mount command, options set in Mount Options will be ignored. Instead, you can include pmount's command line options in the device handler.

Re/mount
The Re/mount item is used to mount or remount a device using specific mount options. A dialog will open asking you for the mount options to be used. If mounted, the device will first be unmounted. Then the device will be mounted using the specified options.

Because most mount programs cannot perform a true remount, the device will be unmounted and mounted.

Re/mount accepts extended mount options, as detailed in Mount Options.

pmount does not support conventional mount options, so when using pmount as the mount command, options set here will be ignored. Instead, you can include pmount's command line options in the device handler.

Bookmark
The Bookmark item will only be shown if the selected device is a mounted network. This item allows you to create a bookmark which will automatically mount the network. Some mounted networks are not recognized. To create a URL bookmark manually, enter the URL in the Path Bar, right-click in the Path Bar, and select New Bookmark.

Note: Any custom menu items you add directly after the Bookmark menu item in the Devices menu will also only appear if the selected device is a mounted network, providing an automatic context.

Root
The Root submenu allows you to perform actions on a device as root. Dialog messages should be read carefully when using any command in the Root submenu, because actions performed as root can affect any aspect of your system. SpaceFM will explain what is about to happen and will let you examine the final command line before it is executed.

For details, see the Root section below.

Settings
The Settings submenu allows you to (globally) configure the appearance of the Devices list, controlling what devices are listed, how they are listed, what icons are used, etc., and also allows you to set the volume monitor to run commands on various events, such as device insertions, etc.

For details, see the Settings section below.

Properties
The Properties item will gather and show information about the currently selected device.

If mounted, any mtab lines related to the device will be shown in DEVICE, showing you how and where the device is mounted.

USAGE will show information about the filesystem on the device.

If the device has any related lines in the /etc/fstab file, these will be listed in FSTAB. These may include lines which are disabled (# comments).

In the INFO section, the device's UUID will be listed if known, as well as detailed information from udev on the device's properties.

The PROCESSES section, shown for mounted devices, uses lsof to display any processes which are using the device. Sometimes when unmounting a device, you will receive an error that the device is in use. You can check this processes list to see what is holding the device open.

Custom Menus
As with most menus, it is also possible to add your own custom menu items and submenus to the Devices menu. This allows you to add commands which can take actions based on the currently selected device in one or more panels.

There are several provided bash variables which your commands can use to get information about the currently selected device: 

    "$fm_device"              selected device (eg /dev/sr0)  ( same as %v )
    "$fm_device_udi"          device ID
    "$fm_device_mount_point"  device mount point if mounted (eg /media/dvd) (%m)
    "$fm_device_label"        device volume label            ( same as %l )
    "$fm_device_fstype"       device fs_type (eg vfat)
    "$fm_device_size"         device volume size in bytes
    "$fm_device_display_name" device display name
    "$fm_device_icon"         icon currently shown for this device
    $fm_device_is_mounted     device is mounted (0=no or 1=yes)
    $fm_device_is_optical     device is an optical drive (0 or 1)
    $fm_device_is_table       a partition table (usually a whole device)
    $fm_device_is_floppy      device is a floppy drive (0 or 1)
    $fm_device_is_removable   device appears to be removable (0 or 1)
    $fm_device_is_audiocd     optical device contains an audio CD (0 or 1)
    $fm_device_is_dvd         optical device contains a DVD (0 or 1)
    $fm_device_is_blank       device contains blank media (0 or 1)
    $fm_device_is_mountable   device APPEARS to be mountable (0 or 1)
    $fm_device_nopolicy       policy_noauto set (no automount) (0 or 1)

    "$fm_panel3_device"       panel 3 selected device (eg /dev/sdd1)
    "$fm_panel3_device_udi"   panel 3 device ID
    ...                       (all these are the same as above for each panel)
For example, to add a custom command which shows the size of the currently selected device in bytes, use this command line: 
    echo "$fm_device_size"


Contents Root

The Root submenu allows you to perform actions on a device as root. When performing commands as root, SpaceFM will use your configured Terminal SU or Graphical SU program to run the command.

When most items on this menu are selected, a dialog will open showing you the exact command to be run, and allowing you to edit it. If SpaceFM knows how to perform the function on the selected device type, a default command will already be present.

In order to edit the default command, you must first depress the Edit button. To restore the command to its default, depress Edit and then press Default.

Most items accept the substitution variable %v in their command, which is used to insert the device file (eg /dev/sda2). Some commands accept additional substitution variables. These will be displayed in the dialog's instructions.

When performing commands which result in data loss, such as format, the exact command line to be run will be displayed in the terminal after you enter the root password. You will need to type the word 'yes' and press Enter to execute the command.

The following functions are included:

Unmount
By default, SpaceFM will use udevil to unmount as root, but you can change this to any unmount command, such as a udisks, pumount, or umount command. Only the substitution variable %v may be used in this command to insert the currently selected device file (eg /dev/sda2).

Mount
Mount works similarly to Unmount, except that the selected device is mounted as root. If you want any mount options added, you must specify them in the dialog.

Label
Label is used to change the volume label of a device. First, a dialog will open asking you to enter the volume label. The device's current volume label, if any, will be entered as default. To unset a volume label, leave the entry blank.

Next the command used to change the volume label on this filesystem type will be shown. If SpaceFM doesn't know how to change the volume label for this type, the command will be blank and you will have to supply your own. This dialog remembers the change label command used for each filesystem type.

When you click OK, your Graphical SU program will be used to run the command (no terminal will open).

IMPORTANT: SpaceFM will display a warning in both dialogs if the device is currently mounted. Although some filesystem types permit it, it is generally good practice to unmount a volume before changing its label.

Check
Check runs a filesystem check on the device, using fsck by default. The command dialog remembers the check command used for each filesystem type.

Check may only be used on unmounted filesystems.

Format
The Format submenu allows you to format or simply erase a device or partition. Although Format will work on an entire device, it is up to you to decide what device or device partition you want to format.

The submenu contains common filesystem types to choose from. To format, select the type and review or edit the command in the dialog. This dialog remembers the format command used for each filesystem type. When you click OK, the command will be run in a terminal. After entering the root password, you will be shown the exact command to be run, and you must type the word 'yes' and press Enter to execute it.

The format submenu also contain 'zero' and 'urandom'. If selected, the device will be overwritten with zeroes or random values to completely erase it. As with filesystem formats, you can edit the particular command used. Edit with care!

To test out the format function without actually formatting anything, try using format on a DVD drive, or an empty drive. The entire procedure will be the same - you will merely receive an error when the command is finally executed. This will allow you to safely review how SpaceFM conducts a format. Just be sure you know which device is the DVD or empty drive!

Backup|FSArchiver
The Backup submenu allows you to perform a backup of a selected device or MBR. There are several supported backup types.

FSArchiver (website) is a modern program which creates an archive of a filesystem. It is similar to tar, except that the archive includes checksums, can be restored if corrupted, and includes additional information.

One disadvantage to using FSArchiver is that unlike Partimage, the on disk locations of files will change when restored. For most files this won't matter, but in the case of grub's stage files, moving them can cause the grub boot process to no longer work. Thus if you restore a volume containing grub's files using an FSArchiver archive, you will then need to reinstall grub to the MBR (so that it knows accurately where it's files are - these locations are stored in the MBR's boot code).

An advantage to FSArchiver is that it supports more filesystem types than Partimage, including ext4 and btrfs, and several compression methods. Other advantages include file exclusion, multi-thread compression, and encryption. The data may also be restored to any partition large enough to hold it, regardless of the original partition's size. FSArchiver is also currently maintained, while Partimage is no longer actively developed. There are additional differences between Partimage and FSArchiver - see their websites for details.

By default, FSArchiver will backup unmounted volumes and volumes mounted read-only. To backup a volume which is mounted read-write, you must add --allow-rw-mounted to the command. This may create inconsistencies in the backup. Run man fsarchiver for details.

To create an FSArchiver backup, right-click on a device and select Root|Backup|FSArchiver. A file save dialog will open asking you to select a filename and location. Keep in mind that the archive size may be 50% or more of the total data saved in the filesystem. Choose a save location with ample space.

Next a command dialog will show you the FSArchiver command to be used, and allow you to edit it. When you click OK, the command will be run immediately in a terminal.

Backup|Partimage
Although older than FSArchiver, Partimage (website) is still a valuable if simpler backup tool. One advantage to Partimage is that the backup preserves the on disk locations of files, which means there is no grub MBR breakage. However, Partimage does have some limitations when compared to FSArchiver:

  • Partimage cannot be used to backup ext4 or btrfs filesystems.
  • Partimage cannot be used to backup mounted filesystems.
  • Partimage can only restore to a partition which is the same size or larger than the original partition, regardless of the actual amount of data in the archive.
  • Archives have no internal checksums, so it is not possible to detect corruption (unless you manually create an MD5 sum and check it yourself, etc.)
  • There is no built-in ability to encrypt an archive.
There are additional differences between Partimage and FSArchiver - see their websites for details.

To create a Partimage backup, right-click on an unmounted device and select Root|Backup|Partimage. A file save dialog will open asking you to select a filename and location. Keep in mind that the archive size may be 50% or more of the total data saved in the filesystem. Choose a save location with ample space. Note that Partimage will add a '.000' volume extension to the name you select.

Next a command dialog will show you the Partimage command to be used, and allow you to edit it. By default, the command will break the archive into archive volumes 4G in size. This can be adjusted by carefully editing the command. When you click OK, the command will be run immediately in a terminal.

Backup|MBR
SpaceFM can also create a backup of a device's Master Boot Record (MBR). This is a small backup (512 bytes) which contains the entire MBR. (What Is The MBR?)

After selecting Root|Backup|MBR, a file save dialog will open asking you to select a filename and location. This is a very small backup file. When you click OK, a terminal will open and the command will be executed immediately. (It is not possible to edit the MBR backup command.)

Restore|From File
To restore the contents of a device, partition, or MBR using a backup archive file, right-click on the target partition and select Root|Restore|From File. A choose file dialog will open for you to choose a backup file. This may be any backup file created by SpaceFM, including an FSArchiver, Partimage, or MBR archive file. (If the file was not created by SpaceFM but uses one of these formats, it may be possible to use the file if the file is named appropriately.)

Next a dialog will show the restoration command to be used, and allow you to edit it. When you click OK, a terminal will open prompting you for the root password. Once entered, the exact command to be run will be shown. You will need to type the word 'yes' and press Enter to execute it.

IMPORTANT: Restoring data to a partition overwrites any existing filesystem.

After restoring from an FSArchiver backup, if the filesystem contains grub's files, you may need to reinstall grub to the MBR to restore normal boot behavior. (Reinstalling grub is not handled by SpaceFM, and is outside the scope of this manual, but you can create a custom command to do so.)

When restoring an MBR, only the first 448 bytes of the MBR are restored. This portion contains the boot code. The remaining portion of the MBR contains the primary partition table. This portion is NOT restored (it is generally not useful to do so, and in the case of an out of date backup, could cause extreme data loss). However, the MBR backup file created by SpaceFM does contain the full 512 byte MBR, so if you do want to restore the entire MBR, consult appropriate instructions such as these.

To practice restoring a file without making real changes, consider restoring to a DVD or empty drive as the target. This will allow you to see the entire process, except that the final command will fail when executed. Just be sure you know which device is your DVD or empty drive!

Restore|File Info
To examine the summary information in a backup file, select Root|Restore|File Info and select the backup file.

Restore|File Info makes no changes to the backup file or any device - it only displays information about the backup file. It may need to run as root to do so.

Edit fstab
Edit fstab is a convenience function which simply opens the /etc/fstab file as root using root's editor (configured in View|Preferences|Advanced).

Contents Settings

The Settings submenu is your interface for controlling the appearance and behavior of the Devices list and volume monitor. Options include:

Show|Internal Drives
By default, the Devices list will only show removable and optical drives, while hiding internal system drives. If option Show|Internal Drives is checked, internal system drives will also be shown in the Devices list. For the root user, option Show|Internal Drives is checked by default.

Internal drives are often treated differently by mount programs. You may not be able to mount or unmount them as a normal (non-root) user without making changes to /etc/fstab or to the mount program's configuration.

Note that some external esata drives report themselves as internal, so they may not be shown unless Show|Internal Drives is checked. Another solution with these drives is to enter an exception for them in Show|Volumes.

Show|Empty Drives
By default, the Devices list will only show drives which contain media, and will hide empty drives. If option Show|Empty Drives is checked, drives not containing media will also be shown.

Properties can still be obtained on empty drives, and you can use Remove or Reload to open or close the tray.

NOTE: For proper detection of media, enabling kernel polling may be required.

Show|Partition Tables
By default, the Devices list will not show devices which contain partition tables, such as a whole device file (eg /dev/sda) which contains the primary partition table in its MBR, or a partition (eg /dev/sda4) which contains the extended partition table. Normally you will not work with these device files so it is not useful to show them. If you do want them shown, check option Show|Partition Tables. If the device is internal, option Show|Internal Drives is also required.

IMPORTANT: For some purposes, a whole device file, such as /dev/sda, designates not just the primary partition table, but also the entire device including partitions (/dev/sda1, /dev/sda2, etc.) Thus if you format /dev/sda, for example, you will overwrite all partitions on the entire device.

However, in some cases a device uses no partitions, and the entire device has been formatted with a single filesystem. In this case, the Devices list does not consider the whole device file a partition table, so option Show|Partition Tables will have no effect on it being shown.

The size displayed for a whole device file (eg /dev/sda) will generally be the size of the entire device (including all partitions), regardless of whether it contains a partition table or a filesystem.

Specifically, SpaceFM considers a device to be a partition table if its udev properties include a 'partition table:' line, or the device is a partition of type 0x05 (extended partition).

Show|Mounted Networks
By default, the Devices list will show recognized mounted network filesystems (eg nfs, cifs, etc). This enables you to click on the network to open it's mount point directory, or right-click on it to use the Unmount and Bookmark menu items. If you do not want mounted networks listed, uncheck option Show|Mounted Networks.

Show|Mounted Other
By default, the Devices list will show files mounted to loop devices, and other non-block devices, such as mounted fuse filesystems. For example, if you right-click on an ISO file and select Open|Mount ISO, the ISO file will be mounted so you can browse its contents. You can then click on this device in the Devices list to open it's mount point directory, or right-click on it to use Remove or Unmount.

If you do not want mounted files and non-block device filesystems listed, uncheck option Show|Mounted Other.

Show|Ignore Hide Policy
Some devices may have their udev property UDISKS_PRESENTATION_HIDE set to 1. This is a hint to software that the device should be hidden. By default, SpaceFM will honor these hints and hide such devices. To ignore such hints, check option Show|Ignore Hide Policy.

The hide policy of a device can be seen by selecting Properties for the device and observing the value of 'presentation hide:' in the INFO section.

To ignore UDISKS_PRESENTATION_HIDE for a specific device, use Show|Volumes.

Show|Volumes
The Show|Volumes dialog allows you to specify display exceptions for some devices. When deciding whether to show or hide a device in the Devices list, SpaceFM will first consult the Show|Volumes list. If the device is present, it will be shown or hidden based on its entry in this list. All other show or hide settings will be ignored for this device.

One example use for Show|Volumes is to show an external esata drive which is erroneously identified by udev as internal. Even if option Show|Internal Drives is unchecked, the drive will be shown if listed in Show|Volumes.

Show|Volumes opens a dialog which allows you to specify device files, volume labels, or device IDs in a space-separated list. There must be a space between entries and a plus or minus sign directly before each item. This list is case-sensitive.

For example, to force showing device /dev/sdd1, include:
    +/dev/sdd1

Or, to force hiding of /dev/sdd1, include:
    -/dev/sdd1

The '/dev/' portion of the device file MUST be included.

Devices can also be identified by volume label. For example, to always hide a device with volume label "Label With Space" use:
    -Label With Space

DO NOT use quotes to enclose the label, even if it contains spaces.

Finally, a device's ID may be used:
    +ata-OCZ-part4

For example, this list in Show|Volumes:
    +/dev/sdd1 -Label With Space +ata-OCZ-part4

would cause /dev/sdd1 and the OCZ device to be shown, and the volume with label "Label With Space" to be hidden.

Show|Display Name
Display Name opens a dialog which allows you to edit the display name format used for the Devices list. This controls how device names are displayed.

In addition to separator characters of your choice, the following substitution variables may be used:

%v device filename (eg sdd1)
%s total size (eg 800G)
%t fstype (eg ext4)
%l volume label (eg Label or [no media])
%m mount point if mounted, or ---
%i device ID

A device in the list is guaranteed to have a unique, non-blank device filename - no two will be alike. The other values may be duplicated or empty in some cases.

After you click OK, the display names of the currently shown devices will be updated. The list is sorted alphabetically, ignoring spaces.

Auto Mount|Mount Optical
The Auto Mount submenu allows you to control the auto-mounting behavior of the volume monitor. This determines what happens when a new device or new medium is inserted, whether a new tab is opened, and the auto-unmount behavior.

IMPORTANT: If you have multiple auto-mount solutions installed and running, this can create confusing behavior. For example, if you use devmon, then when using SpaceFM's auto-mount features, it is best to disable devmon.

If option Mount Optical is checked, optical devices such as CD/DVD drives will be automatically mounted when media is inserted, and at SpaceFM startup.

TIP: For additional information on what the volume monitor is doing, try running SpaceFM in a terminal. Information on devices being auto-mounted will be printed to the terminal, and error messages generated by your command may be seen there as well.

Auto Mount|Mount Removable
If option Mount Removable is checked, the device will be automatically mounted whenever a removable device is inserted, and at SpaceFM startup.

Auto Mount|Ignore No Policy
Some devices may have their udev property UDISKS_PRESENTATION_NOPOLICY set to 1. This is a hint to software that the device should not be automatically mounted. By default, SpaceFM will honor these hints and not auto-mount such devices. To ignore such hints, check option Show|Ignore No Policy.

The policy of a device can be seen by selecting Properties for the device and observing the value of 'presentation nopolicy:' in the INFO section.

To ignore UDISKS_PRESENTATION_NOPOLICY for a specific device, use Mount|Volumes.

Auto Mount|Mount Volumes
The Mount Volumes list works similarly to the Show|Volumes list, except that it determines what devices will or will not be auto-mounted (and auto-unmounted, if option Unmount On Exit is checked). When deciding whether to auto-mount a device, SpaceFM will first consult the Mount Volumes list. If the device is present, it will or will not be auto-mounted based on its entry in this list. All other auto-mount settings will be ignored for this device.

Mount Volumes opens a dialog which allows you to specify device files, volume labels, or device IDs in a space-separated list. There must be a space between entries and a plus or minus sign directly before each item. This list is case-sensitive.

For example, to force auto-mounting of device /dev/sdc1, include:
    +/dev/sdc1

Or, to inhibit auto-mounting of /dev/sdc1, include:
    -/dev/sdc1

The '/dev/' portion of the device file MUST be included.

Devices can also be identified by volume label. For example, to inhibit auto-mounting of a device with volume label "Label With Space" use:
    -Label With Space

DO NOT use quotes to enclose the label, even if it contains spaces.

Finally, a device's ID may be used:
    +ata-OCZ-part4

For example, this list in Mount Volumes:
    +/dev/sdc1 -Label With Space +ata-OCZ-part4

would cause /dev/sdc1 and the OCZ device to be auto-mounted, and the volume with label "Label With Space" to not be auto-mounted.

Auto Mount|Mount Dirs
This dialog allows you to enter a single directory where SpaceFM should automatically create mount point directories for fuse and similar filesystems (%a in handler commands). This directory must be user-writable (do NOT use /media); if it doesn't already exist, it will be created (including parents). For best results with all handlers, avoid spaces and other special characters. If left blank, ~/.cache/spacefm/ (or $XDG_CACHE_HOME/spacefm/) is used.

The following variables are recognized and will be replaced with their current value: $USER $UID $HOME $XDG_RUNTIME_DIR $XDG_CACHE_HOME

Note that some handlers or mount programs may not obey this setting. It will only be used by handlers which use %a in their mount or open commands.

Anytime a device, protocol or file handler uses %a to automatically create a mount point, the specified directory will be used as the parent. This applies to both manual and automatic mounts.

Note that empty subdirectories will be routinely and automatically removed from the specified directory.

Auto Mount|Open Tab
If option Open Tab is checked, when a device is auto-mounted by SpaceFM, a new tab will be opened for the mount point directory of the device. If unchecked, the mount point directory will not be automatically opened.

Note that the Open Tab option only affects what happens after a device is auto-mounted by SpaceFM. It has no effect on devices mounted by other means, nor does it apply to devices mounted by user action within SpaceFM.

Auto Mount|Unmount On Exit
If option Unmount On Exit is checked, any device which would normally be auto-mounted by SpaceFM (based on auto-mount settings) will be unmounted when SpaceFM exits. Exit occurs when the last SpaceFM window is closed, unless a daemon or desktop manager daemon is running. Note that if SpaceFM is killed with SIGKILL (such as when you logout of your X session), the automatic unmount will NOT occur. (To unmount all devices before or just after X logoff, consider running devmon --unmount-all (devmon is distributed with udevil).

When mounting a device, if there is no fstab entry for the device, your mount program may create a subfolder for the device mount point in /media or /run/media/$USER. If you or SpaceFM unmounts the device, this subfolder will be removed. However, if you logoff without unmounting the device, the subfolder may be left behind. In order to avoid these subfolders accumulating in /media, SpaceFM can unmount devices on exit.

If you don't check option Unmount On Exit, you may need to unmount devices in some other way before logging off to avoid these /media subfolders accumulating.

Auto Run|On Mount
Auto Run|On Mount opens a dialog which allows you to set a command line to be run when a removable drive or optical data disc is auto-mounted by SpaceFM. This command can be as simple as a program name to be run, or can be a one line bash script. The following substitution variables may be used in the command line:

%v device (eg /dev/sda1)
%l device volume label
%m device mount point (eg /media/disk)

Note: When the command is run, %v, %l, and %m refer to the device being added or removed, not the device which is currently selected in the Devices list.

For this command to be run, the device must be auto-mounted by SpaceFM. It will not be run for devices mounted by other means, or for devices mounted by user action within SpaceFM.

The command will not be run for devices which are auto-mounted at SpaceFM's initial startup. Thus Auto Run affects devices you add after SpaceFM is running.

For additional information on what the volume monitor is doing, try running SpaceFM in a terminal. Information on devices being auto-mounted will be printed to the terminal, and error messages generated by your command may be seen there as well.

For example, to automatically add a mounted volume to traydevice, set the On Mount command line to: 

    traydevice %v

Another example: To have notify-send alert you of new drive mounts: 

    notify-send --icon=block-device --urgency=low "Volume %l has been mounted"

Auto Run|On Audio CD
Similar to Auto Run|On Mount, Auto Run|On Audio CD opens a dialog which allows you to set a command line to be run when an audio CD is inserted in a qualified optical device.

The command will be run only if: a) option Mount Optical is checked, AND b) the device qualifies for auto-mounting based on Mount Volumes (ie it is not inhibited).

The command will not be run for media which is already inserted during SpaceFM's initial startup. Thus Auto Run|On Audio CD affects media you insert after SpaceFM is running.

For example, to set an audio CD to automatically start playing in the vlc media player, set the On Audio CD command line to: 

    vlc --verbose=-1 cdda://%v

Auto Run|On Video DVD
Similar to Auto Run|On Audio CD, Auto Run|On Video DVD opens a dialog which allows you to set a command line to be run when a video DVD is inserted in a qualified optical device.

The command will be run only if: a) the device is auto-mounted by SpaceFM, AND b) the device contains a video DVD.

The command will not be run for devices which are auto-mounted at SpaceFM's initial startup, nor will it be run for devices mounted by other means, nor for devices mounted by user action within SpaceFM.

For example, to set a video DVD to automatically start in the vlc media player, set the On Video DVD command line to: 

    vlc --verbose=-1 dvd://%v

Auto Run|On Insert
Auto Run|On Insert opens a dialog which allows you to set a command line to be run when any device is inserted. This allows you to connect your command to the insertion (device added) event.

Auto-mount settings have no impact on this function.

Note that when inserting a single drive, your command may be run several times - once for each device file added. For example, if you insert device /dev/sdd which contains one partition /dev/sdd1, your command will be run once with %v=/dev/sdd and once with %v=/dev/sdd1. It is up to your command or script to discard events for unwanted devices or partitions. A script can run one of these commands to get current information on a device's status: 

    udevil info /dev/sdX
    udisks --show-info /dev/sdX
    udisksctl info -b /dev/sdX

For greater control, an event handler may be set for event evt_device.

Auto Run|On Unmount
Auto Run|On Unmount opens a dialog which allows you to set a command line to be run when any device is unmounted by any means.

Auto-mount settings have no impact on this function.

For example, to automatically remove the drive from traydevice, set the On Unmount command line to: 

    pkill -f "traydevice %v"

For greater control, an event handler may be set for event evt_device.

Auto Run|On Remove
Auto Run|On Remove opens a dialog which allows you to set a command line to be run when any device is removed. This allows you to connect your command to the removal event.

The device must be removed. Ejection of media will not cause this command to be run.

Auto-mount settings have no impact on this function.

Note that when removing a single drive, your command may be run several times - once for each device file removed. For example, if you remove device /dev/sdd which contains one partition /dev/sdd1, your command will be run once with %v=/dev/sdd and once with %v=/dev/sdd1. It is up to your command or script to discard events for unwanted devices or partitions. Note that when the command is run, %v equals the device file which has been removed, not the device file which is selected in the Devices list.

For greater control, an event handler may be set for event evt_device.

Device Handlers
Opens the Device Handlers configuration dialog.

Protocol Handlers
Opens the Protocol Handlers configuration dialog.

Mount Options
Mount Options opens a dialog which allows you to set default mount options. These options may be used in Device Handlers via the substitution variable %o, and are used by the default mount command for all mounts, including auto-mounts.

In addition to regular options, you can also specify options to be added or removed for a specific filesystem type by using the form OPTION+FSTYPE or OPTION-FSTYPE.

For example, this set of options:
    nosuid, sync+vfat, sync+ntfs, noatime, noatime-ext4

will add nosuid and noatime for all filesystem types, add sync for vfat and ntfs only, and remove noatime for ext4.

Note that only handlers which use the %o substitution variable will use options specified here. They will not apply to mounts performed by other handlers.

Note that some options, such as nosuid or noatime, may be added by your mount program even if you don't include them. For example, if using udevil, you may need to also change the default options in /etc/udevil/udevil.conf. Also, options specified in /etc/fstab may take precedence over options specified in Mount Options.

pmount does not support conventional mount options, so when using pmount as the mount command, options set here will be ignored. Instead, you can include pmount's command line options in the appropriate Device Handler.

Change Detection
Change Detection opens a dialog which allows you to enter a comma- or space-separated list of filesystems which should NOT be monitored for changes to files. This setting only affects non-block devices (such as nfs or fuse), and is usually used to prevent SpaceFM becoming unresponsive with network filesystems.

When SpaceFM opens a directory in a tab, normally it will detect changes, for example if you edit or change the properties or sizes of files in the directory. Because SpaceFM works directly with the kernel for file information, and because some network filesystems become temporarily unresponsive when busy, this can cause SpaceFM to become temporarily unresponsive to mouse clicks, etc.

To prevent this, the device's filesystem can be listed in the Change Detection Blacklist. In this case, SpaceFM will not detect changes to files, load thumbnails, or load subdirectory sizes, and you will need to manually refresh the file list view to see file changes. To do so, right-click on the file list and select View|Refresh, or press F5.

Note that even if the filesystem is listed in Change Detection, new files created in the directory, or files which are renamed or deleted, will be detected and read.

An alternative approach to blacklisting filesystems is to close the tab containing the filesystem while a copy is in progress to that directory.

Single Click
If option Single Click is checked, the Devices list operates in single-click mode: a single left-click on a device will open it. If unchecked, a single-click will only select a device, and a double-click is required to open it.

New Tab
If option New Tab is checked, when a device is opened with a single or double click (depending on option Single Click), the mount point directory will be opened in a new tab in the current panel. If unchecked, the mount point directory will be opened in the current tab.

Icon
The Icon submenu allows you to set custom icons to be displayed at the left of devices in the Devices list. For example, to change the icon used for an internal, mounted drive, click Icon|Internal Mounted and enter the desired icon name.

By default, SpaceFM reuses a limited number of icons so that only stock GTK icons are required. If you would like the device icons to better reflect the changing state of devices, it is valuable to customise these icons.

Font
Font opens a font selection dialog which allows you to select the font to be used for the Devices list. Select a font family, style, and size and click OK, or click Default to use your GTK theme's font.

Contents How To Enable Kernel Polling

You may need to enable kernel polling for device media changes to be detected by SpaceFM. For example, if you insert a CD and SpaceFM still says 'no media', this is a symptom that kernel polling is not enabled.

Kernel polling is a newer feature of the Linux kernel and udev, so some distros don't yet have it enabled by default. To use kernel polling, your Linux kernel may need to be 2.6.38 or newer, and udev may need to be version 173 or newer.

To determine if kernel polling is enabled: 

    cat /sys/module/block/parameters/events_dfl_poll_msecs
    cat /sys/block/sr0/events_poll_msecs
If you get 0 or -1 from both of those commands, kernel polling may be disabled.

To enable kernel polling permanently (survives a reboot), add the following command to your /etc/rc.local file (anywhere before the 'exit' line in that file): 

    echo 2000 > /sys/module/block/parameters/events_dfl_poll_msecs
Any number between 2000 and 5000 (milliseconds) should be reasonable - the higher 5000 means poll every 5 seconds, which is less overhead but a little slower.

OR pass this option to the kernel boot command line in grub:

block.events_dfl_poll_msecs=2000

OR add a udev rule to enable kernel polling on removable devices:

echo 'ACTION=="add", ATTR{removable}=="1", ATTR{events_poll_msecs}=="-1", ATTR{events_poll_msecs}="2000"' > /etc/udev/rules.d/61-removable-storage-polling.rules

A reboot will be required for the above changes to take effect, or...

To enable kernel polling temporarily and immediately, enable common polling for the block module: 

    sudo bash -c 'echo 2000 > /sys/module/block/parameters/events_dfl_poll_msecs'

OR you can enable polling just for a single device like this (/dev/sr0 in this example): 

    sudo bash -c 'echo 2000 > /sys/block/sr0/events_poll_msecs'
This change should be immediate - media will be detected. However, the above change will be lost when you reboot.

References:
linuxfromscratch.org
uam-can-now-mount-cds-and-dvds
bugs.archlinux.org
unix.stackexchange.com


Tasks
Contents Task Manager

Each SpaceFM window includes a single Task Manager which centrally manages the tasks of all panels in the window. The Task Manager is designed to eliminate annoying popup dialogs which interfere with user multi-tasking, and allows you to continue working while large files are being copied, etc. The Task Manager lists running tasks, automatically manages the task queue, allows you to stop, pause, queue, or resume tasks manually, and opens popup dialogs. Like most parts of SpaceFM, the Task Manager can also be customised with your own commands to control or interact with running tasks.

A task is a job initiated by the user, such as copying a file. Tasks come in two varieties: internal and exec. Internal tasks handle built-in functions such as a copying, moving, and deleting files, while an exec task runs an executable or script, either initiated from within SpaceFM's built-in functions (such as running udevil to unmount a device) or from a custom command. The output of exec tasks is also collected and shown in the popup dialog's output monitor.

The Task Manager is located at the bottom of the SpaceFM window, below all panels. It has two display modes: Show and Auto-Hide. If option View|Task Manager|Show Manager is selected, the Task Manager is always visible, even when no tasks are running. Or, if option View|Task Manager|Auto-Hide Manager is selected (the default), the Task Manager will become visible when tasks are running, and will be automatically hidden from view when the last task completes. The size of the Task Manager may be adjusted by dragging the pane separator above it.

When a task is initiated in any panel and runs for longer than about one half second, it will be listed in the Task Manager, and the Task Manager will be shown if in Auto-Hide mode. If a task finishes in less than about one half second, the task will not be listed. New tasks are added to the end of the task list. When a task completes (successfully or with errors), it is immediately removed from the list.

Task Manager columns provide information on each task, and each column can be hidden or moved, allowing you to control what information is shown.

A single left-click on a task in the list, anywhere except in the Status column, will open a popup dialog showing the task's stats, a progress bar, and an output monitor. For internal tasks (copy, move, etc), the output monitor is used to show errors. For exec tasks, the output monitor shows the combined stdout and stderr output of the command as its produced.

A single left-click on the Status of a task, or a middle-click anywhere on a listed task will change its state (running, queued, or paused). Click repeatedly to achieve the desired state.

A right-click on a task shows the Task Manager's menu, which allows you to stop, pause, queue, and resume tasks, and also contains options for the Task Manager. (These same options may also be accessed via the main menu bar's View|Task Manager submenu.)

Contents Queue

Each task listed in the Task Manager may be in one of three states: running, paused, or queued.

A running task is currently executing - files are being copied, or an executable is running, etc.

A paused task has been halted. For internal tasks such as copy and move, the task thread is halted until you resume the task. For exec tasks (eg a custom command running an executable, or SpaceFM running udevil to unmount a device), the process has been sent a SIGSTOP signal as described in Pause.

A queued task is also halted. The only difference is that the Task Manager will automatically resume running a queued task when other tasks complete, whereas a paused task will never resume automatically.

A task's state (running, paused, or queued) can be changed by the user, and in some cases may be changed automatically.

Simply, the queue is used to prevent all tasks from running simultaneously, which can impact performance. For example, copying two sets of files to the same drive simultaneously is often slower than first copying one set, then the other (due to drive seeking and other issues). Thus it may be desirable to queue the second task, so it will remain halted until the first task is completed.

If option View|Task Manager|Queue|Queue New Tasks is checked (the default), new tasks are automatically queued when initiated, rather than run immediately. SpaceFM will automatically determine when to resume the queued tasks, depending on option View|Task Manager|Queue|Smart Queue. Or, you can always manually Resume, Pause or Stop a task to remove it from the queue.

Contents Menu

The Task Manager's context menu allows you to control tasks and set Task Manager options. The menu is opened by right-clicking on the list. The options found on this menu are also available in the main menu bar's View|Task Manager submenu (convenient if the Task Manager is hidden).

The context menu contains the following items:

Stop
Stop is used to stop the selected task. If the task is internal (such as copying files), SpaceFM will terminate the task thread, and the task will be removed from the Task Manager.

If the task is an exec task (eg a custom command running an executable, or SpaceFM running udevil to unmount a device), the process, and all its child processes, are sent a SIGTERM signal. This will usually cause the processes to terminate, but not always. So SpaceFM will also send a SIGKILL signal to all the processes several seconds later. An exec task will not be removed from the Task Manager until its process terminates. This means that if a process is hung and cannot be stopped with SIGKILL, selecting Stop may have no effect.

If the command was run as another user, such as root, selecting Stop will cause a prompt for the user's password (or root's password depending on your configured su program) to open. This password is required to send the SIGTERM and SIGKILL signals to the process running as another user. (You can see the exact commands being issued by running SpaceFM from a terminal and observing its stdout output.)

Paused and queued tasks may also be stopped.

You can also stop a task by clicking the Stop button in the task's popup dialog.

Pause
Pause temporarily halts a task, putting it into a paused state. It will remain in the paused state until you Resume, Queue or Stop it, and will never be automatically resumed or queued while paused.

If the task is internal (such as copying files), SpaceFM will suspend the task thread. Any files currently being read or written will remain open as long as the task is paused.

If the task is an exec task, the process, and all its child processes, are sent a SIGSTOP signal. This is similar to pressing Ctrl+S in a terminal while a command is running; it will often cause the process to temporarily halt execution. In some cases, a process will not halt on a SIGSTOP signal, but the Task Manager will still list it as being in a 'paused' state until you Resume the task.

If the command was run as another user, such as root, selecting Pause will cause a prompt for the user's password (or root's password depending on your configured su program) to open. This password is required to send the SIGSTOP signal to the process running as another user. (You can see the exact commands being issued by running SpaceFM from a terminal and observing its stdout output.)

If you change the menu icon for Pause, the new icon will also be used as the 'paused' icon in the task list.

You can also pause a task by clicking the Pause button in the task's popup dialog, left-clicking on the Status of a task in the Task Manager list, or by middle-clicking on a task in the list.

Queue
Selecting Queue will change the selected task's state to queued. In this state, the task is halted, but will resume automatically when other tasks complete.

Note that selecting Queue on a running task may seem to have no effect. This is because the task may be queued, but then may automatically be removed from the queue and resumed by the Task Manager. There is no way to force a task to stay in the queue (but you can Pause it).

If you change the menu icon for Queue, the new icon will also be used as the 'queued' icon in the task list.

You can also queue a task by clicking the Queue button in the task's popup dialog, left-clicking on the Status of a task in the Task Manager list, or by middle-clicking on a task in the list.

Resume
Resume starts the selected task, changing its state to running. If it was in the queue it will be removed from the queue and resumed, regardless of how it conflicts with other running tasks.

If the task is an exec task, the process, and all its child processes, are sent a SIGCONT signal. This is similar to pressing Ctrl+Q in a terminal after a command has been halted with Ctrl+S. If the original SIGSTOP halted the execution, SIGCONT should resume it. If SIGSTOP did not halt execution, SIGCONT will generally have no effect, except that the Task Manager will now list the task as 'running'.

If the command was run as another user, such as root, selecting Resume will cause a prompt for the user's password (or root's password depending on your configured su program) to open. This password is required to send the SIGCONT signal to the process running as another user. (You can see the exact commands being issued by running SpaceFM from a terminal and observing its stdout output.)

You can also resume a task by clicking the Resume button in the task's popup dialog, left-clicking on the Status of a task in the Task Manager list, or by middle-clicking on a task in the list. Tasks may also be resumed automatically by the Task Manager if they are queued.

Show Output
The Show Output menu item will only appear if a custom popup handler has been set for the selected task. Show Output will raise the normal popup dialog for the task, showing any stdout/stderr output. This is particularly useful for debugging.

Note that any custom menu items added directly after Show Output will also only appear for tasks with a custom popup handler.

All Tasks
The All Tasks submenu is used to place all listed tasks into the selected state. The Stop, Pause, Queue, and Resume menu items in this submenu have the same effect as detailed above, except that all tasks are affected.

Selecting All Tasks|Queue will place all tasks in the 'queued' state momentarily, but note that one or more of the tasks may then be automatically removed from the queue and resumed.

Show Manager
The Task Manager has two display modes: Show and Auto-Hide. If option Show Manager is selected, the Task Manager is always visible, even when no tasks are running. The size of the Task Manager may be adjusted by dragging the pane separator above it.

This option is also available via the main menu bar's View|Task Manager submenu. You may also associate a key shortcut with it.

Auto-Hide Manager
If option Auto-Hide Manager is selected (the default), the Task Manager will become visible at the bottom of the window when any tasks are running, and will be hidden when the last task completes. This is a window space-saving feature.

Although there is no option to hide the Task Manager while tasks are listed, you can effectively hide it if desired by dragging the pane separator to the very bottom of the window. However, if you do so you should enable option View|Task Manager|Popups|Popup All Tasks, so that you are aware that tasks are running. This combination of a zero-height Task Manager and Popup All Tasks makes SpaceFM behave like a conventional file manager, showing a popup dialog when performing a task, rather than showing a list of tasks. You can also enable option View|Task Manager|Popups|Stay On Top if desired.

Columns
The Columns submenu is used to select which columns are visible in the Task Manager, and to select a font for the Task Manager. Each column provides information about the listed tasks. The following columns are available:

Column Information
Count The number of items processed thus far
Folder Directory containing current item
Item Filename of current item, or command name
To The task's destination directory, eg where files are being copied to
Progress A progress bar with percentage label
Total The task's processed and total sizes
Started Time task was started
Elapsed Elapsed running time of task
Current Speed The current speed of the task (based on previous 2 second interval)
Current Remain Estimated time remaining based on Current Speed
Average Speed The average speed of the task
Average Remain Estimated time remaining based on Average Speed

The current item refers to the file currently being processed in the task (copied, etc). For exec tasks, the Item column shows the name of the command in parentheses.

The Status column, which shows the task icon, current state (queued or paused) and task action (copying, moving, etc.), is not included in the Columns submenu because its visibility not optional.

The Reorder menu item shows a reminder: "To change the order of the columns, drag the column header to the desired location."

The Font menu item allows you to set a font for the Task Manager's list columns. Narrow fonts work well.

Note: The Columns submenu, and other Task Manager options, can also be found in the main menu bar's View|Task Manager submenu.

Popups|Popup All Tasks
The Popups submenu is used to configure the Task Manager's behavior for opening popup dialogs. If option Popup All Tasks is checked, a popup dialog will automatically open for any task which runs for longer than about one half second. If the task finishes successfully, the popup will automatically close. If errors occur, it will remain open for you to view the error messages.

If option Popup All Tasks is unchecked, a popup dialog will open for an internal task only if an error occurs. For custom commands, the popup behavior will depend on the command's popup settings. Note that if Popup All Tasks is checked, this overrides the command's popup settings.

Popup All Tasks makes SpaceFM behave like a conventional file manager with regard to progress dialogs. If the option is enabled, it is also feasible to effectively hide the Task Manager by dragging the pane separator to the very bottom of the window when unneeded. You will still be aware of tasks running due to the popups. Option Stay On Top also works well with this approach.

Popups|Stay On Top
If option Stay On Top is checked, any task's popup dialog, whether opened automatically or manually, will stay on top of the SpaceFM window. However, you can still click on visible portions of the main window. Changing this setting has no effect on dialogs which are already open.

If unchecked, popup dialogs may be placed beneath the main window.

Popups|Above Others
If option Above Others is checked, any task's popup dialog will be kept above all other windows when initially shown. Note that some window managers do not support keeping windows above others, and your window manager settings may override this behavior.

Popups|All Workspaces
If option All Workspaces is checked, any task's popup dialog will appear on all workspaces/desktops (will be set as sticky) when initially shown. Note that some window managers do not support sticking windows, and your window manager settings may override this behavior.

Popups|Detailed Stats
Detailed Stats affects how task stats are displayed in the 'Progress:' line of popup dialogs (seen in internal task dialogs only).

If unchecked, a brief stats line is shown. For example:

Progress: 204 M / 350 M (26 M/s) :05 remaining
In the above example, 204 MB of 350 MB has been processed at an average speed of 26 MB/s. The estimated time remaining until the task finishes is 5 seconds.

If option Detailed Stats is checked, more detailed stats are shown. For example:

Progress: #1 (204 M / 350 M) [:08] @cur 31 M/s (:06) @avg 26 M/s (:05)
The additional stats include the item count (#1), the elapsed running time of the task (8 seconds), the current speed of the task (31 M/s), and the estimated time remaining at the current speed (6 seconds). The current speed is measured based on the speed over the previous two second interval, whereas the average speed is based on the entire time the task has been running. The current speed is a more accurate measure of what is happening right now, and will fluctuate more, while the average speed is a better measure of the overall performance. The time remaining estimate based on the current speed shows how long the task will continue if it continues at the current speed. The time remaining estimate based on the average speed tends to be a more accurate estimate in general.

The information shown in the 'Progress:' line will match the information shown in the corresponding Task Manager columns.

Popups|Overwrite Option
If Overwrite Option is checked, the popup dialogs for internal tasks will show a drop-down list which displays and allows you to change the overwrite mode of the task. The list is not shown for exec tasks. For more information see Popup Dialog.

Popups|Error Option
If Error Option is checked, the popup dialogs for internal tasks will show a drop-down list which displays and allows you to change the error handling mode of the task. The list is not shown for exec tasks. For more information see Popup Dialog.

Popups|Font
The Font menu item allows you to set a font to be used in the output monitor of popup dialogs. For example, you might choose a fixed width font to make the monitor look more like a terminal.

This font may also be set by right-clicking on the output monitor of any task's popup dialog and selecting Font from the context menu.

The dialog font you select will be used for new dialogs only; currently open dialogs will not be affected. (You can close a dialog and re-open it to see the change.)

Errors
The Errors submenu contains a set of radio options which control how errors in internal tasks (such as copy and move) are handled by default. (These options have no effect on exec tasks such as custom commands.)

If option Stop If Error First is selected (the default), the task will be stopped by the Task Manager if an error occurs AND that error is encountered before the task has successfully processed one file. If an error occurs on later files in the task, the Task Manager will open a popup dialog to show the error, but subsequent actions in the task will continue to run. For example, if there are more files to be copied, SpaceFM will attempt to copy them despite any errors on previous files.

Stop If Error First is provided as a convenience option. Usually if the first action of a task fails, the rest of the task will fail as well, so it might as well be stopped rather than producing a long list of errors for every file in the task.

If option Stop On Any Error is instead selected, the Task Manager will stop if any error is encountered in the task, regardless of whether the error occurs on the first or later actions.

If option Continue is selected, the Task Manager will never stop an internal task due to errors. It will present the popup dialog on each error, and will list the errors in the output monitor, but subsequent actions in the task will continue. For example, if a set of files is being copied, and only one file in the middle produces a copy error, all the other files will still be copied. The popup dialog will show the error(s) for the file(s) which failed.

Continue is especially useful when copying large sets of files. If the task stops on errors, you might start the task and leave the computer, only to return to find that only a few files were copied before a single error stopped the entire task. If the task continues on errors, you'll return to find all the files copied except those with errors. You can then correct the problem files without having to restart and wait for the entire task again.

You can also change the error mode on a per task basis if View|Task Manager|Popups|Error Option is checked.

Queue|Queue New Tasks
If option Queue New Tasks is checked (the default), new internal tasks are queued instead of being run immediately. (exec tasks such as custom commands are never queued automatically.) The Task Manager will then automatically resume the task when other tasks finish. When you start new tasks while other tasks are still running, Queue New Tasks improves performance by not running all the tasks simultaneously (though some tasks may be run concurrently, depending on option Smart Queue).

If unchecked, new tasks are always run immediately, even if other tasks are already running, and the Task Manager will never automatically queue any task.

Regardless of how Queue New Tasks is set, you can always manually Queue, Pause or Resume any task.

Queue|Smart Queue
The Smart Queue option determines under what conditions the Task Manager will remove a task from the queue and resume it. If UNchecked, the queue is simple - only one internal task is run at a time, and other tasks are queued. (exec tasks such as custom commands are always run regardless of option Smart Queue.) When a task finishes, the next task is removed from the queue and resumed. If you always want SpaceFM to do only one file operation at a time, uncheck option Smart Queue. However, this may be less efficient.

If option Smart Queue is checked (the default), the Task Manager is more sophisticated in its handling of the queue to improve both performance and convenience. In general, tasks will not be run concurrently, but the following exceptions may be made if Smart Queue is checked:

Different Disks Exception
If two or more tasks involve files on mutually exclusive disks (parent devices), the Task Manager will run them concurrently.

To determine what devices a task involves, SpaceFM makes a list of all devices (and their parent devices, if the device is a partition) holding every file in the task, as well as the device of the destination directory, if applicable. If any devices in this list are the same as the devices in another task's devices list, the two tasks conflict and will not be run concurrently. Note that if the files of two tasks are located on different partitions on the same disk, they will conflict, and only one of the tasks will run. Note that all of the devices of the task are examined when a queue decision is made, not just the device of the file currently in use by the task.

The reason for this exception is that if two tasks involve mutually exclusive disks, there is usually much less of a performance loss by running them together. On the other hand, if two tasks share files on the same disk, running them together may cause excessive drive seeking as different files are concurrently read and written. Thus no exception is made for such tasks, and only one is resumed at a time.

Size Exceptions
Often while copying a set of large files, you may want to perform a quick operation on a set of small files. Because the latter task is brief, it is reasonably efficient to allow it to run concurrently. This way you don't have to wait for the longer task to finish before your quick task is run.

When a task involves copying or moving a set of files less than 10 MB in total size, an exception is made which allows the task to run immediately, even if other tasks are running on the same devices. An exception is also made when a task involves deleting a set of files less than 5 GB in total size. This allows small tasks to run immediately.

Functional Exceptions
Internal tasks involving creating links, and changing file permissions or ownership are typically very fast as little data is written to disk. Thus an exception is always made for these task types - they are run immediately.

Also note that you can always manually Queue, Pause or Resume any task, regardless of the Task Manager's queue settings. For example, if you want a task to run immediately even though the Task Manager made no exception for it, you can Resume it yourself.

HAL NOTE:: If you are using a copy of SpaceFM built with configure option --enable-hal, or a HAL-based SpaceFM package, option Smart Queue will be unavailable.

Queue|Pause On Error
If option Pause On Error is checked, when an error occurs in any running task, all queued tasks will be paused. Tasks which are already running will not be paused. The task in which the error occurs may continue running as well, depending on its error mode.

The paused tasks will not resume until you manually resume them.

Pause On Error is something of a paranoia setting - it ensures that if an error occurs, later tasks (which may depend on files in the task with errors) are suspended until you can examine the problem.

Custom Menus
As with most menus, it is also possible to add your own custom menu items and submenus to the Task Manager's context menu using Design Mode. This allows you to add commands which can control or interact with running tasks.

There are several provided bash variables which your commands can use to get information about the currently selected task: 

    "fm_task_type"            currently SELECTED task type (eg 'run','copy')
    "fm_task_name"            selected task name (custom menu item name)
    "fm_task_pwd"             selected task working directory ( same as %t )
    "fm_task_pid"             selected task pid               ( same as %p )
    "fm_task_command"         selected task command
Note that the PID of the task refers to the initial process started by SpaceFM. The actual process you want to control may be a child of this PID.

For example, to add a custom command which opens the working directory of the currently selected task, use this command line: 

    spacefm "$fm_task_pwd"


Contents Popup Dialog

A single left-click on a task listed in the Task Manager will open a popup dialog showing stats, a progress bar, and an output monitor. Popup dialogs may also be automatically shown when errors occur, if option View|Task Manager|Popups|Popup All Tasks is checked, or based on a custom command's popup settings. The popup dialog's relationship to other windows may be controlled with options View|Task Manager|Popups|Stay On Top, Above Others, and All Workspaces.

For internal tasks, the popup dialog will show the task's job ("Copy", etc), the current file being processed, the destination directory, brief or detailed stats, the status of the task ("Paused", etc), a progress bar, an output monitor used to show the details of any errors which have occurred, and overwrite and error mode controls.

If View|Task Manager|Popups|Overwrite Option is checked and the task is internal, the popup dialog will show a drop-down list which displays and allows you to change the overwrite mode of the task (what happens when a file being copied already exists): Ask (prompt to rename, overwrite, or skip each file), Overwrite All (overwrite all files), Skip All (never overwrite files), or Auto Rename (assign a unique filename). Clicking the Overwrite All, Skip All, or Auto Rename All button in an overwrite query dialog will also change the overwrite mode. Note that the overwrite mode you set only applies to future file conflicts in the current task.

If View|Task Manager|Popups|Error Option is checked and the task is internal, the popup dialog will show a drop-down list which displays and allows you to change the error mode of the task: Stop If Error First, Stop On Any Error, or Continue. When the task first starts, the error mode will match the default set in View|Task Manager|Errors. If you then change the error mode, it will apply to the current task only.

For exec tasks, the popup dialog will show the title of the command being run, the task's status, a pulsing progress bar, and an output monitor showing any output from the command. The output monitor is designed to display text output to be used for monitoring the output of commands as they run, or to display a final result. However, the output monitor is not a terminal and does not allow you to enter input. If your command requires interaction, you will need to enable Run In Terminal instead. Custom commands can also set a custom popup handler to replace the normal popup dialog.

To close the dialog, press the Close button or close the window. You can always re-open the dialog by clicking on the task in the Task Manager.

To permanently stop a task, click the Stop button. This is equivalent to selecting Stop in the Task Manager menu.

The third button in the dialog will change depending on the state of the task. If the task is running, the button will be a Pause button; if the task is paused, the button will become a Queue button; and if the task is queued, the button will become a Resume button. Pressing this button is equivalent to selecting Pause, Queue, or Resume in the Task Manager's context menu.

Design Mode
Contents Introduction

SpaceFM's Design Mode allows you to change the name, shortcut key and icon of menu, toolbar and bookmark items; access help for an item; and set menu items to be disabled or hidden based on your context rules. You may add custom commands, applications, bookmarks, and submenus to any position in menus and toolbars, and save your custom items as plugins. Custom items can be cut/copied/pasted from/to bookmarks, toolbars, and menus. All of this is controlled from the Design Menu.

To open the Design Menu, simply right-click on a menu item, bookmark, or toolbar item. The Design Menu is available for most menus in SpaceFM, including in the right-click menu of the desktop.

To open the Design Menu using a shortcut key, press F2 while a menu item is highlighted. To open the Design Menu for a submenu, first close the submenu (by clicking on it), then right-click on the submenu name. Or, press F2 while the submenu is highlighted.

While Design Mode works in almost all menus, a good place to practice is the Tools menu, which is reserved for your custom menu items.

When working with Design Mode, it is important to distinguish between two types of items: built-in and custom. Built-in items, such as Rename on the file list context menu, are part of the SpaceFM program, whereas custom items are items you have added. Design Mode can be used on both types of items, but in different ways. For example, custom items can be removed, while built-in menu items cannot (although they can be hidden). You will note that some of the Design Menu's functions will be disabled or enabled depending on the type of item.

Custom items in SpaceFM are like word processor macros - they allow you to automate tasks. You might create a quick custom item just for today's use and delete it when you're done, while other items may become a regular part of your file manager use.

Custom items come in several varieties: a Bookmark (which opens a folder, group of folders, URLs, or mounts a device), an Application (which starts an application or runs an executable), a Command (which runs a command line or script), a Separator (a line separating items in a menu or toolbar), and a Submenu (a menu containing more custom items).

Contents Design Menu

When you right-click on a menu item, bookmark, or toolbar item, or press F2 while a menu item is highlighted, you will be presented with a menu which gives you extensive control over how the item is displayed and performs.

TIP: For help with a menu item in the Design Menu itself, highlight the Design Menu item and press F1.

Cut
The next items on the Design Menu, including Cut, Copy, and Paste, allow you to move and copy custom items. Items are cut, copied, and pasted in a similar way to how you cut, copy, and paste files or text, except that instead of the main clipboard, the design clipboard is used.

Cut cuts the current item onto the design clipboard. This will not affect the contents of your main (text & files) clipboard. You will not observe any change in the menu after cutting an item - until you paste it. You cannot cut built-in items (except on the toolbar), only custom ones. You can cut and copy submenus, which copies all the items within the submenu recursively.

You can also cut a menu item using a design mode shortcut instead of the Design Menu. Highlight the menu item and press Ctrl+X, or use the mouse shortcut Alt + Left-or-Right-Click.

Copy
Similarly, Copy copies the current item onto the design clipboard. Again, you will not observe any immediate change to the menu after copying an item, until you paste it. You cannot copy built-in items (except on the toolbar), only custom ones.

Note: When copying an item of type Bookmark, the bookmark target will also be copied to the text and primary clipboards.

You can also copy a menu item using a design mode shortcut instead of the Design Menu. Highlight the menu item and press Ctrl+C, or use the mouse shortcut Ctrl + Left-or-Right-Click.

Paste
If you previously cut or copied an item onto the design clipboard, it can be pasted into a menu, toolbar or the Booksmarks list. Determine where you want to paste the item, right-click on an existing item to open the Design Menu, and select Paste. The item will be copied or moved from its original location and will be placed after the item you clicked on.

For example, to move a custom menu item named 'Test' from the Tools menu to the file list's context menu: Open the Tools menu and right-click on 'Test' to open the Design Menu. Select Cut. Now right-click on the file list and right-click on a menu item, such as 'Rename'. Select Paste in the Design Menu. Right-click again on the file list and you will see your 'Test' command has been moved from the Tools menu and has been placed immediately after the 'Rename' item.

When copying a custom item, note that everything contained in the item is copied, including any command script, extra files you added to the command or data directories, settings, etc.

You can also copy plugins from the Plugins menu (although you cannot cut them). When a plugin, which is root-installed and -protected, is copied, the copy is no longer protected by root. The copy is now a custom item which you can alter in any way. Copying a plugin provides a means of changing and customising it. It can also then be exported and reinstalled as a plugin. See the Plugins section for details.

Paste, Cut, and Copy can also be used on the separators between items. To move a custom item to directly after a separator, copy the item to the Design Menu, right-click on a separator, and select Paste. You can also cut, copy, and paste the separators themselves, providing they are not built-in.

You can also paste a menu item using a design mode shortcut instead of the Design Menu. Highlight the menu item and press Ctrl+V, or use the mouse shortcut Shift + Left-or-Right-Click.

Remove
Remove is used to remove any custom item. It cannot be used on built-in items, except in a toolbar. When used on a plugin, Remove will uninstall the plugin (root password required).

Unless you have unchecked option View|Preferences|Interface|Confirm delete/remove, you will be presented with a confirmation dialog before the item is removed.

IMPORTANT: When a custom item is removed, all files and settings are deleted, including any extra files you added to the command directory, any files stored in the command's data directory, and the command script. When a plugin is uninstalled using Remove, the plugin is removed for all users, and all settings, files and plugin-data for the plugin are deleted.

WHEN REMOVING A SUBMENU, all commands and submenus contained within it are deleted as described above.

Note that a submenu in SpaceFM can never be empty. As a result, if you remove the last item from a submenu, a new custom item named "New Command" or a default bookmark will automatically be added to it.

You can also remove a menu item using a design mode shortcut instead of the Design Menu. Highlight the menu item and press the Delete key, or use the mouse shortcut Ctrl + Shift + Middle-Click.

Export
The Export item, which is only available for custom items, will open a save dialog, allowing you to save the custom item into a plugin file. This is how plugins are created for SpaceFM - you create a custom item, then simply export it.

Once your item has been exported to a plugin file, the file can then be used to import the item back into either the Plugins menu or another menu or toolbar, or can be shared with other users of SpaceFM. Exporting also provides a mechanism for backing up custom items - the plugin file acts as a backup copy of your item which can always be imported into any SpaceFM session.

When using export on a plugin, a new plugin file is created - generally this creates a copy of the original plugin (unless you modified the installed plugin files as root).

You can also export a group of custom items into one plugin file by exporting a custom submenu, which means the plugin file will contain all items and submenus contained in the submenu. This provides way to share multiple related plugins in a single plugin file.

For more information on plugins, please see the Plugins section.

New|Bookmark
The New submenu of the Design Menu allows you to add a new custom item of a particular type: Bookmark, Application, Command, Submenu, or Separator.

New|Bookmark adds a new custom item of type Bookmark after the current item. You will be prompted to select a single target folder, and the Bookmark item will be added. To make further changes to your Bookmark item, right-click on it and select Properties. A Bookmark item's target may be a single folder to be opened when you activate the item, or it can be a semicolon-separated list of target folders, URLs, or devices.

Bookmarks in SpaceFM may be placed into any menu or toolbar, not just the Bookmarks menu.

New|Application
New|Application adds a new custom item of type Application after the current item. Initially, you will be prompted to select an application from a list of applications installed on your system, and the Application item will be added. To make further changes to your Application item, right-click on it and select Properties. An Application item's target may be a .desktop file or an executable file, as detailed in Item Properties.

New|Command
New|Command adds a new custom item of type Command after the current item. You will be prompted to enter a name for the new command. Next, the Item Properties dialog will open to the Command page, allowing you to enter your command line(s) to be run, or to edit a command script.

The command line accepts anything you would normally enter in a bash command line. It can be as simple as a program's name you want to run when this menu item is selected, or may include multiple lines and variables. For more information, please see the Command page.

For example, right-click on a menu item and select New|Command. Enter 'Current Time' for the item name. For the command line, enter: 

    date

And click OK. When you click the new 'Current Time' menu item, a dialog will open showing you the current date and time.

You can also add a new Command menu item using a design mode shortcut instead of the Design Menu. Highlight the menu item where you want to insert the new Command item, and press the Insert key, or use the mouse shortcut Ctrl + Shift + Left-or-Right-Click.

New|Submenu
New|Submenu adds a new submenu into the menu or toolbar after the current item. You will be prompted for the new submenu's name. Because a submenu in SpaceFM can never be empty, a new Command item named "New Command" or a default bookmark will automatically be added to the new submenu.

New|Separator
New|Separator adds a new separator line into the menu or toolbar after the current item. Design Mode works on separators too - right-click on a separator to open its Design Menu, which allows you to remove it, change its context rules, or paste items after it.

New|Import
The New|Import submenu allows you to import a plugin file or URL, inserting it as a new menu item or toolbar item after the current item. This is similar to using Plugins|Import, except that the new item is inserted immediately rather than copied to the design clipboard.

When imported into other menus, a plugin loses root protection and becomes a normal custom item.

Add
The Add submenu will only appear in the Design Menu when it is opened by right-clicking on a toolbar item. This menu allows you to add built-in items to the toolbar. These items have preset functions, but you can change their name, shortcut key, and icon. Once added, they can be cut, copied and pasted (within toolbars only).

Tooltips
The Tooltips checkbox item will only be visible in the Design Menu when it is opened by right-clicking on a toolbar item. Checking the Tooltips option will cause tooltips to be shown when the mouse hovers over a toolbar item (the item's name is shown). This setting is global (for all toolbars).

Help
Help opens contextual help for an item. For built-in items, the SpaceFM user's manual will be opened in your browser. If no help is currently available, Help will be disabled. [Note: Because the user's manual is still incomplete, not all items will have specific help available.]

Your browser may be customised in Help|Options|Browser, and a custom location for the user's manual can be set in Help|Options|Manual Location.

For custom items, including plugins, Help will open the plain text README file for the item in your text editor. If no README file exists for a custom menu item, selecting Help will create one for you to edit. This file may also be named 'README.mkd' or 'README.txt'.

You can also open help for a menu item using a design mode shortcut instead of the Design Menu. Highlight the menu item and press F1, or use the mouse shortcut Alt + Middle-Click. F1 may also be used from within the Design Menu itself to show help for a Design Menu item.

Key Shortcut
Key Shortcut opens a dialog which allows you to bind any shortcut key to the current item, and to change or unset an existing shortcut key. When you select Key Shortcut, a dialog will open asking you to press your key combination (for example Ctrl+G), and the keycode will be displayed. If the key combination is already in use, you will be told what function the key is currently assigned to and be given the option to replace the current assignment. Once you have pressed the desired key combination, click the Set button. Or, to unset the current key assignment, leaving no key assigned to this menu item, click the Unset button. The Key Shortcut option can be used on built-in and custom items, but cannot be used on a submenu.

After you have set a key combination, when you reopen the menu the new key shortcut will be displayed in the menu.

TIP: To use only the keyboard in the Set Key dialog, press a key combination and then press Enter to click the Set button. Or, to click Unset, press the Escape key twice. To cancel, simply close the dialog (usually Alt-F4).

NOTE: Due to SpaceFM's literal use of keycodes, turning Caps Lock on or changing your keyboard layout may cause some key shortcuts to not respond. For example, pressing Ctrl+C with Caps Lock on will not activate 'Copy' because the 'C' key returns a different code than with Caps Lock off. Also note that some keycodes for non-Latin keyboard layouts are converted to their approximate Latin equivalent [SpaceFM 1.0.3 and later]. If such a conversion is made, the original keycode will be shown in square brackets.

You can also change the key for a menu item using a design mode shortcut instead of the Design Menu. Highlight the menu item and press Ctrl+K, or use the mouse shortcut Ctrl + Middle-Click.

Edit Command
Appearing only for custom items of type Command where the command is set to a command line, Edit Command opens the Item Properties dialog to the Command page.

You can also edit an item's command line using a design mode shortcut instead of the Design Menu. Highlight the menu item and press F4 or Ctrl+E, or use the mouse shortcut Middle-Click.

Edit Script
Appearing only for custom items of type Command where the command is set to a script, Edit Script opens the command script in your configured editor.

You can also edit an item's script using a design mode shortcut instead of the Design Menu. Highlight the menu item and press F4 or Ctrl+E, or use the mouse shortcut Middle-Click.

Properties
Properties opens the Item Properties dialog for the current item, allowing you to change properties for the item as detailed in Item Properties below.

You can also open Item Properties for a menu item using a design mode shortcut instead of the Design Menu. Highlight the menu item and press F3, or use the mouse shortcut Ctrl + Alt + Middle-Click.

Contents