SPDX-FileCopyrightText: 2025 João Soares SPDX-License-Identifier: CC-BY-4.0
A tiny utility to:
- Print a visual directory tree to the console and optionally save it to a text file (
src/tree_gen.py) - Recreate a directory and file structure from a previously saved tree layout file (
src/dir_gen.py)
This is handy for documenting project structures and for quickly scaffolding skeleton directories for demos, tutorials, or tests.
- Python 3.11+
You can run the scripts directly from the cloned repository; no installation is required.
Optional: create and activate a virtual environment first.
Print the directory tree for a given path. You can limit depth, include files, ignore patterns, and save the output to a file.
Examples (PowerShell):
- Print a tree of the current directory, directories only:
python .\src\tree_gen.py
- Print up to 5 levels, including files:
python .\src\tree_gen.py . -L 5 --files
- Ignore common folders and save to a file:
python .\src\tree_gen.py . --files --ignore ".git" --ignore "node_modules" --output tree.txt
Key options:
path(positional): root directory to start from; defaults to.-L,--levelN: max depth to display (default 99)--files: include files in the tree (by default only directories are shown)--ignore PATTERN: glob ignore patterns (repeatable)--output FILE: save the tree to FILE (.txt)--ascii: output ASCII connectors (|--,\--,|) instead of Unicode (├──,└──,│)
The output format is compatible with the companion generator below.
Given a text file produced by tree_gen.py (or a similarly formatted file), create the corresponding directory and file structure.
Examples (PowerShell):
- Create under the current directory:
python .\src\dir_gen.py .\tree.txt .
- Dry-run (show what would be created without touching the filesystem):
python .\src\dir_gen.py .\tree.txt . --dry-run
Key options:
layout(positional): path to a tree layout .txt fileroot(positional, optional): target root folder where the structure will be created; defaults to.--dry-run: preview actions only
Notes:
- Directory lines in the layout must end with a trailing
/. - Indentation uses blocks of 4 characters: either a guide block or spaces. Guide blocks are
│(Unicode) or|(ASCII). Spaces are. - Connectors are
├──(middle) and└──(last) in Unicode mode, or|--(middle) and\--(last) in ASCII mode. - The parser accepts both Unicode and ASCII symbols and is tolerant of some legacy files that contain replacement characters.
A minimal example of a saved tree (tree.txt):
my_project/
├── src/
│ └── main.py
└── tests/
└── test_main.py
Recreate it under ./output:
python .\src\dir_gen.py .\tree.txt .\output
- Module form (no install required when running from repo):
python -m skleton_tree tree . -L 3 --filespython -m skleton_tree dir .\tree.txt . --dry-run
- Console script (after install):
skleton-tree tree . -L 3 --filesskleton-tree dir .\tree.txt . --dry-run
The legacy script paths also work:
python .\src\tree_gen.py ...python .\src\dir_gen.py ...
- Install (editable with dev extras):
- Create venv:
python -m venv .venv - Activate (PowerShell):
& .venv\Scripts\Activate.ps1 - Install:
pip install -e .[dev]
- Create venv:
- Format: black
- Tests: pytest (a helper script
tools/pc_pytest.pyruns pytest only if tests exist)
Run tests (PowerShell):
python .\tools\pc_pytest.py- or
pytest -q
- Bump version in
pyproject.toml([project].version). Current:0.2.0. - Build sdist and wheel:
python -m build
- Upload to TestPyPI:
python -m twine upload -r testpypi dist/*- Install from TestPyPI to verify:
pip install -i https://test.pypi.org/simple/ skleton-tree
- Upload to PyPI (when satisfied):
python -m twine upload dist/*
- Code: MIT License (see LICENSE)
- Documentation: CC BY 4.0 (see LICENSE.docs)
Copyright (c) 2025 João Soares