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
,--level
N: 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 --files
python -m skleton_tree dir .\tree.txt . --dry-run
- Console script (after install):
skleton-tree tree . -L 3 --files
skleton-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.py
runs 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