✓ Stable v1.0.2

🏰 fortress

Terminal file explorer written in modern Fortran with git integration

A terminal file explorer written in modern Fortran (2008+) featuring dual-pane navigation, integrated git operations, fuzzy search, move mode, multi-select clipboard, and an intuitive keyboard-driven interface. Native binary compilation for fast startup and minimal resource usage.

View on GitHub Download RPM

🎯 RPM Available 🏛️ AUR Available

Installation

fortress is available for Fedora/RHEL, Arch Linux (AUR), macOS (Homebrew), and can be built from source using the Fortran Package Manager (fpm).

Fedora / RHEL 9

# Add the musicsian repository (first time only) sudo dnf config-manager --add-repo https://repos.musicsian.com/musicsian.repo # Install fortress sudo dnf install fortress

Arch Linux (AUR)

# Install via AUR helper yay -S fortress

macOS (Homebrew)

# Tap the repository and install brew tap FortranGoingOnForty/fortress brew install fortress

From Source (fpm)

# Prerequisites: gfortran 10+, fpm, fzf, git # Install fpm if needed cargo install fpm # or download from GitHub releases # Clone and build git clone https://github.com/FortranGoingOnForty/fortress.git cd fortress fpm build --flag "-O2 -ffree-line-length-none" # Run directly ./build/gfortran_*/app/fortress

Shell Integration

For the cd-on-exit feature to work (press c to change directory and exit), you must source the shell integration script. This wraps the binary and reads the target directory after fortress exits.

Bash / Zsh

Add to your ~/.bashrc or ~/.zshrc:

# Add to ~/.bashrc or ~/.zshrc source /usr/share/fortress/fortress.sh # Alternative location (system-wide) source /etc/profile.d/fortress.sh

Fish

Add to your ~/.config/fish/config.fish:

# Add to ~/.config/fish/config.fish source /usr/share/fortress/fortress.fish # Note: May auto-load from vendor_functions.d

Quick Start

Launch fortress in the current directory and start exploring:

# Start fortress in current directory fortress # Basic navigation ↑/↓ - Move through file list → - Enter directory ← - Go to parent q - Quit

Dependencies

Build: gfortran ≥ 10.0, fpm (Fortran Package Manager), gcc
Runtime: fzf (fuzzy finder), git
Link: ncurses (linked at build time)

Configuration

fortress uses environment variables and a favorites file for configuration. There is no separate config file - the tool follows Unix conventions with sensible defaults and environment-based customization.

Environment Variables

Option	Type	Default	Description
`HOME`	string	(required)	User home directory for temp files
`EDITOR`	string	-	Text editor for file opening (priority 1)
`VISUAL`	string	-	Visual editor (priority 2)
`TERM_PROGRAM`	string	auto	Terminal type detection
`FORTRESS_BIN`	path	auto	Override binary location
`FORTRESS_DIR`	path	-	Development mode repo root

Files and Directories

Option	Type	Default	Description
`~/.fortress_favorites`	file	-	User favorites list (10 max)
`~/.fortress_cd`	file	-	Directory for cd-on-exit feature
`~/.fortress_ls`	temp	-	File listing cache
`~/.fortress_fzf`	temp	-	fzf search results
`~/.fortress_pwd`	temp	-	Current working directory cache
`~/.fortress_repo`	temp	-	Git repository name cache
`~/.fortress_repo_root`	temp	-	Git repo root cache
`~/.fortress_size`	temp	-	Terminal size cache

Temporary files (~/.fortress_*) are cleaned up automatically after use. Only ~/.fortress_favorites and ~/.fortress_cd persist.

Editor Configuration

When you press o (or Alt+v) to open a file, fortress checks environment variables in order:

$EDITOR - Primary text editor
$VISUAL - Fallback visual editor
Platform default: open (macOS) or xdg-open (Linux)

# Add to ~/.bashrc or ~/.zshrc export EDITOR=nvim export VISUAL=vim # Alternative editors export EDITOR=nano export EDITOR=helix export EDITOR=code # VSCode (GUI)

Terminal Detection

fortress auto-detects your terminal emulator via $TERM_PROGRAM to apply appropriate display padding:

WezTerm, Ghostty: 1 line padding
Terminal.app, iTerm2: 2 lines padding
Other terminals: 1 line padding (default)

Favorites File Format

The favorites file at ~/.fortress_favorites stores up to 10 bookmarked directories, one path per line:

# ~/.fortress_favorites # Plain text, one directory path per line /home/user/projects /home/user/documents /etc/nginx /var/log

Development Configuration

For development, you can override the binary location:

# Point to development build export FORTRESS_BIN=/home/user/fortress/build/gfortran_*/app/fortress # Or point to repo root (auto-detects binary) export FORTRESS_DIR=/home/user/fortress

