Metadata-Version: 2.4
Name: directorymap
Version: 0.3.1
Summary: CLI tool that tracks file and folders structure of a project
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# 🗺️ 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

```bash
pip install directorymap
```

### Install from source

```bash
python -m pip install -e .
```

---

## Quick Start

```bash
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

```bash
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:

```bash
directorymap build
directorymap diff
directorymap stats
```

---

## Building the Package

```bash
pip install build
python -m build
```

---

## Testing

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

```bash
directorymap init
directorymap build
directorymap diff
directorymap stats
directorymap hash
directorymap watch
```

---

## Contributing

1. **Create a feature branch:**
```bash
   git checkout -b feature/your-change
```

2. **Commit your changes:**
```bash
   git commit -m "Add feature"
```

3. **Push to your branch:**

```bash
   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

[sankalpomar6115@gmail.com](mailto:sankalpomar6115@gmail.com)
