tree2cmd 0.2.1

Convert text directory trees (struct.txt) into real folders and files.

📘 tree2cmd

tree2cmd is a lightweight Python tool that instantly converts a text-based directory tree (like struct.txt) into real folders and files. It supports both ASCII and Unicode tree formats—including emojis—and generates safe shell commands using mkdir -p and touch.

It is perfect for quickly bootstrapping new projects, sharing folder layouts, automating templates, teaching directory structures, and turning documentation examples into actual directories.

Convert text-based directory trees into real folders and files.

---

📑 Table of Contents

• ✨ Overview
• 🚀 Quick Start
• 📦 Installation
• 📂 Example Input → Output
• 🔧 Usage Guide
• 🧠 How It Works
• 📚 Documentation
• 🧪 Running Tests
• 🔄 Versioning & Publishing
• 🤝 Contributing
• 🗺️ Roadmap
• 📄 License
• 👤 Author

---

✨ Overview

tree2cmd converts text-based directory trees (ASCII/Unicode) like:

Project/
├── src/
│   └── main.py
└── README.md

into actual folders and files using shell commands:

mkdir -p "Project/"
mkdir -p "Project/src/"
touch "Project/src/main.py"
touch "Project/README.md"

Perfect for:

✔ Rapid project scaffolding ✔ Teaching directory layouts ✔ DevOps automation ✔ Reproducible project templates ✔ Converting documentation examples into real directories

Fully tested across ASCII trees, Unicode trees, emoji trees, and mixed indentation styles.

---

🚀 Quick Start

1. Make struct.txt:

Project/
  src/
    main.py
  README.md

2. Convert to commands:

tree2cmd struct.txt

3. Actually create them:

tree2cmd struct.txt --run

---

📦 Installation

Stable release:

pip install tree2cmd

Latest development version:

pip install git+https://github.com/ajmanjoma/tree2cmd.git

---

📂 Example Input → Output

Input:

📦 App/
  backend/
    api.py
  README.md

Output:

mkdir -p "📦 App/"
mkdir -p "📦 App/backend/"
touch "📦 App/backend/api.py"
touch "📦 App/README.md"

This works for any:

• ASCII tree
• Unicode tree
• Emoji directory
• Mixed indentation
• Minimal struct format
• Multi-root trees

---

🔧 Usage Guide

Dry run (recommended):

tree2cmd struct.txt

Execute commands:

tree2cmd struct.txt --run

Save script:

tree2cmd struct.txt --save setup.sh

Use standard input:

cat struct.txt | tree2cmd --stdin

Show tree instead of commands:

tree2cmd struct.txt --tree

Disable logs:

tree2cmd struct.txt --no-verbose

---

🧠 How It Works

tree2cmd uses a 3-stage pipeline:

---

1️⃣ Parsing

Handles:

• ASCII trees (|-, +--, etc.)
• Unicode trees (├──, │, └──)
• Mixed whitespaces and unexpected characters
• Emojis and non-ASCII folder names
• Multi-root directories
• Deep nesting

Uses indentation and tree symbols to infer hierarchy.

---

2️⃣ Classification

Folder detection rules:

• Ends with / → folder
• Contains . → file
• Next line is more indented → folder
• Otherwise → file

---

3️⃣ Command Generation

Folders → mkdir -p Files → touch

All paths:

• Are normalized
• Are quoted
• Escape shell-sensitive characters

---

📚 Documentation

Topic	File
Usage Guide	docs/usage.md
CLI Options	docs/cli.md
Parser Details	docs/parser.md
API Reference	docs/api.md
FAQ	docs/faq.md
Contributing	docs/contributing.md
Changelog	docs/changelog.md

---

🧪 Running Tests

Run all tests:

python -m unittest discover -s tests -p "test*.py" -v

With Makefile:

make test

Coverage: 100% (parser + CLI)

---

🔄 Versioning & Publishing

1. Bump version automatically:

make version patch
# or minor / major

2. Build:

python -m build

3. Upload to PyPI:

twine upload dist/*

4. GitHub Actions (automatic):

• On tag push → build + test + publish
• On PR → run tests

Workflow located at:

.github/workflows/python-publish.yml

---

🤝 Contributing

All contributions are welcome!

1. Fork repo
2. Create a branch
3. Add tests for new features
4. Run tests
5. Open PR

See full guide: 📄 docs/contributing.md

---

🗺️ Roadmap

• Windows PowerShell support
• JSON/YAML → tree converter
• VSCode extension
• GUI visualizer
• Template engine (copy boilerplate files)

---

📄 License

MIT License — free for personal & commercial use.

---

👤 Author

Antony Joseph Mathew 📧 [e-mail] 🌐 GitHub: https://github.com/ajmanjoma/tree2cmd