Build Options

When building from source, you can customize optimization:

# Debug build with warnings fpm build --flag "-g -Wall -Wextra" # Standard build (no optimization) fpm build

Overview

fortress is a terminal file explorer that combines the dual-pane layout of classic file managers with modern features like fuzzy search, git integration, and keyboard-first navigation. Written in modern Fortran (2008+), it compiles to a native binary with fast startup and minimal resource usage.

Key Features

Dual-Pane Display: Parent directory (30%) and current directory (70%)
Git Integration: Stage, unstage, commit, diff, push/pull directly
Fuzzy Jump Search: Type characters to incrementally search files
fzf Integration: Recursive file search with preview
Move Mode: Two-cursor interface for intuitive file moving
Multi-Select: Select multiple files for batch operations
Favorites System: Bookmark up to 10 directories
CD-on-Exit: Change shell directory when exiting

System Overview

fortress is implemented in approximately 3,831 lines of modern Fortran (2008+) across 7 main modules plus a main program file. The architecture follows a modular design with clear separation between UI, filesystem operations, terminal control, and git integration.

Codebase Statistics

Total: 3,831 lines of Fortran
Main Event Loop: 1,873 LOC (app/main.f90)
Git Operations: 709 LOC (src/git/git_ops.f90)
Filesystem Operations: 381 LOC (src/filesystem/fs_ops.f90)
UI Display: 356 LOC (src/ui/display.f90)
Terminal Control: 276 LOC (src/terminal/term_control.f90)
File Preview: 100 LOC (src/ui/preview.f90)
Version Module: 69 LOC (auto-generated)

Module Structure

The project is organized into functional modules:

fortress/
├── app/
│   └── main.f90              # Main event loop, state management
├── src/
│   ├── filesystem/
│   │   └── fs_ops.f90        # File system operations
│   ├── terminal/
│   │   └── term_control.f90  # Terminal control, ANSI codes
│   ├── ui/
│   │   ├── display.f90       # Dual-pane rendering
│   │   └── preview.f90       # File preview (future)
│   ├── git/
│   │   └── git_ops.f90       # Git integration
│   └── version/
│       └── version.f90       # Auto-generated version info
└── test/
    ├── test_display_sim.f90  # Display tests
    └── test_fortran_ansi.f90 # ANSI code tests

Event Loop

The main program (app/main.f90) implements an infinite event loop:

Read current directory contents
Update display with dual-pane rendering
Wait for keyboard input (blocking read)
Process input and update state
Loop until quit signal

State variables persist across iterations, maintaining navigation history, clipboard contents, selection state, and git mode status.

State Management

Key state variables in the main program:

! Navigation state
character(len=MAX_PATH) :: current_dir, parent_dir
integer :: selected = 1, scroll_offset = 0

! Mode management
character(len=10) :: mode = 'normal'  ! 'normal' or 'git'
logical :: move_mode = .false.
logical :: in_rename_mode = .false.

! Clipboard
logical :: has_clipboard = .false.
logical :: clipboard_is_cut = .false.
character(len=MAX_PATH) :: clipboard_source_path
integer :: clipboard_count

! Multi-select
logical, dimension(MAX_FILES) :: is_selected
integer :: selection_count = 0

! Git integration
logical :: in_git_repo = .false.
character(len=256) :: repo_name, branch_name

Terminal Control

Raw Mode Input

fortress uses termios to configure the terminal for character-by-character input without echo:

! Enable raw mode
stty -icanon -echo min 1 time 0

! Restore canonical mode on exit
stty icanon echo

This allows immediate response to keypresses without waiting for Enter, essential for interactive navigation.

ANSI Escape Codes

The terminal control module defines ANSI escape sequences for display:

ESC = char(27)  ! Escape character

! Screen control
ALT_SCREEN_ON  = ESC // "[?1049h"
ALT_SCREEN_OFF = ESC // "[?1049l"
CURSOR_HIDE    = ESC // "[?25l"
CURSOR_SHOW    = ESC // "[?25h"

! Colors
BLUE   = ESC // "[34m"
GREEN  = ESC // "[32m"
RED    = ESC // "[31m"
YELLOW = ESC // "[33m"
GREY   = ESC // "[90m"
WHITE  = ESC // "[37m"

! Styles
BOLD      = ESC // "[1m"
DIM       = ESC // "[2m"
UNDERLINE = ESC // "[4m"
REVERSE   = ESC // "[7m"
RESET     = ESC // "[0m"

Dual-Pane Display

The display layout divides the terminal into regions:

