A tool to export directory structure and optionally include file contents for selected extensions.
Project description
DirScribe — Explore, Document, and Share Your Directory Structures
DirScribe is a lightweight yet powerful CLI tool and Python library for exporting directory structures in either text or JSON format. It helps you optionally include file contents, detect programming languages, skip hidden items, limit file reading by size, show metadata (size and modification time), and output results directly to your terminal or a file.
Created by: Kazuki Kawamura (Caspy /ˈkæspi/, かすぴー)
License: MIT License
Quick Look
If you run:
dirscribe /path/to/your_project
You'll see a text-based tree of your directory structure with file contents (example below):
📁 your_project/
📄 main.py (Python)
├─ Content:
│ def calculate_total(items):
│ return sum(item.price for item in items)
│
│ def main():
│ print("Processing orders...")
│
📁 templates/
📄 index.html (HTML)
├─ Content:
│ <!DOCTYPE html>
│ <html>
│ <head><title>My App</title></head>
│ <body><h1>Welcome</h1></body>
│ </html>
│
📄 style.css (CSS)
├─ Content:
│ body {
│ margin: 0;
│ padding: 20px;
│ font-family: sans-serif;
│ }
Or, if you prefer JSON:
dirscribe /path/to/your_project --output-format json
You get a structured JSON representation:
{
"type": "directory",
"name": "your_project",
"path": "absolute/path/your_project",
"children": [
{
"type": "file",
"name": "main.py",
"path": "...",
"language": "Python",
"content": "...",
...
},
...
]
}
Table of Contents
- Key Features
- Why DirScribe?
- Installation
- Quick Start
- Command-Line Usage
- Python Library Usage
- Use Cases
- AI Tools Integration
- Contributing
- License
Key Features
- Text or JSON Output: Choose between a human-readable tree format or a structured JSON representation for advanced integrations.
- File Content Inclusion: Display the contents of files for specific extensions (e.g.,
.py,.js,.txt, etc.). - Language Detection: Show the programming language name (e.g.,
.py-> Python) alongside file names. - Skip Hidden: Omit hidden files and directories (those starting with a dot).
- Maximum Size Limit: Automatically skip file content if a file exceeds a specified byte-size.
- Metadata Display: Show file size and last modification timestamp in the output.
- Save to File: Output can be redirected to a file rather than just printing to the console.
- Highly Configurable: Combine various options to fit your exact needs.
Why DirScribe?
- Instant Documentation: Quickly generate a snapshot of your codebase – perfect for onboarding new team members or archiving project structures.
- Efficient Code Reviews: Include file contents up to a specified size, letting you skim important files without digging into each folder manually.
- Language Insights: Recognize the languages used in your project at a glance.
- Scriptable: Integrate DirScribe into CI/CD pipelines or other automated workflows to maintain updated structure maps.
- Open Source & Community-Driven: MIT-licensed and easy to extend.
Installation
You can install DirScribe either by cloning this repository or from your own distribution setup:
# From source (assuming you're in the DirScribe project directory):
pip install .
If you're editing the source, you might prefer:
pip install -e .
(This sets up DirScribe in "editable" mode so changes in the code take immediate effect.)
If DirScribe is published on PyPI in the future, you'll be able to run:
pip install dirscribe
directly.
Quick Start
Generate a text listing of a directory:
dirscribe /path/to/project
Generate a JSON output and save it to a file:
dirscribe /path/to/project --output-format json --output-file project_structure.json
That's it! Customize the output further using the rich set of options explained below.
Command-Line Usage
Once installed, you can run dirscribe in your terminal:
dirscribe [DIRECTORY] [OPTIONS]
Common Options
-
-e, --extensions <EXT ...>
Specify which file extensions to include content for (e.g. -e .py .js). -
--detect-language
Enables language detection based on file extensions.
Example: .py -> Python, .js -> JavaScript, etc. -
--skip-hidden
Skips files and directories whose names begin with. -
--max-size <BYTES>
Maximum file size (in bytes) to read. Files larger than this are ignored (content not shown). -
--show-metadata
Displays file metadata (size in bytes, last modification time) next to file content. -
--output-format <text|json>
Output either a text-based tree or JSON structure. Defaults to text. -
--output-file <FILE>
Write the output to the specified file instead of printing to stdout.
Example: Combine Multiple Options
dirscribe /path/to/src \
-e .py .html \
--detect-language \
--skip-hidden \
--max-size 2000 \
--show-metadata \
--output-format text \
--output-file output.txt
What it does:
- Recursively scans
/path/to/src - Shows contents of files with
.pyor.htmlextension (up to 2000 bytes) - Skips hidden items (names starting with .)
- Displays file size & last modified time
- Identifies language names where possible
- Renders as a textual tree
- Saves it to output.txt (instead of printing to the terminal)
Python Library Usage
DirScribe can also be used as a library in your Python scripts or applications:
from pathlib import Path
from dirscribe.core import export_directory_structure
def main():
directory = Path("/path/to/src")
# Export directory structure as text (list of lines)
lines = export_directory_structure(
target_dir=directory,
include_extensions=[".py", ".html"],
skip_hidden=True,
max_size=2000,
show_metadata=True,
detect_language=True,
output_format="text",
output_file=None # if you'd like to write to a file, pass Path("output.txt")
)
# If output_format="text" and output_file=None, you get a list of lines
for line in lines:
print(line)
if __name__ == "__main__":
main()
Parameters
target_dir (Path): The folder you want to scan.include_extensions (List[str], optional): List of extensions for which file contents should be shown.skip_hidden (bool, default=False): Skip hidden files/directories.max_size (int, optional): Skip content for files larger than this size.show_metadata (bool, default=False): Show size and last modification time.detect_language (bool, default=False): Attach a language field based on file extension.output_format (str, default="text"): Either "text" or "json".output_file (Path, optional): If provided, write output to that file.
The function returns:
- A list of strings (text lines) if
output_format="text"andoutput_file=None, or - A JSON string if
output_format="json"andoutput_file=None. - If
output_fileis set, the data is written to the file, and the function returns an empty list or empty string.
Use Cases
Instant Project Documentation
Generate a tree-like structure of your source code, complete with file contents (for specific extensions) and metadata. Ideal for:
- Sharing with collaborators
- Creating "at-a-glance" docs
Code Review & Auditing
Quickly see which files exist, their languages, and read short/medium files directly without jumping between directories.
Security / Compliance Checks
Skip hidden or large files, or selectively scan certain file types to ensure they meet certain criteria.
CI/CD Integration
Save a JSON manifest of your repository structure as part of your build artifacts. Compare structure between builds or track changes over time.
Scripting / Automation
If you need to parse directory contents in a custom pipeline, DirScribe's Python API and JSON output can be easily integrated.
AI Tools Integration
DirScribe's output is perfect for feeding into ChatGPT or other AI tools to analyze or summarize a project's structure:
- Generate a text or JSON snapshot:
dirscribe /path/to/src --output-format text > structure.txt
-
Copy-Paste the contents of
structure.txtinto ChatGPT (or any AI model). -
Ask the AI:
- "Give me an overview of this project."
- "Identify potential security concerns."
- "Suggest improvements or refactoring ideas."
By providing AI with a precise structure (and optionally file contents), you can quickly gain insights or documentation without manual exploration.
Contributing
Contributions, suggestions, and bug reports are warmly welcomed! Check out our CONTRIBUTING.md to learn how to propose changes or open pull requests. We also encourage you to open an issue if you encounter problems or have feature requests.
Ways to help:
- Code contributions (new features, bug fixes, refactoring)
- Documentation improvements (clarify instructions, add examples)
- Language mapping expansions (add more file extensions to LANGUAGE_MAP)
- Feedback and testing on different OS environments or large-scale projects
If you find DirScribe valuable, please consider starring the repository and sharing it with your fellow developers!
License
This project is distributed under the MIT License. © 2025 Kazuki Kawamura
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file dirscribe-0.1.1.tar.gz.
File metadata
- Download URL: dirscribe-0.1.1.tar.gz
- Upload date:
- Size: 13.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.0.1 CPython/3.10.16
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
95e139980b03e0463c616e3947b5b47229f7fdc58e5bbababacd65336419650d
|
|
| MD5 |
47df98be2988db8d731ed7e269b00957
|
|
| BLAKE2b-256 |
1093d38d31aad90ffaea7ba63776733f6da87b75279d78682dd7246aa7ac91c8
|
File details
Details for the file dirscribe-0.1.1-py3-none-any.whl.
File metadata
- Download URL: dirscribe-0.1.1-py3-none-any.whl
- Upload date:
- Size: 10.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.0.1 CPython/3.10.16
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
bca5fdfe2b21139d323935c79abc6f58b1d4f2bc7f0c80dd15467a284d4c8781
|
|
| MD5 |
2935d030e72538fa457f12bad3573db3
|
|
| BLAKE2b-256 |
712b2f2497cc7b4b64d2e140a8d95deaba7e4d598e2d12d08b9419648f57bfd2
|
