Skip to content
SquirreljetpackPublic

Repository files navigation

F:st

F:st is a tactile file manager that runs in your terminal.


Size-sorted file list filtered to images, with a photo preview

The filesystem is a gnarly, sprawling beast. Attempting to navigate it in the terminal is a miserable experience, and built-in file managers are not much better. How do you organize items you downloaded, find a file you edited last week, check your most visited directories, convert media files, find large files to free up disk space, swap two files, share files between devices, extract archives and so on and on?

The problem lies mostly with its strengths: scale and versatility. The first makes it difficult to navigate, the second makes it awkward to manipulate — too few features and you can't do what you need to, too many and things get bloated. But the problem is maybe not an impossible one.

F:st provides just one view, a single list of files, and polishes that view to the limit. The list can be the contents of a directory, or the results of a recursive search, a full text search, your recent files and folders, or other custom lists. Importantly, these searches run extremely efficiently, indexing your entire filesystem in seconds, after which the fuzzy filter1 floats just the ones you were thinking of to the top. No matter where you need to be, there you are (in a couple of keystrokes)2.

The second problem, which puts power and complexity at odds with each other, is really a problem of strategy. Most of the things we need from our files fall into a few broad categories: opening, previewing, editing, checking metadata3, as well as a few others. F:st provides a preconfigured dispatcher, so that you can do things without needing to think about how to do them. For example, the right arrow key steps into things: it enters directly into directories, archives and volumes, opens files in your editor and images in a viewer.

For all else, such as media conversion, comparing directories, sending files and other odd tools which are occasionally useful to have on hand, f:st provides an extensible contextual menu. The same principles that guide the rest of the app are applied here: clutter is reduced by only showing actions valid on the current selections, the help menu is always available for a description of the available options, and the execution model is tightly integrated with other features of f:st, allowing you to bind, background and queue tasks — the purpose of minimal interface is to clarify the power and flexibility concealed beneath.

Good tools should feel comfortable to pick up and use. In many words, they should be intuitive and responsive, transparent in what they do, adaptable to your preferences and rewarding to master, staying out of the way while delivering power and utility as naturally as an extension of your self.

In one word, they should be tactile4.

Installation

Install the required dependencies:

cargo install fd-find ripgrep
# (optional)
cargo install bat eza kreuzberg mediainfo

# If you don't have cargo, all of these are available on almost any package manager of your choice

Get the binary with the install script (or choose one of the options below)

curl -fsSL https://raw.githubusercontent.com/Squirreljetpack/fist/main/install.sh | sh
powershell -ExecutionPolicy Bypass -c "irm https://github.com/Squirreljetpack/fist/releases/latest/download/fist-installer.ps1 | iex"

Call as:

  • fs: Directory navigation
  • fs [..paths] pattern: interactive find
  • z [query]: directory jump (requires shell integration)

Finally, when you're ready, initialize the configuration files, and download some menu actions!

fs --dump-config

Homebrew
brew install Squirreljetpack/tap/fist
AUR
yay -S fist-bin
npm
npm install -g @squirreljetpack/fist
Cargo

Build from a clone5:

git clone https://github.com/Squirreljetpack/fist
cd fist
cargo build --release

Commands

Bindings overview

  • Up/Down: Navigate (or Up in the initial position to to enter prompt).
  • Left/Right: Back/Enter.
  • Enter: Default (system) open.
    • Alt-Enter: Print / Alternate open.
    • Ctrl-Enter: Open in background.
    • alt-n: Reveal (in editor).

  • ctrl-f/ctrl-r: Find files / Search text.
  • ctrl-g: History view (Folders and files).
  • ctrl-z/alt-z: Undo / Redo.

  • ctrl-x/ctrl-c/ctrl-v: Move, Copy, Paste.
  • ctrl-y: Copy the path.
  • delete/shift-delete: Trash/Delete.
  • alt-e: Open menu.
  • alt-u: Open queue.
  • alt-p : Open options.
  • ctrl-s/alt-h: Toggle hidden.
  • ctrl-d: Cycle filter/sort.

  • Tab: Toggle select.
  • alt-enter: Print.
  • ?: toggle preview.
  • alt-/: toggle informative preview.
  • ctrl-l: Maximize preview.
  • alt-l: Maximize extended preview.
  • / and ~: Jump to home
  • ctrl-1..ctrl-9: JumpOrAccept
  • alt-space: JumpOrAccept(prompt)
  • ctrl-space, alt-hyphen: toggle prompt lock

