rich-tree 1.0.0

A better tree command with beautiful icons and colors made in Python

rich-tree

A beautiful, icon-rich replacement for the classic tree command

Powered by Rich · Nerd Fonts · Python

---

Open demo.html in a browser for the best preview.

---

✨ Features

Feature	Description
🗂️ 220+ file type icons	Nerd Font glyphs for every major language and tool
🎨 Per-type colors	Brand-accurate colors for every file type
🔗 Clickable links	Files are hyperlinks in supported terminals
📊 File metadata	Show size, created, modified, and accessed timestamps
🌿 Git status overlay	See modified, added, deleted, and untracked files at a glance
🙈 Smart filtering	Reads .gitignore, hides dotfiles, supports custom exclusion lists
📁 Depth control	Limit recursion to N levels
🌐 HTML export	Save the styled tree as a shareable HTML file
🧙 Onboarding wizard	Interactive setup guide for fonts and aliases
🖥️ Cross-platform	Windows, macOS, and Linux

---

📦 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

Flag	Short	Description
--show-size	-ss	Show file sizes
--show-created	-sc	Show creation timestamps
--show-modified	-sm	Show modification timestamps
--show-accessed	-sa	Show last-accessed timestamps
--show-git	-sg	Overlay git status on files
--depth INTEGER	-d	Limit recursion depth (-1 = unlimited)
--exclude TEXT	-e	Comma-separated names to exclude
--ignore-dot	-id	Hide dotfiles
--all	-a	Show hidden & gitignored files
--no-gitignore		Disable .gitignore filtering
--export-html PATH	-o	Save output as HTML
--width SIZE	-w	Fit output to N characters wide
--soft		Enable soft text wrapping
--onboard		Run the interactive setup wizard
--version	-v	Print version and exit

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:

Document	Description
Getting Started	Installation, requirements, first run
CLI Reference	Every flag and argument explained
Features	Deep dive into all features
Icon System	Complete icon and color reference
Onboarding Wizard	Interactive setup wizard guide
Configuration	Defaults, exclusions, gitignore
Contributing	How to contribute
Changelog	Release history

---

🛠️ 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:

Package	Purpose
rich	Terminal rendering, Tree widget
click	CLI argument parsing
rich-click	Beautiful --help output
questionary	Interactive onboarding prompts
shellingham	Shell detection for alias instructions

---

🤝 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

---

Documentation · PyPI · Issues · Changelog