Terminal GuideTerminal Guide

joshuto

File Managers
macOSLinux
Rust

Ranger-like terminal file manager written in Rust.

Official Website

Features

Ranger-likePreviewAsync I/OTOML Config

Installation

Pacman (Arch)
pacman -S joshuto
Cargo (Rust)
cargo install joshuto

Why 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

Installation Commands
# 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 . --force

Interface 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

KeyAction
hMove to parent directory
jMove down (next file)
kMove up (previous file)
lEnter directory / open file
ggGo to top of list
GGo to bottom of list
/Search files
qQuit joshuto

File Operations

OperationKeysDescription
CopyyCopy selected file(s)
CutdCut (move) selected file(s)
PastepPaste copied/cut file(s)
Deletedelete or xDelete selected file(s)
RenameaRename selected file
SelectSpaceToggle selection
Create DirectorymkdirCreate 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
# ~/.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
# ~/.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
# ~/.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 editor

Mime Type Associations

~/.config/joshuto/mime_associations.toml
# ~/.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.

~/.config/joshuto/preview.sh
#!/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
    ;;
esac

Make 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).

Written by Dai AokiPublished: 2026-01-20

Related Articles

Explore More