Pressing alt-h within the app displays your available binds as part of the help.

Configuration

Documentation for configuration can be found in config.md, mm.md.

You can also get it straight from the source: Main Config, Panes, Styling, Miscellaneous UI, Lessfilter, Lessfilter, Matchmaker Config.

fs :tool check checks your configuration files and installed menu actions for errors.

Panes

Nav

To begin, call fs without any positional arguments.

Navigation pane with a fuzzy query and a directory-tree preview

Once inside, you can navigate and re-enter from other panes by pressing the left/right arrow keys (corresponding to the Parent/ Advance actions). Press alt-h to show a full list of available actions.

Prompt locking

Note

The following describes what is probably the least straightforward feature of F:st. Hopefully, it will make more sense when you start to use it. If not, the behavior comes from a block of bind definitions in mm.toml6 that you can delete to disable.

F:st binds left/right to actions to emulate a traditional file manager experience and to keep all the (most useful) navigation keys together. Unfortunately, because the prompt is also available for typing, the ForwardChar/BackwardChar actions end up bound to shift-left/right, and this can be a bit unexpected at first. To prevent accidents in query-reliant panes like Find or Search, the query bar locks when entering these panes: indicated by a red underline. When the prompt is locked, the left/right and shift-left/right keys switch roles, so that left/right reverts to only moving the caret in your query. ctrl+backspace also returns to DeleteWord instead of Trash.

The locked state can also be entered by entering the prompt -- pressing up at the first result, (or down at the last with results.cycle). Note that in_prompt ⇒ locked_prompt: in this state, the prompt displays your current directory, and all actions apply to that instead. To exit the prompt, just press up or down again. To toggle the locked state, press ctrl-space or alt-hyphen7 -- but this is not often necessary. alt-space jumps to the locked cwd and then accepts it.

Find

You can search through all files recursively by

  • using the subcommand: fs :: [OPTIONS] [PATHS]... [PATTERN]
  • by calling fs directly with the same arguments
  • or by triggering the Find action (ctrl-f) in-app.

Find pane with a fuzzy query and a markdown preview

This is the same as the Nav view before, only a different list.

Note

f:st uses fd for this internally, and that search parameters can be passed through directly following --. However, it is not a strict wrapper and several differences in behavior in the command specification exist:

  • The last positional argument is treated as the query instead of the first
  • queries beginning with . auto-enables the inclusion of hidden files
  • Default parameters, directory-specific ignores, and other parameters can be set in the config.
  • The -t (type) flag has be overloaded to support more conditions. In addition to file types (directory/d, symlink/l, ..etc. ), it now supports extensions (-t .ext), pre-set categories (image/i, video/v), and custom categories as well.

Search

You can perform a full text search

  • using the subcommand: fs : [OPTIONS] [PATTERNS]... [-- <RG_ARGS>...]
  • or by triggering the Search action (ctrl-r) in-app.

In f:st, each result displays two columns: the filepath, and a context column8.

In this pane, the context column contains the query matches and surrounding context.

This pane operates in a query and a filter mode, which can be switched between with ctrl-r:

  • In query mode, the results are populated with all text matches of a your main query.
  • In filter mode, the results are filtered to only lines matching your filter query.
  • By default, the filter applies to the main (first) column. This allows you to easily look for all text matches restricted the results to a specific file extension or pattern9.
  • In query mode, multiple queries (results must match at least one) are seperated by whitespace. Queries containing whitespace can be grouped together by single quotes. Single quotes can be escaped as \'.
  • The default mode treats the given queries as regexes (as opposed to the filter input, which does not).

Note

When the active item is advance/executed on, the matched line and column are saved in the environment variables HIGHLIGHT_LINE and HIGHLIGHT_COLUMN. If your $EDITOR is supported, the Lessfilter::Edit action (which advance dispatches to) automatically opens the file to the corresponding position (you can also configure this manually).

Search pane with query results and a context column

Stream/Custom

f:st can also accept arbitrary lists of files from a command or input stream through the :custom subcommand (fs :custom [CMD]..., where an empty command reads from stdin), where all the usual operations are available:

  • directory traversal
  • file create/edit/delete/custom actions relative to the current item/directory.
  • enriched display
  • full text search
  • reversible actions
  • preview
  • filtering and sorting
  • and so on.

A complete example of a notes manager this can be used for can be found here.

Custom stream pane listing markdown notes with a filtered preview

