f — Folder Auto Banner
A directory listing with instant context.
What It Does
When you run f, you see:
- File listing (like
ls/exa/lsd) - Git status, last commit, commits today, branches
- Build status with duration
- TODO count
- Languages breakdown
- Ports in use
- Docker status
- Cached test results
All instantly, no extra commands needed.
vs lsd / eza
fab is not a drop-in ls replacement — it's a contextual directory dashboard. While lsd and eza focus on making ls pretty, f adds project context (git, TODOs, ports, docker, build status, code metrics) and daemon caching for instant repeated access.
| Feature | f | lsd | eza |
|---|---|---|---|
| Pretty listing | ✅ | ✅ | ✅ |
| Icons | ✅ | ✅ | ✅ |
| Tree view | ✅ | ✅ | ✅ |
| Git status | ✅ (rich) | ✅ | ✅ |
| Context banner | ✅ | ❌ | ❌ |
| Daemon caching | ✅ | ❌ | ❌ |
| TODO count | ✅ | ❌ | ❌ |
| Port detection | ✅ | ❌ | ❌ |
| Build status | ✅ | ❌ | ❌ |
| Language breakdown | ✅ | ❌ | ❌ |
Long format (-l) |
✅ (default) | ✅ | ✅ |
Recursive (-R) |
✅ | ✅ | ✅ |
See COMPETITORS.md for the full comparison.
Quick Start
# Build + install everything (binary, shell function, daemon, auto-banner hook)
This sets up:
- The
fbinary in~/.local/bin/ - The shell function (enables
f N→cdnavigation) - The auto-banner hook (shows a banner on every
cd) - The background daemon
If you only need the shell function (e.g., after a manual build):
Usage
Shell Function (f install)
The f install subcommand sets up the shell function that enables f N → cd navigation:
- Writes the shell wrapper (
fab-shell.zsh/fab-shell.bash) to~/.local/bin/ - Adds a
sourceline to~/.zshrcand/or~/.bashrc - Is idempotent — safe to run multiple times
This is called automatically by ./install.sh. You can also run it standalone:
The shell function is the single source of truth — it reads from the compiled-in src/shell_wrapper.rs constants, not from the standalone files in the repo root.
Numbered Navigation
When numbered = true in config (or enabled by default), each item gets a number:
[ 1] 📁 .github
[ 2] 📁 src
[ 3] 📄 README.md
Navigate with f N:
Note:
f Nrequires the shell function to be installed. Running./install.shorf installsets it up automatically. To activate it in your current terminal without restarting your shell:
CLI Flags (Actions)
Sorting
| Flag | Description |
|---|---|
--sort name|size|date|type|git|extension|version |
Sort by field |
-t, --timesort |
Sort by time modified |
-S, --sizesort |
Sort by size |
-X, --extensionsort |
Sort by extension |
-G, --gitsort |
Sort by git status |
--versionsort |
Natural sort (version numbers) |
--no-sort |
No sort, directory order |
--reverse |
Reverse sort |
--group-dirs first|last |
Group directories |
Display
| Flag | Description |
|---|---|
-a, --hidden |
Show dotfiles |
--tree [depth] |
Tree view (0 = unlimited) |
--group |
Group by type (dirs, files, symlinks) |
--filter <pattern> |
Filter by name |
--max <N> |
Limit items |
--compact |
Less info |
-R, --recursive |
Recurse into subdirectories |
--verbose |
More info |
Output
| Flag | Description |
|---|---|
--json |
JSON output |
--raw |
Plain text output |
Config File
Location: ~/.config/fab/config.toml
Open with: f config
Display Settings
[]
= "rwx" # rwx, octal, disable
= "default" # default, short, bytes
= "date" # date, relative
= true # append */=>@|
= false
= true
Column Selection
[]
= ["permission", "owner", "group", "size", "date", "name"]
= ["inode", "links"]
Feature Toggles
[]
= true
= true
= true
= true
= true
= true
Navigation
[]
= true # Show item numbers for f N navigation
= "micro" # Default editor for f N (overridden by $EDITOR)
Sorting
[]
= "name"
= false
= "first"
Recency Gradient
[]
# Color rows based on recency: same hues, dimmer for older files
# Bright new, dim old — at-a-glance scan of what changed recently
= "all" # "all", "age", "size", or "" to disable
= "gradient" # "gradient" (default) or "fixed"
Tiers: <1h = bold, <1d = normal, <1w = faded gray, <1m = dim, >1m = very dim. Recent files pop out; old files recede into the background.
Environment Variables
| Variable | Description |
|---|---|
FAB_NO_TODOS |
Set to 1 to disable TODO scanning |
FAB_NO_PORTS |
Set to 1 to disable port detection |
FAB_NO_DOCKER |
Set to 1 to disable Docker detection |
FAB_NO_METRICS |
Set to 1 to disable code metrics |
NO_COLOR |
Disable colors (per spec) |
EDITOR |
Editor for f config (default: vi) |
Testing
License
MIT