directorymap 0.3.2

CLI tool that tracks file and folders structure of a project

🗺️ directorymap

Project directory structure tracker CLI.
Lightweight, deterministic, and automation-friendly.

directorymap scans your project, applies ignore and limit rules, and generates a clean, reproducible snapshot of your filesystem structure. It is designed to help you track how your directory layout evolves over time.

---

Features

• Deterministic directory structure snapshots
• Ignore rules for filtering unwanted files
• Limit rules for controlled sampling of files
• Structure diffing between snapshots
• File and folder statistics
• Structural hashing for reproducibility
• Watch mode for automatic updates
• CI/CD friendly output

---

Installation

Install from PyPI

pip install directorymap

Install from source

python -m pip install -e .

---

Quick Start

directorymap init
directorymap build
directorymap diff
directorymap stats
directorymap hash
directorymap watch

---

Commands

Command	Description
init	Initialize .directorymap/ and create config + initial snapshot
build	Generate or update the structure snapshot
diff	Show differences from the previous snapshot
stats	Display file, folder, and size statistics
hash	Output a structural fingerprint
watch	Continuously update on file changes

---

Configuration

Configuration is stored at: .directorymap/config

Example

node_modules .git pycache .DS_Store *.log *.tmp dist

---

Ignore and Limit Rules

directorymap supports both ignore rules and controlled inclusion using limits.

Ignore rules

• Plain names are ignored globally
• Glob patterns (e.g. *.png) exclude matching files entirely

Example: *.png node_modules

Limit rules

You can restrict how many files of a certain pattern are included in the snapshot by adding a number: *.jpg 5

This means:

• If a directory contains many .jpg files, only up to 5 will be included
• Selection is deterministic to keep output stable

This is useful when:

• Folders contain large numbers of similar assets
• You want representative visibility without clutter
• Maintaining stable diffs is important

Combined example: *.jpeg 5 *.png *.log 2

---

Output Example

directorymap/
├─ directorymap/
│  ├─ __init__.py
│  ├─ cli.py
│  └─ core.py
├─ .DS_Store
├─ .gitignore
├─ pyproject.toml
├─ README.md
└─ uploadCmd.txt

---

Local Development

git clone https://github.com/sankalp6115/directorymap
cd directorymap
pip install build
python -m build
pip install dist/*.whl

Make changes inside directorymap/ and validate using:

directorymap build
directorymap diff
directorymap stats

---

Building the Package

pip install build
python -m build

---

Testing

Currently, there is no automated test suite. Verify functionality using CLI commands:

directorymap init
directorymap build
directorymap diff
directorymap stats
directorymap hash
directorymap watch

---

Contributing

1. Create a feature branch:

   git checkout -b feature/your-change

2. Commit your changes:

   git commit -m "Add feature"

3. Push to your branch:

   git push origin feature/your-change

4. Open a pull request with:
   • Description of changes
   • Steps to test locally
   • Expected output/behavior

---

Design Goals

• Deterministic output across environments
• Minimal configuration overhead
• Readable and diff-friendly structure
• Suitable for version control and automation workflows

---

Contact

[e-mail]