History

f:st records the files, directories and applications that you've visited in a local database, where they are displayed in the Files/Folders (ctrl-g) and Apps panes, sorted by relevance10.

History pane listing recently visited files with a markdown preview

The Files and Folders panes are most useful when integrated into the ambient context where you usually access files. For example, the shell, or a command launcher.

Stashes

PushStash(name) adds the selection (or the current directory while the cursor is disabled) to a named stash, and OpenStash(name) switches to its pane. Stash panes are transient or database-backed collections of paths, useful for scratch space or bookmarking.

Stash pane holding three pushed entries, with a directory-tree preview

By default, alt-s and alt-b are bound to "smart" Stash(name) actions for the default (transient) and bookmark (persistent) stashes:

  • if items are selected, they are pushed
  • if you are already in the stash, it backs you out
  • otherwise, it enters the stash pane

Note

Combined with contextual Menu actions, they are f:st's answer to all cross-directory workflows, such as comparing files and folders, archiving, or bulk-renaming: just push everything to the stash and run your action on there.

App

The apps pane comes prepopulated from the existing applications on your system, and can be accessed either through

  • fs :o on the command-line
  • the open with menu action
  • a custom binding for the App action.

Apps pane with a pending file and an application icon preview

It can be used to select a launch method for a given set of files (provided through the command line, or collected in the app view's pending files).

Options

Every pane has a Options overlay (alt-p), with settings for filtering, sorting, and other pane-specific controls for the displayed results.

Options overlay with filter and sort controls

Selecting a sort does not interrupt the current results; items are resorted on the fly. The active sort key is displayed on the right.

Panes can also configure a default sort. This applies a soft sort to the results: the ordering reflects a combination of query relevance and the sort order. The sort key is not displayed when soft sorting is active. In the Files/Folders/Apps/Search panes, sorting is always soft: the initial ordering is still faithful to the sort key.

Additional notes

Panes can be navigated between using the Undo/Redo actions.

For more information on any of the panes, run fs [pane] --help with the appropriate subcommand (i.e. :rg), trigger the in-app help menu, or consult the docs.

Actions

Menu

The Menu (alt-e) houses all the actions available in the current context.

Action menu over a document preview, listing copy, move, rename and delete actions

Custom actions can be added in actions.toml and from files in actions/. They consist of 3 parts:

  • Action: The lua script to execute.
  • Conditions: The various conditions which must be satisfied to show this action in the menu.
  • Execution: Parameters controlling how the action is executed.

You can find a couple official actions here, providing contextual actions for compression and comparison (of files/folders). Just download them into <FIST_CONFIG_PATH>/actions to enable them.

For more information, consult the docs.

Binds

Another way to define arbitrary execution flows is by adding to the [binds] section in your mm.toml configuration file11.

A typical binding looks like this:

"tab" = ["ToggleSelection", "Down"]

where a key is bound to a sequence of actions12. The full list of actions is available here, a couple the ones you may be interested in for customization are:

  • Lessfilter: Execute an action on the current item according to lessfilter rules.
  • Preview/LfPreview/RunPreview/ShowPreview: Change the preview display, run or maximize the current Preview.
  • The Exec family: run a command and wait for it/forget about it/display it in pager/copy it/transform f:st into it (Become($EDITOR {})) etc.
  • Queue-related actions, as mentioned below.

For example, the default mm.toml binds Ctrl-Esc to Execute($SHELL): the inner string is executed in your shell environment, allowing you to drop into a shell from your current directory in f:st.

Moreover, f:st uses the same system for bindings as matchmaker, with only the app-specific actions differing. This entails some niche but maybe cool features, such as that not only keys, but events can be bound to, and also that bindings can also be mode-specific, such as being present only on certain pane types, or when the prompt is locked.

Queue

Queue overlay with pending copy and move operations

The Queue overlay (alt-u) lists the pending file operations. Rows show their kind, source, destination, and progress, and can be edited, rearranged, cancelled, filtered, removed and executed from the overlay.

The Move and Copy13 actions enqueue items under the move and copy kinds. Paste (ctrl-v) executes every queued copy, move and symlink item without enterring the overlay, transferring files into the active directory. The other relevant actions are: ExecuteQueue(selector), Enqueue(kind) and ClearQueue(selector)14.

Menu actions with the Queue/Enqueue/QueueBatch strategies enqueue their targets under the action's key. On execution the action's lua script runs once per queued item with (paths, to, nav_cwd?)15.

Tools

f:st comes with several secondary subcommands for reference and utilitary purposes. They can listed with fs :tool.

Shell integration

The output of fs :tool shell will, when sourced, provide the jump, nav, history-open, and interactive line-editor widget functions:

Zsh / Bash / POSIX
eval "$(fs :tool shell)"
Fish
fs :tool shell --shell=fish | source
Nushell
# 1. Generate the script once in your terminal:
fs :tool shell --shell=nu | save -f ~/.config/nushell/fist.nu

# 2. Add to your config.nu ($nu.config-path):
source ~/.config/nushell/fist.nu

The jump function (z) is a replacement for cd, except that incomplete queries are matched to a most likely destination drawn from the unified f:st database. This behavior is inspired by zoxide16.

Note

In addition, a couple special queries can be used to start an interactive search:

  • the only argument is a valid path: cd.
  • no arguments: interactively select from history.
  • last argument is . : interactively search subdirectories of the best match.
  • a valid path directly before a trailing ././ is that pane's target rather than a query.
  • otherwise: cd into the best match for the search term (if one exists)17.

One final change from zoxide is the introduction of the history.refind setting. When no match is found, or when the top result is the current directory, this setting automatically start the interactive interface.

The open function (Z) brings a similar functionality to files, opening18 matches from your file history (open directories with a trailing .).

The line-editor widget functions push your selected paths onto your command line. By default, shift-left binds to recursive directory search, shift-right binds to recursive file search. There is also a full-text search widget bound to shift-down: the default action opens your editor at the match, but you can still push paths using alt-enter.

To disable any function/widget, just set its bind to an empty string.

Note

These are also fzf's default keybinds (and function similarily), so it's recommended to disable those when using f:st.

Also, before adding them to your shell startup, you can also run the output directly to try them out. On POSIX shells, this is just eval "$(fs :tool shell --myshell)".

Additional

Including the --aliases flag will add a few simple alias definitions into the initialization:

  • lessfilter
  • lz: directory display
  • l: lessfilter (display preset)
  • la: lessfilter (extended preset)
  • ll: lessfilter (info preset)
  • n: edit (lessfilter with edit preset)
  • o: open

For speed and safety, it is recommended pass your actual shell through to --shell19.

Lessfilter

The previewer is controlled by the lessfilter tool.

The lessfilter tool dispatches to 9 presets:

  • preview: the preview pane
  • display: terminal display
  • extended: terminal interaction or verbose display
  • info: metadata and raw information
  • open: system open
  • edit: editing
  • alternate and alternate2: extra presets for custom use

The info preset, using mediainfo to display image metadata

Images are rendered using the best supported graphics protocol of your terminal (sixel, kitty, or iTerm2), falling back to Unicode halfblocks otherwise.

An image preview rendered at pixel resolution with the sixel protocol

Each preset is configured by a rules table in the config file. Each rule is a pair (Actions, Patterns), and for a given file, the rule whose patterns score the highest is selected -- its actions are invoked on the target file. A more complete account can be found in the documentation.

f:st comes with a sane set of defaults with wide coverage for a variety of filetypes, and declaring overrides is as simple as declaring the desired action together with the conditions which it requires. For example:

### --- lessfilter.toml -- ###

preview = [
    # ...
    # On an file with mime-type sqlite-3 and a system with sqlite3, this rule gets a score of 20.
    # sqlite is a custom action whose definition can be found in the default lessfilter.toml configuration file.
    [["sqlite"], ["application/vnd.sqlite3", "have:sqlite3"]],
    # ...
]

# When invoking the edit action (in `fist` or through the `n` alias),
# any file belonging to this category will be opened with the system's default preferred application.
# Since this rule has minimal priority (at most 1), any subsequent rule will override it.
edit = [
    [
        ["Open"],
        [
            "1|cat:document",
            "1|cat:spreadsheet",
            "1|cat:email",
            "1|cat:academic",
        ],
    ],
]

The built-in actions are:

  • Directory
  • Application
  • Text
  • Image
  • Extract
  • Metadata
  • Open
  • Header
  • None

Additional actions can be defined via the same same shell + templating syntax as actions under [bind]. For example:

[rules]
alternate = [
    [["code"], ["*/*"]],
]
[actions]
code = 'code --add {}'

Note that certain default previews will not display without the required dependencies.

If something is not resolving properly, fs :tool lessfilter --diagnose <PATH> shows you how and why your configuration resolves as it does on a given file.

Others

fs exposes several of the more generally useful functionalities it uses internally:

  • diskspace: A stupid fast parallel directory tree/size lister, using the same background worker that is used in the main app for sorting by size.

  • trash: cross platform tool for easily moving files to the system trash.

  • action: run a menu action directly

  • check: verify your configuration

  • types: a list of all supported types, used by the -t parameter of the find subcommand and the cat condition of the lessfilter.

  • as for the rest, run fs :tool to see a full listing.

Additional

fist integrates into CommandSpace, which you may also enjoy checking out.

Full uninstallation

  1. Remove binary:

    # Installed via cargo:
    cargo uninstall fist
    # Installed via install script:
    rm -f ~/.cargo/bin/fs /usr/local/bin/fs
  2. Remove shell integration:

    • Bash / Zsh / POSIX: Remove eval "$(fs :tool shell)" from ~/.bashrc or ~/.zshrc.
    • Nushell: Remove source ~/.config/nushell/fist.nu from ~/.config/nushell/config.nu and delete ~/.config/nushell/fist.nu.
    • Fish: Remove fs :tool shell --shell=fish | source from ~/.config/fish/config.fish.
  3. Remove configuration, state, and cache:

    rm -rf ~/.config/fist ~/.local/state/fist ~/.cache/fist

Docs

Help is plentiful and always readily accessible: in the user documentation, from the command line via --help, or in-app via alt-h.

License

F:st is licensed under the GNU Affero General Public License, version 3. See LICENSE.

Footnotes

  1. optionally typo-resistant or regex-driven ↩

  2. Compare this to having to use standard file managers or cli tools, where you need to learn filter grammars or organizational schemes. Here, the process is always the same: choose the list type, (optionally, choose a sort or filter), and type in a fragment of the file's path. Then, to return, ctrl-z takes you back in the pane stack. ↩

  3. image dimensions, media type, encoding ↩

  4. If f:st does not live up to that standard in any way, let me know! ↩

  5. f:st depends on the patches in .cargo/config.toml crates, so you must either clone the repository, or export the variables in there before running cargo install fist. ↩

  6. One of the guiding heuristics of the project is to provide the best out-of-the-box experience through opiniated defaults, but full power should always remain with the user: underneath the surface, everything is customizable or extensible. ↩

  7. necessarily, this will also drop you out of the prompt if you were in it ↩

  8. In the previous panes, the secondary column was simply empty and therefore not displayed. ↩

  9. To switch to filtering the second column, type % (i.e. path_filter % context_filter). ↩

  10. frequency, recency, and similarity to query. ↩

  11. fs --dump-config to initialize it ↩

  12. These are code-styled and camel-cased throughout this document (i.e. PushStash). ↩

  13. This action also copies the file to your system clipboard. ↩

  14. selector is similar to kind, but with the addition of the reserved strings all (default), first, last, and builtins (i.e. Paste is just ExecuteQueue(builtins)). Enqueue(kind) enqueues the current selection under the referenced kind (for custom actions, the conditions must be satisfied). ↩

  15. Supplied when executed from a nav pane. ↩

  16. f:st uses an improved implementation by default I adopted after seeing this project, although the simple zoxide implementation can be enabled by disabling lambda:

    Event clock: zoxide score decay is coupled to wall-clock time. The problem is that after any extended period of inactivity, all scores decay toward zero, and the first directories visited on return immediately dominate the ranking regardless of prior history. f:st replaces wall-clock time with an event clock: each cd action advances the clock by one tick. The clock stands still during inactive periods and no score decay occurs during such periods.

    Scoring: Items are sorted by score. In zoxide, the score is computed as count * recency bucket. f:st replaces this with a monoexponential decay kernel. The decay rate is controlled by lambda (default 8e-3, equating to a half-life of about 87 actions).

    Unified database: f:st maintains a single SQLite database tracking files, directories, and applications together.

    Pruning: Pruning happens automatically and lazily once db exceeds a certain size. For more information, see fs :tool bump --help.

    Interactive fallback: When no match is found, or when the top result is the current directory, f:st can be configured to start an interactive search interface instead of failing. ↩

  17. There is one final case: if the last argument is ./: z interactively navigates the best match. This is also provided directly by x (configurable via --nav-name). ↩

  18. using the lessfilter edit preset. ↩

  19. Another optimization you can make is to cache the generated command: my zcomet fork supports this. ↩