# 🦆 nestscan — Pretty Directory Trees in One Command

> *"Because sometimes you just need to see what's actually in a folder without losing your mind."*

---

## 🚀 Install

```bash
pip install nestscan
```

---

## ⚡ Usage

Navigate to any folder and run:

```bash
nestscan
```

It prints a clean, readable tree of your current directory — sorted, structured, and easy on the eyes.

You can also point it anywhere:

```bash
nestscan /path/to/my/project
```

---

## 🛠 All Options

| Flag | Description |
|------|-------------|
| `path` | Target directory to scan (default: current directory) |
| `-o`, `--output` | Save the tree to a text file (e.g., `-o tree.txt`) |
| `--all` | Include hidden/junk directories like `.git`, `node_modules`, `venv`, etc. |

### Examples

```bash
# Scan the current directory
nestscan

# Scan a specific path
nestscan /home/user/myproject

# Save output to a file
nestscan -o tree.txt

# Show everything, including hidden and junk folders
nestscan --all

# Combine options
nestscan /home/user/myproject --all -o full_tree.txt
```

---

## 📋 Example Output

```
Directory Tree for: /home/user/myproject
==================================================
myproject
├── src
│   ├── main.py
│   ├── utils.py
│   └── models
│       ├── user.py
│       └── post.py
├── tests
│   ├── test_main.py
│   └── test_utils.py
├── README.md
└── requirements.txt
```

Clean. Sorted. Directories first.

---

## ✨ What It Does

- 🌲 **Recursive tree generation** — walks the full directory structure and renders it with proper branch characters
- 📁 **Directories first** — folders are always listed before files at every level
- 🚫 **Skips the noise by default** — ignores `venv`, `.venv`, `node_modules`, `__pycache__`, `.git`, `build`, `dist`, and other clutter you never want to see
- 👁 **`--all` mode** — opt in to see everything when you actually need it
- 💾 **Optional file output** — save the tree to a `.txt` file for sharing, documentation, or README pasting
- 🪟 **Windows compatible** — ANSI colors work there too

---

## 🛠 Requirements

- Python 3.6+
- No third-party dependencies — pure stdlib, zero bloat

---

## ⚠️ Notes

- Directories you don't have permission to read will show `[Permission Denied]` instead of crashing
- Output is sorted alphabetically within each level, with directories always above files

---

## 🤝 Contributing

Found a bug? Have a wild idea? PRs welcome.

---

## 📜 License

Do whatever you want with it. Just stop doing `ls -la` and squinting at terminal output like it's 1995.

---

*By turnt ducky 🦆 — also check out [reqscan](https://github.com/turntducky/reqscan) for auto-generating `requirements.txt`.*