Skip to content
SquirreljetpackPublic

Repository files navigation

F:st

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


In project management there is an iron law: “Cheap, fast, good. Choose two”.

Miraculously, f:st manages to escape this law. Its motto goes something more like this: "Free, fast, good... simple, extensible, customizable, minimalistic, powerful, versatile, consistent, cohesive, flexibile, efficient, modular, portable. Take all of them!".

It is a program at once as revolutionary as a comet, and as familiar as an old sock. It takes the greatest ideas for command-line tools in recent history, and combines them into a cohesive experience that makes interacting with the filesystem so fluid, so efficient it will feel like you were born in it, moulded by it. Once adopted, the only barriers that remain will be those imposed by your own thoughts; and if you ever again return to the old ways, you will be blinded by their slowness.


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

It all starts with the pane, a dropdown list of all the items in your current directory. Type to filter, navigate with the arrow keys, a preview window to the side shows you the contents of the files, press alt-h to show a dynamic help menu with all available actions, and you can even use your mouse1. Everything that should run asynchronously does, so that the UI never stutters, and all effects are accompanied by toasts, so that you always know what exactly is going on.

All the rest of this app revolves around this interface, providing efficient ways to navigate, robust and optimized filesystem primitives2, smart previews, recents tracking, alterrnate views & lists, and a system for contextual actions. All of this on the same interface, with the help menu only ever being one keypress away, the net effect being that everything is within the reach of a few taps and nothing is overwhelming.

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 clone3:

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

For a full list of binds, press alt-h within the app4.

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).

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.toml5 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. On macos, cmd+delete 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-hyphen6 -- 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

The results will be available for filtering, navigating, editing, previewing etc. Filtering and sort order can be adjusted through the Options overlay.

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 column7.

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 pattern8.
  • 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 relevance9.

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 -w [..FILES] 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 file10.

A typical binding looks like this:

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

where a key is bound to a sequence of actions11. 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 Copy12 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)13.

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?)14.

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 zoxide15.

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)16.

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, opening17 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 --shell18.

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.

The score modifiers and their prefix syntax are:

  • >n|pattern: Max(n) — take the max of the current score with n.
    • The minimal syntax n| (such as 1|cat:...) is also supported.
  • <n|pattern: Min(n) — take the min of the current score with n.
  • +n|pattern: Add(n) — add n (or 1) to the current score.
  • -n|pattern: Sub(n) — subtract n (or 1) from the current score.
  • ^|pattern : Req — require the condition; sets the score to 0 if the test fails.
    • ^pattern is also supported.

The patterns and their default scores (used when no score prefix is specified) are:

  • glob: match the full path — Max(50)
  • child: match a child name (or a sibling name for a file) — Max(50)
  • ext: match a file extension — Max(30)
  • mime: match a MIME type such as text/plain or image/* — Max(20)
  • cat: match a built-in or configured file category — Max(20)
  • application: match a platform-specific application bundle, launcher, or executable — Max(60)
  • *: match any path — Max(0)
  • have: require an executable to exist — Req
  • filetype: require a matching filesystem type — Req
  • git: require a path inside a Git work tree — Req

Though the syntax has many parts, configuration should be fairly straightforward. 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.

Types

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

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.

  • pager: smart compatible pager that feeds bat for syntax highlighting into minus for modern aesthetics.

  • action: run a menu action directly

  • check: verify your configuration

  • 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. We hope you have a grand time with clicking, dragging, and scrolling. ↩

  2. Fast and error-proof copying, transparent decompression, re-filtering/sorting that runs on the fly etc. ↩

  3. f:st depends on patched crates, so it must be cloned and built in place; cargo install fist cannot apply those patches. ↩

  4. For more information on bindings (how they are defined, key testing, and default generic binds), see matchmaker. ↩

  5. 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. ↩

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

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

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

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

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

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

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

  13. 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). ↩

  14. Supplied when executed from a nav pane. ↩

  15. 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. ↩

  16. 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). ↩

  17. using the lessfilter edit preset. ↩

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