fen

README

fen

fen is a terminal file manager inspired by ranger
Works for Linux, macOS, FreeBSD and Windows

Installing

Prebuilt binaries

Download and run the latest version in the Releases page

Add it to your path environment variable, or (on Linux/FreeBSD) place the executable in /usr/local/bin

Building from source

This requires Go 1.21.5 or above (install Go)

git clone https://github.com/kivattt/fen
cd fen
go build
./fen # fen.exe on Windows

Controls

Arrow keys, hjkl, mouse click or scrollwheel to navigate (Enter goes right), Escape key to cancel an action

? or F1 Toggle help menu
F2 Show libraries used in fen
q Quit fen
o Options
z or Backspace Toggle hidden files
Ctrl + Space or Ctrl + n Open file(s) with specific program
! Run system shell command (cmd on Windows)
Home or g Go to the top
End or G Go to the bottom
Ctrl + Left arrow Go to the root folder (or current Git repository if fen.git_status=true)
Ctrl + Right arrow Go to the path furthest down in history, follow a symlink or go to the first changed file if fen.git_status=true
M Go to the middle
Page Up / Page Down Scroll up/down an entire page
H Go to the top of the screen
L Go to the bottom of the screen
Del or x Delete file(s)
y Copy file(s)
d Cut file(s)
p Paste file(s)
/ or Ctrl + f Search
c Goto path
Space Select files
A Flip selection in folder (select all files)
D Deselect all, press again to un-yank
a Rename a file
b Bulk-rename (rename in editor)
V Start selecting by moving
n Create a new file
N Create a new folder
F5 Refreshes files, syncs the screen (fixes broken output), refreshes git status when fen.git_status=true
0-9 Go to a configured bookmark

Configuration

You can find a complete default config with extra examples in the config.lua file
For a full config folder example, see my personal config

Linux/FreeBSD: ~/.config/fen/config.lua or $XDG_CONFIG_HOME/fen/config.lua if $XDG_CONFIG_HOME set
macOS: $HOME/Library/Application Support/fen/config.lua
Windows: %AppData%\Roaming\fen\config.lua

You can specify a different config file with the --config flag

Left-clicking to copy the selected path on Linux/FreeBSD requires xclip to be installed

File previews

fen does not (yet!) have file previews by default
For file previews with programs like cat or head, you can add something like this to your config.lua:

fen.preview = {
    {
        program = {"head -n 100"},
        match = {"*"}
    }
}

For something cross-platform, file previews can also be a lua script.

fen.preview = {
    {
        script = fen.config_path.."basic.lua",
        match = {"*"}
    }
}

If "script" is set, "program" will be ignored in the same preview entry.
"script" can not be a list like "program" can, because we want to see syntax errors when writing lua code instead of falling back to anything.
The "script" key has to be an absolute file path

Changing directory

You can change the current working directory to the one in fen on exit:

cd $(fen --print-folder-on-exit)

You can alias fen to do this every time you open it by adding this to your .bashrc:

cd_fen() {
    cd $(fen --print-folder-on-exit)
}
alias fen=cd_fen

NOTE: Using this alias will break command-line arguments, like fen -v since the output will be passed to cd.

Lua scripting (click to expand)

fen uses gopher-lua as its Lua runtime.

Writing file preview scripts with Lua

Do not use print(), it outputs to stdout which doesn't work well within file previews.
You can find examples in lua-file-preview-examples

File preview scripts are separate from config.lua, don't expect any direct overlap in the API

Available variables:

fen.SelectedFile Currently selected file absolute file path to preview
fen.Width Width of the file preview area
fen.Height Height of the file preview area

Available functions:

fen:Print(text, x, y, maxWidth, alignment, color) returns amount of characters on screen printed Print text at the given x/y position. x=0, y=0 is the top left corner of the file preview area and limited to the file preview area only Go doc
fen:PrintSimple(text, x, y) returns amount of characters on screen printed Same as above, with default color and alignment and no maxWidth Go doc
fen:Escape(text) Escape style tags Go doc
fen:TranslateANSI(text) Turn ANSI into style tags Go doc
fen:NewRGBColor(r, g, b) Go doc
fen:ColorToString(color) (Since v1.1.2) Go doc
fen:RuntimeOS() (Since v1.1.3) The OS fen is running in Go doc
fen:Version() (Since v1.2.3) fen version string

Notes about fen:Print() and fen:PrintSimple():
Newlines will not show up, and do nothing. You will have to manually call it multiple times, increasing y.
Tabs are replaced with 4 spaces so they are visible

Writing file open scripts with Lua (Since v1.3.0)

You can find examples in lua-file-open-examples

Available variables:

fen.SelectedFiles List of selected files to open
fen.ConfigPath Same as fen.config_path from config.lua
fen.RuntimeOS The OS fen is running in Go doc
fen.Version fen version string

Known issues

• fen may crash in the middle of deleting files due to a data race, most commonly when deleting a lot of files (like 4000)
• File previews are ran synchronously, which means they slow down fen
• fen intentionally does not handle Unicode "grapheme clusters" (like chinese text) in filenames correctly for performance reasons. You need to manually build fen with the replace directive for my tcell fork in the go.mod file removed to show them correctly
• Symlinks have no special distinction, a folder symlink will appear like a normal folder
• On FreeBSD, when the disk is full, fen may erroneously show a very large amount of disk space available (like 18.446 EB free), when in reality there is no available space
• go test doesn't work on Windows
• The color for audio files is invisible in the default Windows Powershell colors, but not cmd or Windows Terminal
• Bulk-renaming a .git folder on Windows hangs fen forever

See TODO.md for other issues and possible future features, roughly sorted by priority