Skip to content

README.md

Latest commit

 

History

History
296 lines (220 loc) · 8.73 KB

README.md

File metadata and controls

296 lines (220 loc) · 8.73 KB
Raw

🌟 AstroFS

A blazing-fast, emoji-powered, oh-my-zsh inspired terminal file explorer built with Rust and Ratatui.

Build Status Latest Release Rust Version License

Image 1 Image 2 Image 3 Image 4

✨ Features

🎨 Beautiful UI

  • Multi-pane layout: File tree (30%) + Preview (70%) + Status bar
  • Emoji-based file types: 📁 Folders, 📄 Files, 🖼️ Images, ⚡ Executables, 🗜️ Archives
  • Colorful theme: Modern aesthetic with cyan, green, magenta, yellow highlights
  • oh-my-zsh/Powerlevel10k inspired: Git branch + dirty indicators in status bar
  • Responsive design: Automatically adjusts to terminal size

⚡ Performance

  • Parallel search: Lightning-fast file search using Rayon
  • Virtual scrolling: Only render visible items for smooth navigation
  • Instant directory loading: Fast directory traversal

🔍 Search System

  • Blazing-fast fuzzy search: Real-time search as you type
  • Relevance scoring: Exact match, starts-with, contains, fuzzy matching
  • Live results: Search updates instantly
  • Parallel traversal: Multi-threaded directory scanning

🛠️ Core Features

  • Navigate directories with keyboard (Vim-style keys supported)
  • File preview (text files, binary detection, directory listing)
  • Human-readable file sizes
  • Hidden file toggle (. key)
  • Git integration (branch, dirty status)
  • Page up/down navigation
  • Jump to first/last item

🎮 Keyboard Navigation

  • ↑/k - Move up
  • ↓/j - Move down
  • Enter - Open folder
  • Backspace/h - Go back to parent directory
  • / - Enter search mode
  • . - Toggle hidden files
  • F5 - Refresh directory
  • PgUp/PgDn - Page up/down
  • Home/End - Jump to first/last item
  • ? - Show help
  • q or Ctrl+C - Quit

🚀 Installation

Prerequisites

  • Rust 1.70 or higher
  • Cargo

Build from source

# Clone the repository
git clone https://github.com/programmersd21/astrofs.git
cd astrofs

# Build in release mode for best performance
cargo build --release

# Run the application
cargo run --release

📚 Usage

Basic Navigation

  1. Launch the app with cargo run --release
  2. Use arrow keys or j/k to navigate
  3. Press Enter to open a folder
  4. Press Backspace to go back
  5. Press q to quit

Search Mode

  1. Press / to enter search mode
  2. Type your search query
  3. Results appear in real-time with relevance scores
  4. Press Enter to navigate to the first result
  5. Press Esc to cancel search

File Preview

  • Text files: First 200 lines displayed
  • Code files: Syntax highlighting (planned)
  • Binary files: Shows "Binary file" with size
  • Directories: Lists contents

🏗️ Architecture

src/
├── main.rs          # Application entry point + event loop
├── app.rs           # Application state and business logic
├── ui.rs            # Ratatui UI rendering and layout
├── input.rs         # Keyboard event handling
├── files.rs         # File system operations
├── preview.rs       # File preview generation
├── search.rs        # Parallel search engine
├── theme.rs         # Colors, emojis, and styling
└── git.rs           # Git integration

🐍 Python Bindings

AstroFS provides comprehensive Python bindings for programmatic access. See PYTHON_BINDINGS.md for complete documentation.

Installation

pip install pyastrofs # THIS IS NOT IMPLEMENTED YET, SO YOU'LL NEED TO BUILD FROM SOURCE BY USING ./scripts/build_bindings

Quick Example

from pyastrofs import PyAstroFS

fs = PyAstroFS()
fs.navigate("/home/user")
files = fs.list_files()

for file in files:
    print(f"{file.name} - {file.size} bytes")

Building from Source

Use the build scripts in the scripts/ directory:

Linux/macOS

chmod +x scripts/build_bindings.sh
./scripts/build_bindings.sh --release
pip install whl/*.whl

Windows

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process
.\scripts\build_bindings.ps1 -Release
pip install whl/*.whl

Build Script Options

Both scripts support the same options:

# Linux/macOS
./scripts/build_bindings.sh --help
./scripts/build_bindings.sh --output build --release
./scripts/build_bindings.sh --debug --skip-stubs

# Windows
.\scripts\build_bindings.ps1 -Help
.\scripts\build_bindings.ps1 -OutputDir build -Release
.\scripts\build_bindings.ps1 -Release $false -GenerateStubs $false

All wheels are built to the whl/ directory with type stubs (pyastrofs.pyi) included.

🎨 Customization

The color theme and emojis can be customized in src/theme.rs:

pub struct Theme {
    pub folder: Style,      // Folders: cyan + bold
    pub executable: Style,  // Executables: green + bold
    pub image: Style,       // Images: magenta
    pub archive: Style,     // Archives: yellow
    // ... more styles
}

🔧 Dependencies

  • ratatui - Terminal UI framework
  • crossterm - Cross-platform terminal manipulation
  • rayon - Data parallelism for fast search
  • walkdir - Recursive directory traversal
  • ignore - Git-aware file walking
  • syntect - Syntax highlighting (ready for future use)
  • git2 - Git repository access
  • infer - File type detection
  • humansize - Human-readable file sizes
  • serde + serde_json - Configuration (ready for future use)
  • anyhow - Error handling
  • chrono - Date/time handling

Python Bindings Dependencies

For building Python bindings:

  • maturin - Build tool for Python packages (pip install maturin)
  • PyO3 - Python bindings framework (automatically managed by Cargo)

📦 Project Structure

astrofs/
├── src/               # Rust source code
├── scripts/           # Build and utility scripts
│   ├── build_bindings.ps1    # Windows PowerShell build script
│   └── build_bindings.sh     # Linux/macOS bash build script
├── whl/               # Built Python wheels (generated)
├── Cargo.toml         # Rust project manifest
├── pyproject.toml     # Python project configuration
├── pyastrofs.pyi        # Python type stubs
└── examples_python_bindings.py  # Python usage examples

🗺️ Roadmap

Implemented ✅

  • Multi-pane layout with automatic resizing
  • File navigation (keyboard-driven)
  • File preview (text, binary detection, directories)
  • Git integration (branch, dirty status)
  • Fast parallel search with fuzzy matching
  • Emoji file type indicators
  • Colorful oh-my-zsh inspired theme
  • Hidden file toggle
  • Status bar with Git info and file details
  • Page up/down navigation
  • Jump to first/last item
  • Help screen
  • Syntax highlighting in file preview

Planned Features 📋

  • File operations (copy, move, delete, rename)
  • Create new folders/files
  • Archive file preview (ZIP, TAR contents)
  • Image metadata display
  • Open files with default applications
  • Tab support (multi-pane workspaces)
  • Configurable themes (load from JSON)
  • Bookmarks for quick directory access
  • Search history
  • Command palette
  • Plugin system

🤝 Contributing

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

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

💡 Inspiration

This project was inspired by modern terminal tools like:

  • lf: Terminal file manager
  • ranger: Console file manager with VI key bindings
  • nnn: Blazing-fast terminal file manager
  • broot: Tree view file explorer

Made with ❤️ and 🦀 Rust