🎖️ Sergeant (sgt)

Interactive TUI Directory Navigator for Terminal - "Leave it to the Sarge!"

Sergeant is a interactive terminal user interface (TUI) for navigating directories and managing files. Instead of typing cd and file manipulation commands, just run sgt, use arrow keys and keyboard shortcuts to navigate, preview, copy, move, and organize your files. Simple, fast, and elegant.

• 🗂️ Visual Directory Navigation - See all directories and files at a glance
• ⌨️ Keyboard Driven - Arrow keys, vim bindings (hjkl), and shortcuts
• 🎨 Color-Coded Display - Directories in cyan, files grayed out
• 📊 Smart Scrolling - Handles directories with hundreds of items
• 🔍 Git Branch Display - Shows current git branch in header
• 👤 Ownership Toggle - View file permissions and ownership (press 'o')
• 📑 Bookmarks - Save and quickly navigate to favorite directories

• 📋 Copy/Cut/Paste - Mark files with spacebar, copy (c), cut (x), and paste (p)
• ✂️ Multi-file Selection - Mark multiple files/folders for batch operations
• 🗑️ Delete with Confirmation - Safe deletion with confirmation dialog
• ✏️ Rename - Rename files and folders with pre-filled input
• 🔄 Conflict Resolution - Smart handling of file conflicts (skip/overwrite/rename)
• 📄 File Preview - View markdown files with glow, code files with vim/nano

• 🔎 Fuzzy Search - Integrate with fzf for fast file finding
• ❓ Help Modal - Press 'm' for comprehensive key mapping reference
• 🚀 Instant CD - Select and change directory in one smooth motion

• Ruby 2.7 or higher (Ruby 3.x recommended)

The curses gem (installed automatically) requires native libraries:

macOS:

# Usually works out of the box
# If you get errors, install Xcode Command Line Tools:
xcode-select --install

# Recommended: Use Homebrew Ruby instead of system Ruby
brew install ruby
# Add to ~/.zshrc: export PATH="/opt/homebrew/opt/ruby/bin:$PATH"

Linux (Debian/Ubuntu):

sudo apt-get install libncurses-dev ruby-dev

Linux (Fedora/RHEL):

sudo dnf install ncurses-devel ruby-devel

• glow - For beautiful markdown preview (brew install glow or go install github.com/charmbracelet/glow@latest)
• fzf - For fuzzy file search (brew install fzf or sudo apt-get install fzf)

Once published to RubyGems:

gem install sergeant

# Clone the repository
git clone https://github.com/biscoitinho/Sergeant.git
cd Sergeant

# Build and install the gem locally
gem build sergeant.gemspec
gem install ./sergeant-1.0.0.gem

That's it! The sgt command will automatically be added to your PATH.

If you want to work on the gem:

# Clone and setup
git clone https://github.com/biscoitinho/Sergeant.git
cd Sergeant

# Install dependencies
bundle install

# Run directly without installing
bundle exec bin/sgt

# Start sergeant in current directory
sgt

# Navigate and select
# Arrow keys or j/k to move up/down
# Enter or l to enter directory
# h to go back
# q to quit and cd to selected directory

Create a ~/.sgtrc file to customize colors and bookmarks:

# Color theme (available: black, red, green, yellow, blue, magenta, cyan, white)
[colors]
directories=cyan
files=white
selected_bg=blue
selected_fg=black
header=yellow
path=green
git_branch=magenta

# Bookmarks
[bookmarks]
home=/home/user
projects=~/projects
documents=~/Documents

# Install development dependencies
bundle install

# Run all tests
bundle exec rspec

# Run specific test file
bundle exec rspec spec/utils_spec.rb

# Run with documentation format
bundle exec rspec --format documentation

# Run rubocop linter
bundle exec rubocop

# Auto-correct issues
bundle exec rubocop -A

sergeant/
├── bin/
│   └── sgt                   # Executable command
├── lib/
│   ├── sergeant.rb           # Main application class
│   └── sergeant/
│       ├── version.rb        # Gem version
│       ├── config.rb         # Configuration and bookmark management
│       ├── utils.rb          # Utility functions (formatting, file detection)
│       ├── rendering.rb      # UI rendering and display logic
│       ├── modals.rb         # Modal modules loader
│       └── modals/           # Modal dialog modules
│           ├── navigation.rb       # Bookmark navigation
│           ├── dialogs.rb          # Info/error/confirmation dialogs
│           ├── file_operations.rb  # File preview, copy, paste, delete, rename
│           └── help.rb             # Help modal with key mappings
├── spec/                     # RSpec test suite
├── sergeant.gemspec          # Gem specification
├── Gemfile                   # Bundler configuration
└── README.md                 # This file

Contributions are welcome! Please feel free to submit a Pull Request. Be warn, that I reserve my personal judgement to new features as I'm very focused on not to bloat it with too many functionalities

MIT License

• Built with Ruby and ncurses
• Inspired by Omarchy linux and terminal file managers like ranger and nnn
• Uses glow for markdown rendering
• Integrates with fzf for fuzzy finding

"Leave it to the Sarge!" 🎖️