Skip to content

Latest commit

 

History

History
117 lines (94 loc) · 4.23 KB

README.md

File metadata and controls

117 lines (94 loc) · 4.23 KB

SPDX-FileCopyrightText: 2025 João Soares SPDX-License-Identifier: CC-BY-4.0

skleton-tree

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.

Requirements

  • Python 3.11+

Installation

You can run the scripts directly from the cloned repository; no installation is required.

Optional: create and activate a virtual environment first.

Usage

1) Generate a directory tree (tree_gen.py)

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.

2) Recreate a structure from a tree layout (dir_gen.py)

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 file
  • root (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.

Example

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

CLI Usage

  • 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 ...

Development

  • Install (editable with dev extras):
    • Create venv: python -m venv .venv
    • Activate (PowerShell): & .venv\Scripts\Activate.ps1
    • Install: pip install -e .[dev]
  • 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

Release

  • 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/*

License

  • Code: MIT License (see LICENSE)
  • Documentation: CC BY 4.0 (see LICENSE.docs)

Acknowledgements

Copyright (c) 2025 João Soares