The Problem
Every developer has been there: you're reading documentation, see a beautiful project structure, and think "I'll just recreate this quickly."
Fifteen minutes later, you're still typing mkdir and touch, you've made three typos, and you're wondering why this isn't automated.
I was working on a project when I realized I'd recreated the same project structure three times in one week (I don't use LLMs when I code). That was the moment I decided to build tree2fs.
What is tree2fs?
tree2fs is a Python package that converts tree-formatted text into actual filesystem structures.
Instead of manually creating each folder and file, you write:
project/
├── src/
│ ├── main.py
│ └── utils.py
├── tests/
└── README.md
And run:
tree2fs tree.txt
Done. Your entire structure is created.
Architecture Decisions
1. Two-Phase Architecture
Separate Parsing from Filesystem Operations
Text File → Parser → Tree Data Structure → Builder → Filesystem
2. Tree Data Structure
Use Proper Tree Nodes Instead of Path Stacks
class Node:
def __init__(self, data: FileItem, parent: Optional['Node'] = None):
self.data = data
self.children: List['Node'] = []
self.parent = parent
Why:
- Clarity: Tree operations are explicit and understandable
- CS Fundamentals: Standard tree algorithms (DFS, BFS) work naturally
- Extensibility: Easy to add tree operations (find, count, height, etc.)
- Debugging: Can inspect tree structure independently
- Parent References: Node stores parent, enabling upward traversal
3. Text Format Choice
Tree-Formatted Text Over JSON/TOML/YAML (I may add them too in future versions)
project/
├── src/
│ └── main.py
└── tests/
Why:
- Copy-Paste Ready: Most documentation already uses this format
- Visual Clarity: Hierarchy is immediately obvious
- Source Matching: ChatGPT, Claude, docs all output trees
- Natural Comments: ├── config.py # handles configuration
- Zero Conversion: No need to translate from other formats
Trade-off:
- Parsing │ ├ └ ─ is harder than
json.loads()
4. Zero Dependencies
- Security: No third-party vulnerabilities
- Compatibility: Works everywhere Python works
- Installation Speed: No dependency resolution
- Maintenance: No dependency updates to track
- Size: Lightweight package
5. CLI + API Design
Provide Both Interfaces
CLI:
tree2fs tree.txt --verbose --dry-run
Python API:
from tree2fs import create_from_tree
create_from_tree("tree.txt", verbose=True)
Why Both:
- CLI: Quick usage, shell scripts, CI/CD
- API: Programmatic control, testing, integration
- Different Users: Command-line users vs. Python developers
### 6. Dry-Run Mode
Add Preview Without Creation
tree2fs tree.txt --dry-run
Why:
- Safety: Preview before making changes
- Verification: Check if structure is correct
- Testing: Verify parser without side effects
- User Confidence: See what will happen
Architecture Diagram
┌─────────────────────────────────────────────────────────────┐
│ tree2fs │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌───────────────────┐ │
│ │ CLI │────▶│ API │────▶│ create_from_tree │ │
│ └──────────┘ └──────────┘ └─────────┬─────────┘ │
│ │ │
│ ┌────────────────────────────────────────────▼─────────┐ │
│ │ TreeParser │ │
│ │ • parse_line(line) → FileItem │ │
│ │ • build_tree(file) → Node │ │
│ └────────────────────────────┬─────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Tree Data Structure │ │
│ │ │ │
│ │ Node FileItem │ │
│ │ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ data │◀───────│ filename │ │ │
│ │ │ children[] │ │ level │ │ │
│ │ │ parent │ │ comment │ │ │
│ │ └──────────────┘ └──────────────┘ │ │
│ └────────────────────────────┬────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ FilesystemBuilder │ │
│ │ • build(root) → create structure │ │
│ │ • _traverse_and_create(node) → DFS │ │
│ │ • _create_directory(path) │ │
│ │ • _create_file(path) │ │
│ └─────────────────────────────┬───────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Filesystem │ │
│ │ 📁 Directories & 📄 Files │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
Try It Out
pip install tree2fs
GitHub: https://github.com/ABDELLAH-Hallou/tree2fs
Let me know what you think in the comments!