NAME

sff — simple and fast terminal file manager

SYNOPSIS

DESCRIPTION

sff (simple file finder) is a simple, fast, and feature-rich terminal file manager inspired by nnn and guided by the suckless philosophy. It consists of two parts: a core program and an extension script. The core program is designed as a pure file browser and selector with minimal built-in functionality. All file operations, such as copying, moving, and deleting, are implemented by the extension script. For more details, see the EXTENSION SCRIPT section.

sff opens the current working directory if path is not specified.

OPTIONS

The following options are available:

-b

Force the program to run in browse mode. For more details, see the RUNNING MODE section.

-c

Enable case sensitivity when sorting by filename.

-d keys

Specify the details to show by default. Valid keys include:

- t: time
- o: owner & group
- p: permissions
- s: size
- n: none

-H

Show hidden files.

-h

Display program help and exit.

-m

Mix directories and files when sorting.

-v

Print version information and exit.

KEY BINDINGS

Press '?' or 'F1' in sff to see the list of key bindings for built-in functions.

Press Alt+'/' in sff to see the list of key bindings for extension functions and plugins.

CONFIGURATION

sff does not use a runtime configuration file. To customize sff, you need to edit config.h and recompile the program. config.h is a source code file which is included by sff.c (the main source code module). It is a C language header file, and serves as the configuration file for default settings, key bindings, and colors.

EXTENSION SCRIPT

The extension functions are provided by a POSIX-compliant shell script named sff-extfunc, which is installed by default in /usr/libexec/sff/
or /usr/local/libexec/sff/.

You can easily customize key bindings for extension functions and plugins, modify existing functions, or add your own functions by editing this file. It is generally not recommended to directly modify the system-wide sff-extfunc. Instead, copy it to the user's config directory and make modifications there.

The user's config directory is required for executing extension functions. This directory is either $XDG_CONFIG_HOME/sff or ~/.config/sff, whichever is encountered first. If this directory does not exist, the program will attempt to create it when calling an extension function.

During initialization, sff determines the location of sff-extfunc by checking the following directories in order, and uses the first occurrence found:

1. The user's config directory
2. The directory where the sff executable resides
3. /usr/libexec/sff/ or /usr/local/libexec/sff/

TABS

The tab status is displayed in the top-left corner of the screen. Five tab indicators are shown, with the current tab highlighted in reverse video. Tabs 1 through 4 are regular tabs and are indicated by '*' when inactive. When switching to an inactive tab, the new tab will be activated and use the current directory path as its starting path. The fifth tab is a special tab, indicated by '#', dedicated to handling search results.

SELECTION

The names of the selected files are highlighted in reverse video. By default, the file under the cursor is automatically selected. When a file selection operation is performed by the user, the program enters manual selection mode, and the file under the cursor will no longer be automatically selected. Clearing all selections causes the program to exit manual selection mode and return to the default state.

sff allows file selection across directories. Each tab maintains its own independent selection state. The second set of numbers in the bottom status bar (highlighted in reverse video) indicates the total number of selected files in the current tab.

When an extension function is executed, if it sends a request, the absolute paths of the selected files are delivered to the extension function via a FIFO.

FILTERS

Filters are strings used to dynamically list matching files in the current directory. When a filter is enabled, it appears above the bottom status bar, and the program enters input mode. In this mode, you can perform the following actions:

- Enter a filter matching string (matching is case-insensitive).

- Use the Up and Down Arrow keys to move the cursor.

- Press Enter or Esc to exit input mode while keeping the filter
active.

- Press '/' to disable the filter.

The filter only applies to the current directory. When navigating away from the current directory, the filter is automatically disabled.

QUICK FIND

Quick Find is used to quickly locate a file within the current directory. When Quick Find is enabled, it appears above the bottom status bar, and the program enters input mode. In this mode, you can perform the following actions:

- Enter a search string to match filenames.

- Enter '/' as the first character to navigate to the root directory.

- Press Tab or '/' to enter the directory under the cursor and clear
the search string.

- Press the Left Arrow key to go to the parent directory.

- Use the Up and Down Arrow keys to move the cursor.

- Press Enter or Esc to exit Quick Find.

Matching is case-insensitive and prioritizes matches at the beginning of filenames. If no filename starts with the search string, it matches filenames containing the string. Upon a match, the cursor jumps to the first matching file.

ADVANCED SEARCH

Advanced Search is an extension function based on the find command. It requires two inputs:

1. Filename pattern: This is passed to the -name option of the find
command. So remember to use wildcards when necessary. For example,
to search for files containing 'lib' in their name, enter '*lib*'
instead of just 'lib'. If you do not want to search by filename,
enter '*' to match all files.

2. Additional search options: Here, you can provide more options for
the find command, such as '-size +4k' to search for files larger
than 4KB. If no additional options are needed, leave this field
blank and press Enter.

After both inputs are provided, the executed command will be:

find ./ input2 -name "input1"

The search results are sent back to sff and listed in the fifth tab, where you can further process them.

UNDO AND REDO

sff supports undoing or redoing the last file operation. Supported operations include:

- Create new files
- Copy-paste (when none of the pasted files already exist)
- Cut-paste (when none of the pasted files already exist)
- Rename
- Duplicate

Undo/redo actions apply across different tabs and even different sff instances. A file operation performed in one sff instance can be undone or redone in another instance.

RUNNING MODE

Browse Mode:
A green reversed 'B' is displayed in the bottom-left corner of the screen as an indicator.

This can be considered a safe mode. In this mode, extension functions are disabled, and sff does not make any changes to the file system.

The program is forced into browse mode and cannot exit this mode until termination under the following conditions:

- When the -b option is used while running sff
- During initialization, if certain non-fatal errors occur
(e.g., the sff-extfunc file is missing).

Sudo Mode:
A red reversed 'S' is displayed in the bottom-left corner of the screen as an indicator.

When sff is run as a regular user and switched to sudo mode, the following operations are executed with superuser privileges:

- All extension functions
- File editing

However, all other operations are still performed by the current user.

When sff is run as the superuser, the program will always run in sudo mode until termination or can be switched to browse mode. All operations are performed by the superuser.

PLUGINS

Plugins are shell scripts used to extend functionality. They are invoked by the extension script, which also sets their keybindings. By default, plugins are installed in /usr/libexec/sff/plugins/ or /usr/local/libexec/sff/plugins/.

Detailed information about a plugin should usually be provided as comments at the beginning of the script. To view this information, refer directly to the plugin file.

If you wish to modify or add your own plugins, it is recommended to do so in the plugins directory within the user's config directory. For details on the user's config directory, see the EXTENSION SCRIPT section. When the extension script invokes a plugin, it searches for the plugin in the following locations in order and uses the first match found:

1. The plugins directory in the user's config directory
2. The plugins directory where the currently running extension
script resides
3. /usr/libexec/sff/plugins/ or /usr/local/libexec/sff/plugins/

ENVIRONMENT

EDITOR: The default text editor used in the program. If not set, 'vi' is used.

HOME: The home directory used by the program. If not set, '/' is used.

AUTHORS

Shi Yanling <sylphenix@outlook.com>

HOMEPAGE

https://codeberg.org/sylphenix/sff