https://github.com/kivattt/fen
Terminal file manager
https://github.com/kivattt/fen
file-manager file-manager-cli terminal
Last synced: 4 months ago
JSON representation
Terminal file manager
- Host: GitHub
- URL: https://github.com/kivattt/fen
- Owner: kivattt
- License: mit
- Created: 2024-03-12T08:14:26.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2026-01-06T22:49:35.000Z (5 months ago)
- Last Synced: 2026-01-11T11:32:33.815Z (5 months ago)
- Topics: file-manager, file-manager-cli, terminal
- Language: Go
- Homepage:
- Size: 8.19 MB
- Stars: 31
- Watchers: 2
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: history.go
- License: LICENSE
Awesome Lists containing this project
README
# fen
[](https://goreportcard.com/report/github.com/kivattt/fen)
fen is a terminal file manager inspired by [ranger](https://github.com/ranger/ranger)\
Works for Linux, macOS, FreeBSD and Windows
Warning! There are race conditions which make fen unsuitable for copying large amounts of individual files. Use something like [ranger](https://github.com/ranger/ranger) for this purpose instead!
## Installing
### Prebuilt binaries
Download and run the latest version in the [Releases](https://github.com/kivattt/fen/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](https://go.dev/dl/))
```
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 + b 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\
M Go to the middle\
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`\
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\
f or Ctrl + n Search filenames recursively\
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](config.lua) file\
For a full config folder example, see [my personal config](https://github.com/kivattt/dotfiles/blob/main/.config/fen/config.lua)
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:
```lua
fen.preview = {
{
program = {"head -n 100"},
match = {"*"}
}
}
```
For something cross-platform, file previews can also be a [lua script](lua-file-preview-examples/basic.lua).
```lua
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:
```bash
cd $(fen --print-folder-on-exit)
```
You can alias fen to do this every time you open it by adding this to your `.bashrc`:
```bash
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](https://github.com/yuin/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](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](https://pkg.go.dev/github.com/rivo/tview#Print)\
`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](https://pkg.go.dev/github.com/rivo/tview#PrintSimple)\
`fen:Escape(text)` Escape style tags [Go doc](https://pkg.go.dev/github.com/rivo/tview#Escape)\
`fen:TranslateANSI(text)` Turn ANSI into style tags [Go doc](https://pkg.go.dev/github.com/rivo/tview#TranslateANSI)\
`fen:NewRGBColor(r, g, b)` [Go doc](https://pkg.go.dev/github.com/gdamore/tcell/v2#NewRGBColor)\
`fen:ColorToString(color)` (Since v1.1.2) [Go doc](https://pkg.go.dev/github.com/gdamore/tcell/v2#Color.String)\
`fen:RuntimeOS()` (Since v1.1.3) The OS fen is running in [Go doc](https://pkg.go.dev/runtime#pkg-constants)\
`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](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](https://pkg.go.dev/runtime#pkg-constants)\
`fen.Version` fen version string
## Known issues
- fen may crash in the middle of deleting files due to a race condition, 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](https://github.com/kivattt/tcell-naively-faster) in the go.mod file removed to show them correctly
- 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
- On Windows, `fen.git_status` may show a file as changed when it was only re-saved in notepad, until you run a Git command in the repo
See [TODO.md](TODO.md) for other issues and possible future features