✨ Features

📦 Installation

pip install rich-tree

Requires Python 3.6+ and a Nerd Font for icons to render correctly.

With pipx (recommended for CLI tools):

pipx install rich-tree

Run without installing:

pipx run rich-tree .

Development version from GitHub:

pip install git+https://github.com/wasi-master/rich-tree

🚀 Quick Start

# Display tree for the current directory
rtree

# Or use the Python module form
python -m rtree

# Show a specific directory
rtree /path/to/project

Run the interactive onboarding wizard (recommended on first install):

rtree --onboard

This verifies your Nerd Font is set up correctly and walks you through configuration.

📖 Usage

rtree [OPTIONS] [DIRECTORY]

DIRECTORY defaults to . (current directory) if omitted.

Options

Examples

# Show sizes and git status, 3 levels deep
rtree -ss -sg -d 3

# Show everything — including hidden and gitignored files
rtree --all --no-gitignore

# Exclude build artifacts
rtree -e dist,build,__pycache__

# Export a styled HTML snapshot
rtree -o project-tree.html

# Show all file metadata
rtree -ss -sc -sm -sa

# Shallow view of a project
rtree -d 1 /path/to/project

🧩 Nerd Font Setup

rich-tree uses Nerd Fonts for its icon set. You need to:

1. Download a Nerd Font from nerdfonts.com/font-downloads
   (Recommended: JetBrainsMono Nerd Font, CaskaydiaCove, or FiraCode Nerd Font)
2. Install the font on your system
3. Set your terminal's font to the installed Nerd Font

Verify with:

rtree --onboard

If icons appear as □ or ?, follow the instructions shown by the wizard.

🔗 Alias Setup

Replace the classic tree command with rtree for a better experience everywhere:

Bash / Zsh — add to ~/.bashrc or ~/.zshrc:

alias tree="rtree"

PowerShell — add to your PowerShell profile:

New-Alias tree rtree

Windows CMD — create C:\Windows\System32\tree.bat:

@echo off
call rtree %*

Run rtree --onboard for interactive, shell-specific alias instructions.

📚 Documentation

Full documentation is available in the docs/ folder and at the project website:

🛠️ How It Works

rtree .
  │
  ├── Reads .gitignore at each level (hierarchical, full spec support)
  ├── Scans directories with os.scandir() (fast, lazy)
  ├── Resolves icon + color for each entry (name → extension → fallback)
  ├── Optionally fetches git status via git status --porcelain -z
  ├── Optionally reads file stat() for size/timestamps
  └── Renders the Rich Tree widget to the terminal

Dependencies:

🤝 Contributing

Contributions are welcome! The most common contribution is adding icons for new file types.

See Contributing Guide for full instructions.

Quick start:

git clone https://github.com/wasi-master/rich-tree.git
cd rich-tree
pip install -e ".[dev]"

📄 License

MIT — © Wasi Master