path: root/sfm.1

.TH SFM 1 "2026-03-16" "0.4" "Simple File Manager"

.SH NAME
sfm \- Simple File Manager

.SH SYNOPSIS
.B sfm
.RI [ path ]

.SH DESCRIPTION
.B sfm
is a lightweight, terminal-based file manager written entirely in POSIX sh.
It runs in your terminal with no external dependencies beyond standard Unix
tools. Designed to be fast, flicker-free, and keyboard-driven with a
vim-inspired key layout.

If
.I path
is given, sfm opens that directory. Otherwise it opens in the current
working directory.

.SH KEY BINDINGS

.SS Navigation
.TP
.BR j ", " k " or " "up/down arrows"
Move cursor up or down.
.TP
.BR h " or " "left arrow"
Go to parent directory.
.TP
.BR l ", " "right arrow" ", or " enter
Open selected file or enter directory.
.TP
.B g
Jump to top of list.
.TP
.B G
Jump to bottom of list.
.TP
.B ~
Go to home directory.
.TP
.B \`
Jump to previous directory (toggle).
.TP
.B :
Prompt for a path to jump to directly. Supports
.B ~
expansion. Shows an error if the path does not exist. Press esc to cancel.
.TP
.B f
Find files recursively under the current directory. Opens an interactive
picker. Press j/k or arrows to navigate results, enter or l to jump to the
selected result, esc/q/h to close.

.SS Search and Filter
.TP
.B /
Enter search mode. The listing is filtered as you type.
.TP
.B esc
Clear filter and exit search mode.
.TP
.B enter
Exit search mode while keeping the current filter active.

.SS Display Toggles
.TP
.B .
Toggle hidden files (dotfiles). Hidden entries appear before regular
entries (hidden dirs, then regular dirs, then hidden files, then
regular files).
.TP
.B T
Toggle size/date detail column.
.TP
.B P
Toggle preview pane on the right side.
.TP
.B s
Cycle sort mode: name \-> size \-> date.
.TP
.B i
Show file info (permissions, size, date) in the status bar.
.TP
.B R
Refresh the current directory listing.

.SS File Operations
.TP
.B r
Rename selected entry. Press esc to cancel.
.TP
.B m
Create a new directory. Press esc to cancel.
.TP
.B n
Create a new empty file. Press esc to cancel.
.TP
.B d
Delete selected entry or all multi-selected entries.
Non-empty directories require a second confirmation.
.TP
.B u
Move selected entry to trash (safe delete).
.TP
.B U
Open the trash directory.
.TP
.B o
Open selected file with a custom program. Press esc to cancel.
.TP
.B +
Make the selected file executable
.RB ( "chmod +x" ).
.TP
.B \-
Remove execute permission from the selected file
.RB ( "chmod -x" ).

.SS Clipboard
.TP
.B y
Yank (copy) selected entry or all multi-selected entries.
.TP
.B x
Cut selected entry or all multi-selected entries.
.TP
.B p
Paste clipboard contents into the current directory.
Auto-renames on conflict by appending
.IR _copy .
.TP
.B c
Copy the full path of the selected entry to the system clipboard.
Requires
.BR wl-copy ", " xclip ", " xsel ", or " pbcopy .

.SS Multi-Select
.TP
.B space
Toggle multi-select on the current entry (cursor advances).
.TP
.B a
Select all entries / deselect all.
.PP
Multi-select works with
.BR y ", " x ", and " d .

.SS Bookmarks
.TP
.B b
Bookmark the current directory. Press again to remove it.
.TP
.B B
Open the bookmark picker.
Use j/k to navigate, enter to jump, esc to close.

.SS Other
.TP
.B !
Drop into
.B $SHELL
in the current directory. Type
.I exit
to return to sfm. The working directory is updated if you cd elsewhere
in the shell.
.TP
.B ?
Show the keyboard shortcuts help overlay.
.TP
.B q
Quit sfm.

.SH PREVIEW PANE
When the preview pane is enabled with
.BR P ,
the terminal is split into a left pane (file list) and a right pane
(preview). The preview shows:
.IP \(bu 2
.B Text files \-
file contents displayed line by line.
.IP \(bu 2
.B Directories \-
directory contents (subdirectories first, then files).
.IP \(bu 2
.B Symlinks \-
the link target path.
.IP \(bu 2
.B Binary files \-
file size.

.SH CUSTOM OPENER
.B sfm
checks for a user-defined opener script at:
.PP
.I ~/.config/sfm/opener
.PP
If the file exists and is executable, sfm passes the selected file path
to it as the first argument instead of using the built-in smart opener.
.PP
Example opener script:
.PP
.nf
#!/bin/sh
case "$1" in
    *.jpg|*.jpeg) imv "$1" ;;
    *.mp4)        mpv "$1" ;;
    *.html|*.pdf) firefox "$1" ;;
    *)            echo "no program set for this file type" ;;
esac
.fi
.PP
Make it executable with:
.B chmod +x ~/.config/sfm/opener
.PP
If the opener script does not exist, sfm falls back to its built-in
smart opener which detects file types by extension and MIME type.

.SH SMART FILE OPENER
When no custom opener is configured, sfm opens files using the first
available program for each file type:
.TP
.B Text / code
$EDITOR or vi.
.TP
.B Images
imv, feh, sxiv, eog, gimp.
.TP
.B Video
mpv, vlc, mplayer, totem.
.TP
.B Audio
mpv, vlc, cmus, mocp.
.TP
.B PDF
zathura, evince, okular, mupdf.
.TP
.B Office documents
libreoffice.
.TP
.B Archives
atool or bsdtar (lists contents in pager).
.PP
Falls back to xdg-open, open (macOS), or $EDITOR.

.SH FILE COLOURS
.TP
.B Green bold
Directories.
.TP
.B Red bold
Executables and broken symlinks.
.TP
.B Magenta
Images.
.TP
.B Magenta bold
Video files and valid symlinks.
.TP
.B Cyan bold
Audio files.
.TP
.B Red
Archives (zip, tar, gz, etc.).
.TP
.B Yellow
Documents (pdf, docx, etc.).
.TP
.B Green
Code and scripts (py, sh, rs, etc.).
.TP
.B Cyan
Config and data files (json, yaml, etc.).
.TP
.B White
Text, markdown, and all other files.

.SH STATUS BAR INDICATORS
.TP
.B [hidden]
Hidden (dot) files are currently visible.
.TP
.B [sort:size] or [sort:date]
Active sort mode. Not shown when sorting by name (default).
.TP
.B [copy] or [cut]
A file is stored in the clipboard.
.TP
.B [sel:N]
N items are currently multi-selected.
.TP
.B [details]
Size/date detail column is visible.

.SH TRASH
Files deleted with
.B u
are moved to:
.PP
.I ~/.local/share/sfm-trash/
.PP
Files are prefixed with a timestamp in the format
.IR YYYYMMDD_HHMMSS_filename .
Use
.B U
to browse the trash directory. To restore a file, rename it with
.B r
to remove the timestamp prefix, then cut with
.B x
and paste with
.B p
to the desired location.

.SH FILES
.TP
.I ~/.config/sfm/bookmarks
Saved bookmarks, one directory path per line.
.TP
.I ~/.config/sfm/opener
Custom file opener script (optional, must be executable).
.TP
.I ~/.local/share/sfm-trash/
Directory where trashed files are stored.

.SH ENVIRONMENT
.TP
.B EDITOR
Editor used to open text files when no custom opener is set.
.TP
.B SHELL
Shell used when dropping to the terminal with
.BR ! .
.TP
.B PAGER
Pager used when listing archive contents.
.TP
.B XDG_CONFIG_HOME
Base directory for sfm config files. Defaults to
.IR ~/.config .
.TP
.B XDG_DATA_HOME
Base directory for sfm data files (trash). Defaults to
.IR ~/.local/share .

.SH EXAMPLES
Open sfm in the current directory:
.PP
.nf
sfm
.fi
.PP
Open sfm at a specific path:
.PP
.nf
sfm /mnt/data
.fi
.PP
Use sfm as a cd wrapper (add to shell rc):
.PP
.nf
s() { cd "$(sfm)"; }
.fi

.SH AUTHORS
Emmett1 <me@emmett1.my> with help of AI.

.SH SEE ALSO
.BR find (1),
.BR ls (1),
.BR mv (1),
.BR cp (1),
.BR rm (1),
.BR chmod (1),
.BR vi (1)