┌─────────────────────────────────────────────┐
│ Header (2 lines)                            │
│ FORTRESS - /current/dir/path                │
│ <status line: mode, clipboard, etc.>        │
├──────────────┬──────────────────────────────┤
│ Parent (30%) │ Current (70%)                │
│ [dimmed]     │ [active, colored]            │
│ filename     │ filename ↑ (staged)          │
│ → dir/       │ → dir/                       │
│ ..           │ file.txt ✗ (modified)        │
├──────────────┴──────────────────────────────┤
│ Footer: Controls and help text              │
└─────────────────────────────────────────────┘

Color Scheme

Directories: Blue + bold, followed by /
Executables: Green
Dotfiles: Grey (dimmed)
Regular files: White
Cut files: Dark red (dimmed)
Staged (git): Green + ↑
Unstaged (git): Red + ✗
Untracked (git): Grey + ✗

Filesystem Operations

The filesystem module (src/filesystem/fs_ops.f90) defines constants and operations:

! Constants
integer, parameter :: MAX_PATH = 512   ! Maximum path length
integer, parameter :: MAX_FILES = 500  ! Maximum files per directory

Key Functions

get_file_list() - Read directory, detect file types via shell
get_pwd() - Get current working directory
get_parent_path() - Extract parent directory path
join_path() - Safely concatenate path components
fzf_search() - Launch fzf for recursive search
write_exit_dir() - Write target directory for cd-on-exit
open_file_in_default_app() - Open with editor/platform opener

File Type Detection

File types are detected via a shell command that checks each file:

Directories: -d flag, displayed with / suffix
Executables: -x flag and not directory
Regular files: Everything else

Navigation

Option	Type	Default	Description
`Arrow Up / Down`	binding	-	Move cursor through file list
`Arrow Right`	binding	-	Enter directory or follow symlink
`Arrow Left`	binding	-	Go back to parent directory
`~`	binding	-	Jump to home directory
`/`	binding	-	Jump to root directory
`Shift+Up / Shift+Down`	binding	-	Extend selection range

File Operations

Option	Type	Default	Description
`y / Alt+y`	binding	-	Copy to clipboard (yank)
`x / Alt+x`	binding	-	Cut to clipboard
`p / Alt+p`	binding	-	Paste from clipboard
`v / Alt+m`	binding	-	Enter move mode / confirm move
`n / Alt+n`	binding	-	Rename file or directory
`r / Alt+r`	binding	-	Delete with confirmation
`o / Alt+v`	binding	-	Open with $EDITOR or $VISUAL

Search & View

Option	Type	Default	Description
`s / Alt+s`	binding	-	fzf recursive search
`c / Alt+c`	binding	-	CD to directory and exit
`.`	binding	-	Toggle dotfile visibility
`a-z, 0-9`	binding	-	Fuzzy jump search (incremental)

Selection

Option	Type	Default	Description
`Space`	binding	-	Toggle selection on current item
`Shift+Up / Shift+Down`	binding	-	Extend selection range
`e / E`	binding	-	Exit selection mode (clear all)

Git Mode (Alt+g to toggle)

Option	Type	Default	Description
`Alt+g`	binding	-	Toggle git mode
`a`	binding	-	Stage file/directory (batch recursive)
`u`	binding	-	Unstage file/directory
`m`	binding	-	Commit with message prompt
`d`	binding	-	Show git diff (files only)
`f`	binding	-	Fetch from remote
`l`	binding	-	Pull from remote
`h`	binding	-	Push to remote
`t`	binding	-	Create git tag

Favorites

Option	Type	Default	Description
`*`	binding	-	Add/remove current directory as favorite
`8`	binding	-	Open favorites picker (fzf)

Control

Option	Type	Default	Description
`q`	binding	-	Quit (or exit move mode)
`Ctrl+q`	binding	-	Force quit
`ESC`	binding	-	Cancel current operation

Complete Reference

NAVIGATION ↑/↓ Move cursor up/down → Enter directory ← Back to parent ~ Jump to home / Jump to root Shift+↑/↓ Range select FILE OPERATIONS y/Alt+y Copy (yank) x/Alt+x Cut p/Alt+p Paste n/Alt+n Rename r/Alt+r Delete o/Alt+v Open with editor v/Alt+m Move mode SELECTION Space Toggle selection e/E Clear selections GIT MODE (Alt+g to toggle) a Stage u Unstage m Commit d Diff f Fetch l Pull h Push t Tag SEARCH & VIEW s/Alt+s fzf search c/Alt+c CD on exit . Toggle dotfiles * Add favorite 8 Open favorites Alphanumeric Fuzzy jump search CONTROL q Quit (or exit move) Ctrl+q Force quit ESC Cancel operation

Common Issues

CD-on-exit not working

Cause: Shell integration script not sourced.

Solution:

# Add to ~/.bashrc or ~/.zshrc source /usr/share/fortress/fortress.sh # For fish, add to ~/.config/fish/config.fish source /usr/share/fortress/fortress.fish # Verify: After pressing 'c', check if file exists cat ~/.fortress_cd

