fileview 0.7.0

A minimal file tree UI for terminal emulators
Documentation

FileView (fv)

Crates.io License: MIT

A minimal, VSCode-style file tree TUI for modern terminal emulators.

English | 日本語

Features

  • Fast file tree navigation with vim-like keybindings
  • Git integration - color-coded file status and branch display
  • Multi-select support for batch operations
  • Preview panel with support for:
    • Text files (syntax highlighting by extension)
    • Images (half-block rendering)
    • Directories (file count, size statistics)
    • Binary files (hex dump view)
  • Copy/cut/paste with internal clipboard
  • System clipboard integration (path/filename copy)
  • Pick mode for external tool integration
  • Callback execution on file selection
  • Hidden files toggle
  • Mouse support (click, double-click, scroll, drag-and-drop)
  • Nerd Fonts icons (optional, enable with --icons)

Git Status Colors

When inside a git repository, files are color-coded by their status:

Color Status
Yellow Modified
Green Added / Untracked
Red Deleted
Cyan Renamed
Gray Ignored
Magenta Conflict

The current branch name is displayed in the status bar.

Installation

From crates.io (Recommended)

cargo install fileview

From source

git clone https://github.com/Hiro-Chiba/fileview.git
cd fileview
cargo install --path .

Requirements

  • Rust 1.70+
  • A terminal with true color support (recommended: Ghostty, iTerm2, Alacritty)

Usage

# Open current directory
fv

# Open specific directory
fv /path/to/directory

# Pick mode (output selected path to stdout)
fv --pick

# Pick mode with JSON output
fv --pick --format json

# Execute command on selection
fv --on-select "code {path}"

Keybindings

Navigation

Key Action
j / ↓ Move down
k / ↑ Move up
g Go to top
G Go to bottom

Tree Operations

Key Action
l / → / Tab Expand directory
h / ← / Backspace Collapse directory
Enter Toggle expand/collapse
H Collapse all
L Expand all (depth limit: 5)

Selection

Key Action
Space Toggle mark
Esc Clear all marks

File Operations

Key Action
a Create new file
A Create new directory
r Rename
D / Delete Delete (with confirmation)
y Copy to clipboard
d Cut to clipboard
p Paste

Search

Key Action
/ Start search
n Next search result

Preview

Key Action
P Toggle side preview panel
o Open fullscreen preview
Tab Toggle focus between tree and preview (when preview visible)

Side Preview Focus Mode

When the side preview panel is open, press Tab to switch focus:

Focus j/k/↑/↓ g/G b/f
Tree Navigate files Top/Bottom of list -
Preview Scroll content Top/Bottom of preview Page scroll
  • Click on a panel to switch focus
  • Scroll wheel works on the focused panel
  • Esc returns focus to tree
  • Focused panel has cyan border highlight

Other

Key Action
. Toggle hidden files
R / F5 Refresh
c Copy path to system clipboard
C Copy filename to system clipboard
? Show help
q Quit

CLI Options

Option Description
-p, --pick Pick mode: output selected path(s) to stdout
-f, --format FMT Output format: lines (default), null, json
--on-select CMD Run command when file is selected
-i, --icons Enable Nerd Fonts icons (default)
--no-icons Disable icons
-h, --help Show help
-V, --version Show version

Environment Variables

Variable Description
FILEVIEW_ICONS=0 Disable icons by default

Placeholders for --on-select

Placeholder Description
{path} Full path
{dir} Parent directory
{name} Filename with extension
{stem} Filename without extension
{ext} Extension only

Examples

# Use as file picker for another tool
selected=$(fv --pick)
echo "Selected: $selected"

# Open selected file in editor
fv --on-select "vim {path}"

# Copy selected file path to clipboard (macOS)
fv --on-select "echo {path} | pbcopy"

# Multiple file selection with JSON output
fv --pick --format json

License

MIT