gpt-folder-tree 0.2.0
Generate real folder and file structures from GPT-style ASCII trees
License: MIT
Requires Python: >=3.11

# gpt-folder-tree

> **Create complete project folder structures from GPT-style ASCII trees — instantly.**

`gpt-folder-tree` is a lightweight Python utility that converts **ASCII folder trees (like those generated by ChatGPT or written in README files)** into real directories and files on your filesystem.

Perfect for:
- Bootstrapping new projects
- Recreating documented folder structures
- Automating scaffolding for frameworks, microservices, or libraries
- Turning design docs into real codebases

---

## ✨ Features

- 📂 Parse GPT / Unix-style ASCII folder trees
- 🧪 Dry-run mode to preview what will be created
- ⚡ Create folders **and files** automatically
- 🧩 Minimal, dependency-free, and fast
- 🐍 Pythonic API — easy to integrate into tools or CLIs

---

## 📦 Installation

```bash
# Install using pip
pip install gpt-folder-tree
```

```bash
# Install using uv
uv add gpt-folder-tree
```

---

## 🚀 Quick Start

### 1. Import the library

```python
from gpt_folder_tree import parse_tree, create_tree, dry_run
```

---

### 2. Define your folder structure (ASCII format)

```python
gpt_ascii_text = """
project/
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── config.py
│   ├── database/
│   │   ├── __init__.py
│   │   ├── connection.py
│   │   └── models.py
│   ├── api/
│   │   ├── __init__.py
│   │   ├── v1/
│   │   │   ├── __init__.py
│   │   │   ├── routes.py
│   │   │   └── schemas.py
│   ├── services/
│   │   ├── __init__.py
│   │   ├── auth_service.py
│   │   ├── user_service.py
│   │   └── email_service.py
│   ├── core/
│   │   ├── __init__.py
│   │   ├── security.py
│   │   └── dependencies.py
│   ├── utils/
│   │   ├── __init__.py
│   │   └── helpers.py
├── tests/
│   ├── __init__.py
│   ├── test_main.py
│   ├── test_auth.py
│   └── test_users.py
├── alembic/
│   ├── env.py
│   └── versions/
├── scripts/
│   └── seed_db.py
├── requirements.txt
├── .env
├── README.md
└── Dockerfile
"""
```

---

### 3. Parse the tree

```python
tree = parse_tree(gpt_ascii_text)
```

---

### 4. (Optional) Dry run — preview what will be created

```python
dry_run(tree)
```

**Output example:**

```
CREATE DIR  ./project
CREATE DIR  ./project/app
CREATE FILE ./project/app/main.py
...
```

---

### 5. Create the folders & files

```python
create_tree(tree)
```

✅ Your entire project structure is now created on disk.

---

## 🧠 How It Works

* Directories are detected by a trailing `/`
* Files are created as empty files
* Indentation depth determines parent-child relationships
* Compatible with GPT-generated trees and Unix-style layouts

---

## 🗂 API Reference

### `parse_tree(text: str) -> Node`

Parses an ASCII tree string into an internal tree structure.

---

### `dry_run(node: Node, base_path: str = ".")`

Prints what **would** be created without touching the filesystem.

---

### `create_tree(node: Node, base_path: str = ".")`

Creates all directories and files on disk.

---

## ⚠️ Notes & Best Practices

* Run `dry_run()` before `create_tree()` for safety
* Avoid running in sensitive directories (e.g., `/`, home root)
* ASCII tree must be properly indented (4 spaces per level)

---

## 🤝 Contributing

Contributions, issues, and feature requests are welcome.
This project is intentionally simple — clarity over complexity.

---

## ⭐ Why This Exists

Because copying folder structures from ChatGPT, README files, or documentation
**should not require manual folder creation**.

Turn ideas into structure. Instantly.