Terminal display corrupted or shifted

Cause: Terminal emulator not properly detected for padding adjustment.

Solution: Check your TERM_PROGRAM environment variable. Try using a tested terminal emulator (WezTerm, iTerm2, Alacritty, GNOME Terminal).

fzf integration not working

Cause: fzf not installed.

Solution:

# Arch Linux sudo pacman -S fzf # Fedora sudo dnf install fzf # macOS brew install fzf # From source git clone https://github.com/junegunn/fzf.git ~/.fzf ~/.fzf/install

Git features not available

Cause: Git not installed or not in a git repository.

Solution: Install git and ensure you're inside a git repository. The Alt+g toggle only appears when fortress detects a .git directory.

File open (o/Alt+v) doesn't work

Cause: No $EDITOR or $VISUAL set, and no system opener available.

Solution:

# Add to ~/.bashrc or ~/.zshrc export EDITOR=nvim # or vim, nano, helix, etc. export VISUAL=vim # Verify echo $EDITOR

Rename mode typing not working

Cause: Terminal may have been left in canonical mode after a suspend (Ctrl+Z).

Solution:

# Manually restore raw mode stty -icanon -echo min 1 time 0 # Prevention: Don't suspend fortress with Ctrl+Z during rename

Performance

Terminal Size Caching

Terminal dimensions are cached for 100 screen redraws to prevent expensive tput calls on every frame. If the display looks wrong after resizing your terminal, navigate to a different directory to force a refresh.

Git Status Caching

Git status is cached with a 500ms TTL per directory. The cache is invalidated:

When navigating to a different directory
After any git operation (add, unstage, commit, etc.)

File List Limits

MAX_FILES = 500 limits the number of files displayed per directory. Very large directories may be truncated.

Building from Source

Debug Build

# Build with debug symbols and warnings fpm build --flag "-g -Wall -Wextra" # Run tests fpm test

Compiler Requirements

fortress requires gfortran 10.0 or newer. On macOS with Apple Silicon, you may need to install a newer gfortran via Homebrew.

Terminal Compatibility

Tested Terminals

Linux: Alacritty, GNOME Terminal, Konsole, xterm
macOS: Terminal.app, iTerm2, WezTerm

Known Issues

macOS Reverse Video: Fixed in v0.9.94+ (uses white background instead)
Alacritty Unicode: Extra spacing for wide characters (★ symbol)

Comparison with Similar Tools

fortress vs. ranger

ranger: ~4500 lines of Python with external dependencies
fortress: ~3800 lines of Fortran, compiled to native binary
fortress: Faster startup, no Python runtime required

fortress vs. lf

lf: ~2000 lines of Go
fortress: Faster startup than Go runtime
fortress: Git integration out-of-box

fortress vs. midnight commander (mc)

mc: ~50,000 lines of C
fortress: Minimal, focused feature set
fortress: Modern git-first design

Unique to fortress

Git-First Design: Git staging/committing integrated, not bolted-on
Favorites System: Quick bookmark navigation
Fuzzy Jump: Character-by-character incremental search
Move Mode: Two-cursor interface for intuitive file moving
Multi-Select Clipboard: Copy/cut multiple items at once
Smart Paste Suffix: Auto-rename on conflicts

🏰 fortress

Installation

Fedora / RHEL 9

Arch Linux (AUR)

macOS (Homebrew)

From Source (fpm)

Shell Integration

Bash / Zsh

Fish

Quick Start

Dependencies

Configuration

Environment Variables

Files and Directories

Editor Configuration

Terminal Detection

Favorites File Format

Development Configuration

Build Options

Overview

Key Features

Navigation

Basic Movement

Basic Movement

Directory Traversal

Fuzzy Jump Search

Scoring Algorithm

File Operations

Copy/Cut/Paste

Copy (Yank)

Cut

Paste

Smart Suffix

Move Mode

Rename Mode

Delete

Multi-Select

Selection Basics

Range Selection

Batch Operations

Git Integration

Git Mode

Status Indicators

Staging Changes

Committing

Remote Operations

Favorites System

System Overview

Codebase Statistics

Module Structure

Event Loop

State Management

Terminal Control

Raw Mode Input

ANSI Escape Codes

Dual-Pane Display

Color Scheme

Git Operations

Filesystem Operations

Key Functions

File Type Detection

Navigation

File Operations

Search & View

Selection

Git Mode (Alt+g to toggle)

Favorites

Control

Complete Reference

Common Issues

CD-on-exit not working

Terminal display corrupted or shifted

fzf integration not working

Git features not available

File open (o/Alt+v) doesn't work

Rename mode typing not working

Performance

Terminal Size Caching

Git Status Caching

File List Limits