gravityfile

"Where mass accumulates, attention should follow."

File system explorer and analyzer with an interactive TUI, built in Rust.

Features

• Interactive TUI - Beautiful terminal interface with vim-style navigation
• Miller Columns Layout - Ranger-style three-pane view (toggle with v)
• File Operations - Copy, move, rename, create, delete with undo support
• Parallel Scanning - Fast directory traversal using jwalk
• Duplicate Detection - Find duplicate files using BLAKE3 hashing with partial-hash optimization
• Age Analysis - Identify stale directories and analyze file age distribution
• Drill-Down Navigation - Explore directories without rescanning
• Conflict Resolution - Interactive handling for file conflicts during copy/move
• Command Palette - Vim-style : commands for power users
• Multiple Themes - Dark and light theme support
• Library-First Design - Use as a library or standalone tool
• Export Support - Export scan results to JSON

Installation

From crates.io

cargo install gravityfile

From source

git clone https://github.com/epistates/gravityfile
cd gravityfile
cargo install --path .

This installs two binaries: gravityfile and grav (short alias).

Usage

Interactive TUI (Default)

gravityfile [PATH]
# or use the short alias:
grav [PATH]

Launch the interactive terminal interface to explore disk usage.

Quick Scan

gravityfile scan [PATH] [-d DEPTH] [-n TOP]

Quick summary of disk usage with tree output.

Find Duplicates

gravityfile duplicates [PATH] [--min-size SIZE] [-n TOP]

Find duplicate files. Uses a three-phase algorithm:

1. Group files by size
2. Compute partial hash (first + last 4KB)
3. Full BLAKE3 hash for candidates

Age Analysis

gravityfile age [PATH] [--stale DURATION]

Analyze file ages and find stale directories.

Export

gravityfile export [PATH] [-o OUTPUT]

Export scan results to JSON.

TUI Keybindings

Navigation

Key	Action
j / ↓	Move down
k / ↑	Move up
h / ←	Collapse directory
l / →	Expand directory
g / Home	Jump to top
G / End	Jump to bottom
Ctrl-u / PgUp	Page up
Ctrl-d / PgDn	Page down
Enter	Drill into directory
Backspace / -	Navigate back
o	Toggle expand node
Ctrl-g	Go to path

Selection & Clipboard

Key	Action
Space	Mark item for multi-select
y	Yank (copy) to clipboard
x	Cut to clipboard
p	Paste from clipboard
Esc	Clear clipboard / marks

File Operations

Key	Action
d / D / Del	Delete item(s)
r	Rename
a	Create file (touch)
A	Create directory (mkdir)
T	Take (mkdir + cd into new directory)
Ctrl-z	Undo last operation

Views & Display

Key	Action
Tab / Shift-Tab	Switch view tab (Usage, Duplicates, Age)
v	Toggle Tree / Miller layout
i	Toggle details panel
P	Cycle preview mode
t	Toggle theme (dark/light)
,	Open settings
R	Rescan current directory

Search & Sort

Key	Action
/	Search
s	Sort
S	Reverse sort

Directory Tabs

Key	Action
Ctrl-t	New directory tab
Ctrl-w	Close current tab
] / [	Next / previous tab
1-9	Switch to tab by number

Commands

Key	Action
:	Open command palette
?	Show help
q	Quit
Ctrl-c	Force quit

Command Palette

Command	Action
:q :quit	Quit
:cd <path>	Change directory
:touch <name>	Create file
:mkdir <name>	Create directory
:take <name>	Create dir and cd into it
:yank :y	Copy to clipboard
:cut :x	Cut to clipboard
:paste :p	Paste from clipboard
:delete :rm	Delete marked items
:rename <name>	Rename current item
:clear	Clear all marks
:theme dark|light	Set theme
:layout tree|miller	Set layout
:help	Show help

Library Usage

gravityfile is designed as a composable library:

use gravityfile_scan::{JwalkScanner, ScanConfig};
use gravityfile_analyze::{DuplicateFinder, DuplicateConfig};

// Scan a directory
let config = ScanConfig::new("/path/to/analyze");
let scanner = JwalkScanner::new();
let tree = scanner.scan(&config)?;

// Find duplicates
let dup_config = DuplicateConfig::builder()
    .min_size(1024u64)
    .build()?;
let finder = DuplicateFinder::with_config(dup_config);
let report = finder.find_duplicates(&tree);

println!("Found {} duplicate groups", report.group_count);
println!("Wasted space: {} bytes", report.total_wasted_space);

Crate Structure

• gravityfile - Main binary and CLI
• gravityfile-core - Core types (FileNode, FileTree, etc.)
• gravityfile-scan - File system scanning engine
• gravityfile-analyze - Analysis algorithms (duplicates, age)
• gravityfile-ops - File operations engine (copy, move, rename, delete)
• gravityfile-tui - Terminal user interface

Performance

• Parallel directory traversal via jwalk
• Memory-mapped I/O for large file hashing
• Partial hash optimization reduces disk reads for duplicate detection
• Event-driven TUI rendering minimizes CPU usage

Acknowledgements

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contributing

Contributions welcome! Please feel free to submit a Pull Request.