PlantingTree

PlantingTree is a lightweight, modular command-line development tool designed to generate exact filesystem structures (directories and empty files) from text-based tree diagrams.

It streamlines project bootstrapping and scaffold generation by parsing standard ASCII/Unicode tree representations—such as those generated by the Linux tree command or written manually—while automatically stripping inline comments and annotations.

Features

• Automated Scaffolding: Instantly convert text tree diagrams into real directory and file structures.
• Intelligent Comment Stripping: Automatically ignores inline comments (#, //, -, --) and metadata enclosed in brackets or parentheses.
• Indentation & Hierarchy Awareness: Accurately resolves parent-child relationships using a stack-based parser that evaluates prefix lengths (spaces, tabs, and tree-drawing characters like ├── and └──).
• Directory Detection: Automatically identifies directories via trailing slashes (/ or \) or the presence of child nodes.
• Safe Execution: Creates directories and empty files without overwriting existing file contents.
• PEP 668 Compliant: Fully compatible with modern Linux distributions via isolated environment installations (pipx or venv).

Installation

Recommended: Installation via pipx (Linux / macOS / Windows)

On modern operating systems (such as Ubuntu 24.04+ or Debian 12+) that enforce PEP 668 externally managed environments, installing via pipx is the standard best practice.

1. Ensure pipx is installed and configured:

   sudo apt install pipx
   pipx ensurepath

2. Install the package in editable (developer) mode from the root directory:

   pipx install -e .

Alternative: Standard Virtual Environment (venv)

If you prefer using a traditional Python virtual environment:

python3 -m venv venv
source venv/bin/activate
pip install -e .

Usage

Once installed, the plantingtree command becomes available globally in your terminal.

Basic Syntax

plantingtree <path_to_tree_file> [options]

Examples

Generate the filesystem structure in the current working directory based on tree.txt:

plantingtree ./tree.txt

Generate the structure inside a specific target directory:

plantingtree ./tree.txt -d /path/to/target_directory

CLI Arguments

Argument	Type	Description	Default
tree_file	Positional	Path to the text file containing the tree diagram.	Required
-d, --dest	Optional	Destination root directory for the generated structure.	. (Current Dir)
-h, --help	Optional	Show help message and exit.	N/A

Tree File Syntax Rules

PlantingTree is designed to be forgiving and flexible when parsing text files. It adheres to the following rules:

1. Tree Drawing Characters: Standard line-drawing symbols (│, ├, └, ─, |, +, -) and spaces/tabs are calculated to determine the hierarchy level.
2. Inline Comments: Anything following #, //, or a hyphen description separator (- or --) on the same line is ignored.
3. Metadata: Text inside parentheses (...), square brackets [...], or curly braces {...} at the end of a line is stripped.
4. Directories vs. Files:

• Any node with a trailing slash (/ or \) is explicitly created as a directory.
• Any node that acts as a parent to other indented nodes is automatically treated as a directory.
• All terminal leaf nodes without trailing slashes are created as empty files.

Sample Input (tree.txt)

gg-cli/                           # Root project directory
├── pyproject.toml                // Build configuration
├── README.md                     - Project documentation
└── gg_cli/                       (Main package)
    ├── __init__.py
    ├── main.py                   -- Entry point
    ├── config.py                 [Configuration settings]
    └── commands/                 # CLI subcommands
        ├── __init__.py
        ├── base.py
        ├── init_cmd.py
        └── flow_cmd.py

Execution Output

$ plantingtree ./tree.txt
Successfully generated 3 directories and 8 files in: /home/user/projects/rallm/plantingtree

Project Architecture

The codebase follows separation of concerns and modular software engineering principles:

src/plantingtree/
├── __init__.py      # Package metadata and versioning
├── parser.py        # AST generation, prefix calculation, and comment stripping
├── builder.py       # Filesystem interaction and directory/file generation
└── cli.py           # Command-line interface and argument parsing

• parser.py: Converts raw text lines into an in-memory Abstract Syntax Tree (AST) using a stack-based algorithm.
• builder.py: Traverses the AST and executes standard pathlib system calls to construct the hierarchy safely.
• cli.py: Handles user input, validation, and terminal feedback.

License

This project is licensed under the MIT License. See the LICENSE file for more details.