Enhancing Ranger with fzf and bat: A Powerful File Search Integration
Table of Contents 📑
The ranger file manager is already a powerful tool for navigating your filesystem, but with the addition of fzf
(fuzzy finder) and bat
(syntax highlighter), you can supercharge your file searching capabilities. This guide will show you how to integrate these tools for a seamless and visually appealing search experience.
Changelog
Date | Change |
---|---|
2025-07-18 | Initial Version: Created guide for integrating fzf and bat with ranger |
1. Prerequisites
Before we begin, ensure you have the following tools installed on your system:
- ranger: The terminal file manager
- fzf: Command-line fuzzy finder
- bat: A cat clone with syntax highlighting
Installation on Various Distributions
# For Debian/Ubuntu
sudo apt update && sudo apt install ranger fzf bat
# For Arch Linux
sudo pacman -S ranger fzf bat
# For Fedora
sudo dnf install ranger fzf bat
Note: On some distributions, bat
might be packaged as batcat
. You can create an alias in your shell configuration file:
alias bat='batcat'
2. Creating the Custom fzf_select Command
The integration requires adding a custom command to ranger. This command will use fzf
for searching and bat
for file previews.
2.1. Create or Edit commands.py
First, navigate to your ranger configuration directory and create or edit the commands.py
file:
mkdir -p ~/.config/ranger
touch ~/.config/ranger/commands.py
If you don’t have a commands.py
file yet, you can generate a template with:
ranger --copy-config=commands
2.2. Add the fzf_select Command
Open the commands.py
file in your favorite text editor and add the following code:
from ranger.api.commands import Command
import os
import subprocess
class fzf_select(Command):
"""
:fzf_select
Find a file or directory using fzf with preview using bat, excluding certain directories unless currently in them.
"""
def execute(self):
exclude_dirs = ['Remote', 'USBmount', 'NFSshares', 'Games_ROMS'] # List of directories to exclude
current_dir = os.getcwd()
base_name = os.path.basename(current_dir)
# Check if the current directory is in the list of directories to exclude
if base_name in exclude_dirs:
find_command = "find . -type f -o -type d"
else:
# Construct the find command with exclusion criteria
exclude_opts = ' '.join(f"-path './{d}' -prune -o" for d in exclude_dirs)
find_command = f"find . \\( {exclude_opts} -false \\) -o \\( -type f -o -type d \\) -print"
command = f"{find_command} | fzf --preview '[[ -f {{}} ]] && bat --style=numbers --color=always {{}} || echo {{}} is a directory' --preview-window=right:70%:wrap --exact"
fzf = subprocess.Popen(command, stdout=subprocess.PIPE, shell=True, text=True, cwd=current_dir)
selected, _ = fzf.communicate()
if fzf.returncode == 0:
selected = selected.strip()
selected_path = os.path.abspath(selected)
if os.path.isdir(selected_path):
# Change to the directory if it's a directory
self.fm.cd(selected_path)
else:
# Open the file if it's a file
self.fm.select_file(selected_path)
# Explicitly refresh the ranger window
self.fm.ui.redraw_window()
This command will:
- Exclude specific directories from the search (unless you’re already in one of them)
- Use
bat
for file previews and show a simple message for directories - Execute
fzf
with the appropriate options - Navigate to the selected file or directory
- Explicitly refresh the ranger window after selection
3. Creating a Keyboard Shortcut
Now that we have our custom command, let’s create a keyboard shortcut to invoke it easily.
3.1. Edit rc.conf
Open your ranger configuration file:
vim ~/.config/ranger/rc.conf
If you don’t have this file yet, you can generate it with:
ranger --copy-config=rc
3.2. Add the Keyboard Mapping
Add the following line to map the fzf_select
command to a keyboard shortcut. In this example, we’ll use zi
(which stands for “zoom in”):
map zi fzf_select
This shortcut is easy to remember as zi
stands for “zoom in” - which is exactly what this command does: it zooms into your file structure to quickly find what you’re looking for.
Shortcut | Description |
---|---|
zi | Start fuzzy search with fzf and bat preview (“zoom in” to your files) |
4. Advanced Configuration
4.1. Customize Directory Exclusions
You can modify the list of directories to exclude from the search by changing the exclude_dirs
list in the fzf_select
command:
exclude_dirs = ['Remote', 'USBmount', 'NFSshares', 'Games_ROMS', 'VirtualMachines'] # Add or remove directories as needed
4.2. Show Hidden Files
If you want to include hidden files in your search, modify the find_command
variable:
find_command = "find . -type f -o -type d -name '.*' -o -type f -o -type d"
4.3. Customize Preview Options
You can customize how bat
displays file previews by modifying the preview part of the command:
command = f"{find_command} | fzf --preview '[[ -f {{}} ]] && bat --style=full --color=always --line-range :150 {{}} || echo {{}} is a directory' --preview-window=right:60%:wrap --exact"
This example:
- Uses the “full” style for bat (includes line numbers, Git modifications, etc.)
- Shows up to 150 lines in the preview
- Sets the preview window width to 60% of the terminal
5. Usage
Once everything is set up, you can use your new fuzzy search capability:
- Open ranger in your terminal
- Press your configured shortcut (e.g.,
zi
) - Type to search for files
- Use arrow keys to navigate through results
- Press Enter to select a file or directory
6. Troubleshooting
6.1. Command Not Found
If you get a “Command not found” error when trying to use the shortcut:
- Make sure you’ve saved the
commands.py
file correctly - Restart ranger to load the new command
- Check that
fzf
andbat
are installed and in your PATH
6.2. Preview Not Working
If file previews aren’t displaying:
- Verify that
bat
is installed correctly - Try using
batcat
instead ofbat
if you’re on Debian/Ubuntu - Check if your terminal supports the preview feature
Summary
With this integration, you’ve significantly enhanced ranger’s search capabilities:
✅ Lightning-fast file searching with fuzzy matching
✅ Beautiful syntax-highlighted previews
✅ Seamless navigation to selected files
✅ Customizable interface and behavior
This setup combines the best of three powerful tools: ranger’s file management, fzf’s search capabilities, and bat’s beautiful syntax highlighting.