joshuto
Ranger-like terminal file manager written in Rust.
Official WebsiteFeatures
Installation
pacman -S joshutocargo install joshutoWhy use joshuto?
Ranger-Inspired
Built on the familiar ranger philosophy with dual-pane layout and preview column. Vi keybindings feel natural to Vim users.
Written in Rust
Blazingly fast async I/O operations. Better performance than Python-based alternatives like ranger, especially with large directories.
Image Preview
Built-in image preview support with sixel, kitty, and iTerm2 protocols. Preview images directly in the terminal while browsing.
TOML Configuration
Simple TOML configuration files instead of complex vimrc syntax. Easy to understand and modify for anyone.
Installation
# Cargo (Rust)
cargo install joshuto
# Pacman (Arch Linux)
sudo pacman -S joshuto
# Building from source
git clone https://github.com/kamiyaa/joshuto.git
cd joshuto
cargo install --path .
# Update to latest version
cargo install --path . --forceInterface Layout
joshuto displays files in a three-column layout similar to ranger: parent directory (left), current directory (center), and file preview (right). The status bar shows current file information.
┌─────────── joshuto: ~/projects ───────────┬─ Preview ─────────┐ │ │ │ │ .. │ README.md │ │ .git/ │ # My Project │ │ .gitignore │ │ │ Cargo.toml │ A Rust project... │ │ >.cargo/ │ │ │ src/ │ │ │ target/ │ │ │ Makefile │ │ │ │ │ │ │ │ ├───────────────────────────────────────────┴────────────────────┤ │ .cargo/ : 123 items : 45.6 MB | 3/8 │ └─────────────────────────────────────────────────────────────────┘
Basic Navigation
| Key | Action |
|---|---|
h | Move to parent directory |
j | Move down (next file) |
k | Move up (previous file) |
l | Enter directory / open file |
gg | Go to top of list |
G | Go to bottom of list |
/ | Search files |
q | Quit joshuto |
File Operations
| Operation | Keys | Description |
|---|---|---|
| Copy | y | Copy selected file(s) |
| Cut | d | Cut (move) selected file(s) |
| Paste | p | Paste copied/cut file(s) |
| Delete | delete or x | Delete selected file(s) |
| Rename | a | Rename selected file |
| Select | Space | Toggle selection |
| Create Directory | mkdir | Create new directory |
Configuration
joshuto configuration uses TOML format in ~/.config/joshuto/. Configuration is simpler and more readable than traditional vimrc syntax.
Basic Configuration
# ~/.config/joshuto/joshuto.toml
# Basic joshuto configuration
# Display settings
enable_mouse = false
watch_patterns = ["*.rs", "*.toml", "Cargo.lock"]
xdg_open = true
use_trash = true
# General UI
scroll_offset = 5
use_relative_numbering = false
show_hidden = false
# Preview settings
show_borders = true
preview_shown = true
image_protocol = "sixel" # or "kitty", "iterm2"
# Status bar format
[statusbar]
left = ["%R/%S", "%H"]
center = ["%W"]
right = ["%T", "%E"]Key Mappings
# ~/.config/joshuto/keymap.toml
# Vi-like keybindings
# Navigation
[keymap.normal_mode.navigate]
j = "move_down"
k = "move_up"
h = "move_parent"
l = "move_right"
gg = "goto_top"
G = "goto_bottom"
ctrl_u = "page_up"
ctrl_d = "page_down"
# Selection
Space = "toggle_selection"
v = "toggle_selection"
# File operations
y = "copy_files"
d = "cut_files"
p = "paste_files"
P = "paste_files"
delete = "delete_files"
x = "delete_files"
# Search
/ = "search"
? = "search_rev"
n = "search_next"
N = "search_prev"
# Misc
q = "quit"
Q = "force_quit"
zh = "toggle_hidden"
zp = "toggle_preview"Advanced Configuration
# ~/.config/joshuto/joshuto.toml
# Advanced configuration
# Preview configuration
[preview]
# Image display method
image_protocol = "sixel" # "sixel", "kitty", "iterm2"
# Enable preview for specific file types
previewer = "~/.config/joshuto/preview.sh"
max_preview_size = 2097152 # 2MB in bytes
# Syntax highlighting in preview
syntax_highlight = true
highlight_theme = "Monokai Extended"
# File associations - define how files are opened
[[extension_association]]
ext = ["jpg", "jpeg", "png", "gif", "bmp"]
program = "feh"
[[extension_association]]
ext = ["pdf"]
program = "zathura"
[[extension_association]]
ext = ["mp4", "mkv", "avi"]
program = "mpv"
[[extension_association]]
ext = ["txt", "md", "rs", "py", "js"]
program = "nvim"
[[extension_association]]
ext = ["zip", "tar", "gz", "rar", "7z"]
program = "bsdtar"
# Custom commands
[keymap.normal_mode.commands]
"zz" = "maximize" # Maximize pane
"zi" = "open_with_editor" # Open selection in editorMime Type Associations
# ~/.config/joshuto/mime_associations.toml
# Define how different file types are opened
# Text files - edit with vim
[[mime]]
extensions = ["txt", "md", "rst", "json", "yaml", "toml"]
app = "vim"
# Code files
[[mime]]
extensions = ["py", "rs", "js", "ts", "go", "c", "cpp"]
app = "nvim"
# Images
[[mime]]
extensions = ["jpg", "jpeg", "png", "gif", "bmp", "svg"]
app = "feh"
fork = true
# PDF
[[mime]]
extensions = ["pdf"]
app = "zathura"
fork = true
# Video
[[mime]]
extensions = ["mp4", "mkv", "avi", "mov", "flv"]
app = "mpv"
fork = true
# Archives
[[mime]]
extensions = ["zip", "tar", "gz", "rar", "7z", "bz2"]
app = "bsdtar"
# Default handler
[[mime]]
extensions = ["*"]
app = "less"Custom Preview Script
Create a custom preview script to handle different file types with syntax highlighting and special preview formatting.
#!/bin/bash
# ~/.config/joshuto/preview.sh
# Custom preview script for joshuto
file_path="$1"
max_lines="$2"
case "$file_path" in
*.py)
bat --language python "$file_path" | head -n "$max_lines"
;;
*.rs)
bat --language rust "$file_path" | head -n "$max_lines"
;;
*.json)
jq . "$file_path" | head -n "$max_lines"
;;
*.md)
glow "$file_path" | head -n "$max_lines"
;;
*.pdf)
pdftotext "$file_path" - | head -n "$max_lines"
;;
*)
head -n "$max_lines" "$file_path" 2>/dev/null
;;
esacMake the script executable: chmod +x ~/.config/joshuto/preview.sh
Tips and Tricks
Image Preview Support
joshuto supports image preview with sixel, kitty, and iTerm2 protocols. Enable it in config with image_protocol = "sixel". Requires terminal support.
File Type Associations
Define custom programs for different file types in mime_associations.toml. Use fork = true to prevent blocking the file manager when opening files.
Syntax Highlighting Preview
Use tools like bat, glow, and jq in your preview script for beautiful syntax-highlighted previews of different file types.
Trash Support
Enable use_trash = true to use the system trash instead of permanently deleting files. Requires trash-cli on Linux.
Relative Numbering
Enable use_relative_numbering = true to show relative line numbers. Great for jumping with 5j (move down 5 lines).