Skip to content

JDPS/skleton_tree

Repository files navigation

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

About

No description, website, or topics provided.

Resources

License

MIT, Unknown licenses found

Licenses found

MIT
LICENSE
Unknown
LICENSE.docs

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages