Recursivist

See the shape of any codebase in one command

Recursivist draws any directory as a color-coded tree and annotates it with lines of code, file sizes, modification times, and Git status. It can filter that tree, compare it with another, and export it in six formats, for a local folder or for a GitHub repository you haven't cloned.

Each file type gets its own color. Folder figures are totals for the files beneath them, and [M] and [U] mark modified and untracked files.

Installation

pip install recursivist

Prefer an isolated install? pipx install recursivist and uv tool install recursivist both work. Each installs the recursivist command and its shorter alias, rcv.

Features

• File statistics: lines of code, size, and modification time for every file, rolled up per folder. Sort by any of them, or just display them.
• Git status: modified, added, deleted, and untracked files are marked in the tree and can be sorted first.
• Filtering: exclude directories and extensions, match file names by glob or regex, and apply .gitignore-style files at every level of the tree.
• GitHub repositories: pass a URL wherever a path is accepted, pinned to a branch, tag, or subfolder if you like. Private repositories work with GITHUB_TOKEN set.
• Comparison: two trees side by side with their differences highlighted, in the terminal or as a self-contained HTML page. Either side can be local or on GitHub.
• Export: Markdown, JSON, HTML, SVG, plain text, and reStructuredText, with a pre-commit hook that regenerates them on every commit.
• Configuration: save your defaults once, or commit a project's to .recursivist.toml or pyproject.toml.
• And more: Nerd Font icons, shell completion for Bash, Zsh, Fish, and PowerShell, and a typed Python API.

Quick Start

# The current directory, or any path, as a tree
recursivist visualize
recursivist visualize path/to/project --depth 2

# Most lines of code first, with size and modification time alongside
recursivist visualize --sort-by-loc --size --mtime

# Changed files first, leaving out whatever .gitignore ignores
recursivist visualize --sort-by-git-status --ignore-file .gitignore

# Python files only, without the tests
recursivist visualize --include-pattern "*.py" --exclude-pattern "test_*"

# A GitHub repository, or one folder of one branch
recursivist visualize https://github.com/owner/repo
recursivist visualize https://github.com/owner/repo/tree/develop/src

# A fork against its upstream, saved as an HTML report
recursivist compare ./my-fork https://github.com/owner/repo --save

# Markdown for the docs, JSON for scripts, SVG for a README
recursivist export --format "md json svg" --output-dir docs

# Defaults for every run
recursivist config set exclude node_modules .git
recursivist config set ignore-file .gitignore

Documentation

The documentation covers every command and option. Begin with the quick start, borrow from the recipes for CI pipelines, self-updating structure docs, and jq analysis, or look things up in the CLI reference.