Skip to content

Basic Examples

This page provides simple examples of common Recursivist usage patterns. These examples are designed to help you get familiar with the basic capabilities of the tool.

Simple Visualization

Viewing the Current Directory

To visualize the current directory structure:

recursivist visualize

This will produce output similar to:

📂 my-project
├── 📁 src
│   ├── 📄 main.py
│   ├── 📄 utils.py
│   └── 📁 tests
│       ├── 📄 test_main.py
│       └── 📄 test_utils.py
├── 📄 README.md
├── 📄 requirements.txt
└── 📄 setup.py

Viewing a Specific Directory

To visualize a different directory:

recursivist visualize ~/projects/my-app

Limiting Directory Depth

To limit the depth of the directory tree (useful for large projects):

recursivist visualize --depth 2

Output:

📂 my-project
├── 📁 src
│   ├── 📄 main.py
│   ├── 📄 utils.py
│   └── 📁 tests
│       ⋯ (max depth reached)
├── 📄 README.md
├── 📄 requirements.txt
└── 📄 setup.py

Showing Full Paths

To show full file paths instead of just filenames:

recursivist visualize --full-path

Output:

📂 my-project
├── 📁 src
│   ├── 📄 /home/user/my-project/src/main.py
│   ├── 📄 /home/user/my-project/src/utils.py
│   └── 📁 tests
│       ├── 📄 /home/user/my-project/src/tests/test_main.py
│       └── 📄 /home/user/my-project/src/tests/test_utils.py
├── 📄 /home/user/my-project/README.md
├── 📄 /home/user/my-project/requirements.txt
└── 📄 /home/user/my-project/setup.py

File Statistics

Showing Lines of Code

To display and sort by lines of code:

recursivist visualize --sort-by-loc

Output:

📂 my-project (4328 lines)
├── 📁 src (3851 lines)
│   ├── 📄 main.py (245 lines)
│   ├── 📄 utils.py (157 lines)
│   └── 📁 tests (653 lines)
│       ├── 📄 test_main.py (412 lines)
│       └── 📄 test_utils.py (241 lines)
├── 📄 README.md (124 lines)
├── 📄 requirements.txt (18 lines)
└── 📄 setup.py (65 lines)

Showing File Sizes

To display and sort by file sizes:

recursivist visualize --sort-by-size

Output:

📂 my-project (1.2 MB)
├── 📁 src (850.5 KB)
│   ├── 📄 main.py (12.4 KB)
│   ├── 📄 utils.py (8.2 KB)
│   └── 📁 tests (45.7 KB)
│       ├── 📄 test_main.py (28.9 KB)
│       └── 📄 test_utils.py (16.8 KB)
├── 📄 README.md (4.2 KB)
├── 📄 requirements.txt (512 B)
└── 📄 setup.py (3.8 KB)

Showing Modification Times

To display and sort by modification times:

recursivist visualize --sort-by-mtime

Output:

📂 my-project (Today 14:30)
├── 📁 src (Today 14:25)
│   ├── 📄 main.py (Today 14:25)
│   ├── 📄 utils.py (Yesterday 18:10)
│   └── 📁 tests (Feb 15)
│       ├── 📄 test_main.py (Feb 15)
│       └── 📄 test_utils.py (Feb 10)
├── 📄 README.md (Today 10:15)
├── 📄 requirements.txt (Jan 20)
└── 📄 setup.py (Jan 15)

Combining Statistics

To show multiple statistics at once:

recursivist visualize --sort-by-loc --sort-by-size

Output:

📂 my-project (4328 lines, 1.2 MB)
├── 📁 src (3851 lines, 850.5 KB)
│   ├── 📄 main.py (245 lines, 12.4 KB)
...

Simple Exclusions

Excluding Specific Directories

To exclude directories like node_modules or .git:

recursivist visualize --exclude "node_modules .git"

Excluding File Extensions

To exclude files with specific extensions:

recursivist visualize --exclude-ext ".pyc .log"

Combining Exclusions

You can combine different exclusion methods:

recursivist visualize --exclude "node_modules .git" --exclude-ext ".pyc .log"

Basic Exports

Exporting to Markdown

To export the current directory structure to Markdown:

recursivist export --format md

This creates a file named structure.md in the current directory.

Exporting to Multiple Formats

To export to multiple formats at once:

recursivist export --format "txt md json"

Exporting to a Specific Directory

To export to a different directory:

recursivist export --format html --output-dir ./docs

Customizing the Filename

To use a custom filename prefix:

recursivist export --format json --prefix my-project

This creates a file named my-project.json.

Exporting with Statistics

To include file statistics in the export:

recursivist export --format html --sort-by-loc --sort-by-size

Simple Comparisons

Comparing Two Directories

To compare two directories:

recursivist compare dir1 dir2

This displays a side-by-side comparison in the terminal.

Exporting a Comparison

To save the comparison as an HTML file:

recursivist compare dir1 dir2 --save

This creates a file named comparison.html in the current directory.

Comparing with Statistics

To include file statistics in the comparison:

recursivist compare dir1 dir2 --sort-by-loc

This makes it easy to see not just structural differences but also differences in code volume.

Shell Completion

Generating Shell Completion for Bash

mkdir -p ~/.bash_completion.d
recursivist completion bash > ~/.bash_completion.d/recursivist
source ~/.bash_completion.d/recursivist

Generating Shell Completion for Zsh

mkdir -p ~/.zsh/completion
recursivist completion zsh > ~/.zsh/completion/_recursivist

Then add to your .zshrc:

fpath=(~/.zsh/completion $fpath)
autoload -U compinit; compinit

Version Information

To check the version of Recursivist:

recursivist version

Next Steps

These basic examples should help you get started with Recursivist. For more advanced examples, check out: