fsg 0.1.0__tar.gz

fsg-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+build/
+dist/
+*.egg-info/
+.idea/

fsg-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Hähnel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fsg-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.5
+Name: fsg
+Version: 0.1.0
+Summary: Generates clean directory trees that respect .gitignore and keep your docs up to date.
+Project-URL: Homepage, https://github.com/KarnesTH/fsg
+Project-URL: Issues, https://github.com/KarnesTH/fsg/issues
+Project-URL: Changelog, https://github.com/KarnesTH/fsg/blob/main/CHANGELOG.md
+Author: Patrick Hähnel
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,directory,documentation,gitignore,pre-commit,project-structure,readme,tree
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/logo.svg" alt="fsg logo" width="128" />
+</p>
+
+<h1 align="center">fsg</h1>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/version-0.1.0-blue" alt="Version 0.1.0" />
+  <img src="https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white" alt="Python 3.11+" />
+  <img src="https://img.shields.io/badge/dependencies-none-brightgreen" alt="No dependencies" />
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License" />
+</p>
+
+<p align="center">Generates clean directory trees that respect .gitignore and keep your docs up to date.</p>
+
+## Features
+
+- Inside a git repository, only files git tracks or would track are listed (`.gitignore` is respected)
+- Outside a repository, common generated and tool directories are skipped (`.venv`, `__pycache__`, `node_modules`, `target`, `.idea`, …)
+- Directories first, entries sorted case-insensitively, empty directories omitted
+- Keeps a marked section of your README up to date, with a check mode for CI
+- Sets up the commit hook for you: extends an existing `.pre-commit-config.yaml` or the native git hook, never overwrites
+- Limit the depth, render directories only or exclude entries by glob pattern
+- Options can live in `.fsg.toml` or `[tool.fsg]` in `pyproject.toml`
+- Output is wrapped in a `plaintext` code fence (optional) and always written as UTF-8
+- Optional ASCII branches (`|--`, `` `-- ``) for environments without Unicode support
+
+## Installation
+
+Requires Python 3.11+ and git (optional, for `.gitignore` support).
+
+```bash
+uv tool install fsg   # or: pipx install fsg
+uvx fsg               # run without installing
+```
+
+## Usage
+
+```bash
+fsg [options] [path]
+```
+
+| Argument                         | Description                                                                 |
+|----------------------------------|-----------------------------------------------------------------------------|
+| `path`                           | Directory to render (default: current directory)                            |
+| `-d N`, `--depth N`              | Render only the first N levels below the root                               |
+| `--dirs-only`, `--no-dirs-only`  | Render directories only                                                     |
+| `-e`, `--exclude PATTERN`        | Leave out entries whose name or relative path matches the glob (repeatable) |
+| `--fence`, `--no-fence`          | Wrap the tree in a Markdown code fence (default: on)                        |
+| `--ascii`, `--no-ascii`          | Draw the tree with ASCII instead of box-drawing characters                  |
+| `-u`, `--update FILE`            | Write the tree between the fsg markers of FILE                              |
+| `-c`, `--check FILE`             | Exit with status 1 when the tree in FILE is out of date                     |
+| `--setup-hook FILE`              | Run `fsg --update FILE` on every commit                                     |
+| `-h`, `--help`                   | Show the help text and exit                                                 |
+| `-V`, `--version`                | Show the version and exit                                                   |
+
+Example:
+
+```bash
+fsg src --depth 2
+```
+<!-- fsg:start -->
+```plaintext
+src/
+└── fsg/
+    ├── hooks/
+    ├── trees/
+    ├── __init__.py
+    ├── __main__.py
+    ├── cli.py
+    ├── config.py
+    ├── constants.py
+    └── readme_section.py
+```
+<!-- fsg:end -->
+
+## Configuration
+
+With `--update` and `--check`, the path and all options not given on the command line are read from `.fsg.toml`
+or the `[tool.fsg]` table in `pyproject.toml`, searched from the directory of the target file upwards.
+`path` is relative to the config file. Command line options take precedence, exclude patterns are combined.
+Plain `fsg` ignores the config.
+
+```toml
+[tool.fsg]
+path = "src"
+depth = 2
+dirs-only = false
+exclude = ["*.log", "docs/api"]
+fence = true
+ascii = false
+```
+
+## Keep your README up to date
+
+Add the markers where the tree should appear:
+
+```markdown
+<!-- fsg:start -->
+<!-- fsg:end -->
+```
+
+```bash
+fsg --update README.md       # writes the tree between the markers
+fsg --check README.md        # exit 1 if outdated, 2 if the file or markers are missing
+fsg --setup-hook README.md   # updates the tree on every commit
+```
+
+`--setup-hook` adds fsg to an existing `.pre-commit-config.yaml`. Without one, it adds a step to the git
+`pre-commit` hook that updates the tree and stops the commit so you can stage the change.
+
+### pre-commit
+
+To add the hook by hand:
+
+```yaml
+repos:
+  - repo: https://github.com/KarnesTH/fsg
+    rev: v0.1.0
+    hooks:
+      - id: fsg          # updates README.md
+      # - id: fsg-check  # only checks, e.g. in CI
+```
+
+Use `args` for another file, e.g. `args: [--update, docs/structure.md]`.
+
+## Development
+
+```bash
+git clone https://github.com/KarnesTH/fsg.git
+cd fsg
+uv sync
+uv run pytest
+```

fsg-0.1.0/README.md

@@ -0,0 +1,134 @@
+<p align="center">
+  <img src="assets/logo.svg" alt="fsg logo" width="128" />
+</p>
+
+<h1 align="center">fsg</h1>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/version-0.1.0-blue" alt="Version 0.1.0" />
+  <img src="https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white" alt="Python 3.11+" />
+  <img src="https://img.shields.io/badge/dependencies-none-brightgreen" alt="No dependencies" />
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License" />
+</p>
+
+<p align="center">Generates clean directory trees that respect .gitignore and keep your docs up to date.</p>
+
+## Features
+
+- Inside a git repository, only files git tracks or would track are listed (`.gitignore` is respected)
+- Outside a repository, common generated and tool directories are skipped (`.venv`, `__pycache__`, `node_modules`, `target`, `.idea`, …)
+- Directories first, entries sorted case-insensitively, empty directories omitted
+- Keeps a marked section of your README up to date, with a check mode for CI
+- Sets up the commit hook for you: extends an existing `.pre-commit-config.yaml` or the native git hook, never overwrites
+- Limit the depth, render directories only or exclude entries by glob pattern
+- Options can live in `.fsg.toml` or `[tool.fsg]` in `pyproject.toml`
+- Output is wrapped in a `plaintext` code fence (optional) and always written as UTF-8
+- Optional ASCII branches (`|--`, `` `-- ``) for environments without Unicode support
+
+## Installation
+
+Requires Python 3.11+ and git (optional, for `.gitignore` support).
+
+```bash
+uv tool install fsg   # or: pipx install fsg
+uvx fsg               # run without installing
+```
+
+## Usage
+
+```bash
+fsg [options] [path]
+```
+
+| Argument                         | Description                                                                 |
+|----------------------------------|-----------------------------------------------------------------------------|
+| `path`                           | Directory to render (default: current directory)                            |
+| `-d N`, `--depth N`              | Render only the first N levels below the root                               |
+| `--dirs-only`, `--no-dirs-only`  | Render directories only                                                     |
+| `-e`, `--exclude PATTERN`        | Leave out entries whose name or relative path matches the glob (repeatable) |
+| `--fence`, `--no-fence`          | Wrap the tree in a Markdown code fence (default: on)                        |
+| `--ascii`, `--no-ascii`          | Draw the tree with ASCII instead of box-drawing characters                  |
+| `-u`, `--update FILE`            | Write the tree between the fsg markers of FILE                              |
+| `-c`, `--check FILE`             | Exit with status 1 when the tree in FILE is out of date                     |
+| `--setup-hook FILE`              | Run `fsg --update FILE` on every commit                                     |
+| `-h`, `--help`                   | Show the help text and exit                                                 |
+| `-V`, `--version`                | Show the version and exit                                                   |
+
+Example:
+
+```bash
+fsg src --depth 2
+```
+<!-- fsg:start -->
+```plaintext
+src/
+└── fsg/
+    ├── hooks/
+    ├── trees/
+    ├── __init__.py
+    ├── __main__.py
+    ├── cli.py
+    ├── config.py
+    ├── constants.py
+    └── readme_section.py
+```
+<!-- fsg:end -->
+
+## Configuration
+
+With `--update` and `--check`, the path and all options not given on the command line are read from `.fsg.toml`
+or the `[tool.fsg]` table in `pyproject.toml`, searched from the directory of the target file upwards.
+`path` is relative to the config file. Command line options take precedence, exclude patterns are combined.
+Plain `fsg` ignores the config.
+
+```toml
+[tool.fsg]
+path = "src"
+depth = 2
+dirs-only = false
+exclude = ["*.log", "docs/api"]
+fence = true
+ascii = false
+```
+
+## Keep your README up to date
+
+Add the markers where the tree should appear:
+
+```markdown
+<!-- fsg:start -->
+<!-- fsg:end -->
+```
+
+```bash
+fsg --update README.md       # writes the tree between the markers
+fsg --check README.md        # exit 1 if outdated, 2 if the file or markers are missing
+fsg --setup-hook README.md   # updates the tree on every commit
+```
+
+`--setup-hook` adds fsg to an existing `.pre-commit-config.yaml`. Without one, it adds a step to the git
+`pre-commit` hook that updates the tree and stops the commit so you can stage the change.
+
+### pre-commit
+
+To add the hook by hand:
+
+```yaml
+repos:
+  - repo: https://github.com/KarnesTH/fsg
+    rev: v0.1.0
+    hooks:
+      - id: fsg          # updates README.md
+      # - id: fsg-check  # only checks, e.g. in CI
+```
+
+Use `args` for another file, e.g. `args: [--update, docs/structure.md]`.
+
+## Development
+
+```bash
+git clone https://github.com/KarnesTH/fsg.git
+cd fsg
+uv sync
+uv run pytest
+```

fsg-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "fsg"
+version = "0.1.0"
+description = "Generates clean directory trees that respect .gitignore and keep your docs up to date."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Patrick Hähnel" }]
+requires-python = ">=3.11"
+dependencies = []
+keywords = ["tree", "directory", "project-structure", "readme", "documentation", "gitignore", "pre-commit", "cli"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Documentation",
+    "Topic :: Software Development :: Documentation",
+    "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://github.com/KarnesTH/fsg"
+Issues = "https://github.com/KarnesTH/fsg/issues"
+Changelog = "https://github.com/KarnesTH/fsg/blob/main/CHANGELOG.md"
+
+[project.scripts]
+fsg = "fsg.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+]
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fsg"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "CHANGELOG.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.fsg]
+path = "src"
+depth = 2

fsg-0.1.0/src/fsg/__init__.py

@@ -0,0 +1,3 @@
+from fsg.trees import GitProjectTree, PlainProjectTree, ProjectTree
+
+__all__ = ["GitProjectTree", "PlainProjectTree", "ProjectTree"]

fsg-0.1.0/src/fsg/__main__.py

@@ -0,0 +1,4 @@
+from fsg.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

fsg-0.1.0/src/fsg/cli.py

@@ -0,0 +1,209 @@
+import argparse
+import io
+import subprocess
+import sys
+from importlib.metadata import version
+from pathlib import Path
+
+from fsg.config import Config
+from fsg.hooks import GitHook, Hook
+from fsg.readme_section import ReadmeSection
+from fsg.trees import ProjectTree
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    """Parses the command line arguments and returns the resulting namespace.
+
+    Boolean options are None when not given.
+    Exits with status 2 when --depth is smaller than 1.
+
+    Args:
+        argv: Argument list to parse instead of the command line arguments.
+    """
+
+    parser = argparse.ArgumentParser(
+        prog="fsg",
+        description="Generates clean directory trees that respect .gitignore and keep your docs up to date.",
+        epilog=(
+            "With --update or --check, the path and options not given on the command line are read from "
+            ".fsg.toml or [tool.fsg] in pyproject.toml, searched from the directory of FILE upwards."
+        ),
+    )
+    parser.add_argument(
+        "path",
+        nargs="?",
+        type=Path,
+        help="project directory to render (default: the configured path or the current directory)",
+    )
+    parser.add_argument(
+        "-d",
+        "--depth",
+        type=int,
+        metavar="N",
+        help="render only the first N levels below the root",
+    )
+    parser.add_argument(
+        "--dirs-only",
+        action=argparse.BooleanOptionalAction,
+        help="render directories only",
+    )
+    parser.add_argument(
+        "-e",
+        "--exclude",
+        action="append",
+        default=[],
+        metavar="PATTERN",
+        help="leave out entries whose name or relative path matches the glob pattern (repeatable)",
+    )
+    parser.add_argument(
+        "--fence",
+        action=argparse.BooleanOptionalAction,
+        help="wrap the tree in a Markdown code fence (default: on)",
+    )
+    parser.add_argument(
+        "--ascii",
+        action=argparse.BooleanOptionalAction,
+        dest="use_ascii",
+        help="draw the tree with ASCII characters instead of box-drawing characters",
+    )
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument(
+        "-u",
+        "--update",
+        type=Path,
+        metavar="FILE",
+        help="write the tree between the <!-- fsg:start --> and <!-- fsg:end --> markers of FILE",
+    )
+    mode.add_argument(
+        "-c",
+        "--check",
+        type=Path,
+        metavar="FILE",
+        help="exit with status 1 when the tree between the markers of FILE is out of date",
+    )
+    mode.add_argument(
+        "--setup-hook",
+        type=Path,
+        metavar="FILE",
+        help="add 'fsg --update FILE' to .pre-commit-config.yaml if present, otherwise to the git pre-commit hook",
+    )
+    parser.add_argument(
+        "-V",
+        "--version",
+        action="version",
+        version=f"%(prog)s {version('fsg')}",
+    )
+    args = parser.parse_args(argv)
+    if args.depth is not None and args.depth < 1:
+        parser.error("--depth must be at least 1")
+    return args
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Runs the mode selected by the arguments and returns the exit status.
+
+    Without a mode the tree is rendered from the arguments alone and written UTF-8 encoded to stdout.
+    With --update or --check the config found from the directory of the target file fills in the path
+    and every option not given. Returns 0 on success, 1 when the path is not a directory or --check finds
+    an outdated tree, and 2 when a file cannot be read, lacks the markers, the config is invalid or the
+    hook cannot be set up.
+
+    Args:
+        argv: Argument list to use instead of the command line arguments.
+    """
+
+    args = parse_args(argv)
+    for stream in (sys.stdout, sys.stderr):
+        if isinstance(stream, io.TextIOWrapper):
+            stream.reconfigure(encoding="utf-8")
+    if args.setup_hook:
+        return _setup_hook(args.setup_hook)
+    target = args.update or args.check
+    config = Config()
+    if target is not None:
+        try:
+            config = Config.find(target.resolve().parent)
+        except (OSError, ValueError) as error:
+            return _fail(str(error), 2)
+    root = args.path or config.path or Path(".")
+    if not root.is_dir():
+        return _fail(f"{root}: not a directory", 1)
+    output = ProjectTree.for_path(root, **config.merge(args)).render()
+    if target is None:
+        print(output)
+        return 0
+    return _sync(target, output, check=bool(args.check))
+
+
+def _sync(target: Path, output: str, check: bool) -> int:
+    """Compares or writes the tree in the marked section of the target and prints one status line.
+
+    Args:
+        target: File holding the markers.
+        output: Rendered tree.
+        check: Only compares when True, otherwise writes the tree.
+    """
+
+    try:
+        section = ReadmeSection(target)
+    except FileNotFoundError:
+        return _fail(f"{target}: file not found", 2)
+    except UnicodeDecodeError:
+        return _fail(f"{target}: not a UTF-8 text file", 2)
+    except (OSError, ValueError) as error:
+        return _fail(f"{target}: {getattr(error, 'strerror', None) or error}", 2)
+    if check:
+        if section.is_current(output):
+            print(f"{target}: tree is up to date")
+            return 0
+        print(f"{target}: tree is out of date, run fsg --update {target}", file=sys.stderr)
+        return 1
+    if section.update(output):
+        print(f"{target}: tree updated")
+    else:
+        print(f"{target}: tree already up to date")
+    return 0
+
+
+def _setup_hook(target: Path) -> int:
+    """Adds the update step for the target to the hooks of the repository around the current directory and prints the result.
+
+    Args:
+        target: File holding the markers, relative to the current directory.
+    """
+
+    repository = Hook.repository_root(Path.cwd())
+    if repository is None:
+        return _fail("not inside a git repository", 2)
+    try:
+        relative = target.resolve().relative_to(repository.resolve()).as_posix()
+    except ValueError:
+        return _fail(f"{target}: not inside the repository {repository}", 2)
+    hook = Hook.for_repository(repository, relative)
+    try:
+        location = hook.location()
+        added = hook.install()
+    except (OSError, ValueError, subprocess.CalledProcessError) as error:
+        return _fail(str(error), 2)
+    root = repository.resolve()
+    location = location.resolve()
+    shown = (location.relative_to(root) if location.is_relative_to(root) else location).as_posix()
+    if not added:
+        print(f"{shown}: fsg hook already present")
+    elif isinstance(hook, GitHook):
+        print(f"{shown}: fsg hook added")
+    else:
+        print(f"{shown}: fsg hook added, run 'pre-commit install' if not done yet")
+    return 0
+
+
+def _fail(message: str, status: int) -> int:
+    """Prints the message prefixed with fsg: to stderr and returns the status.
+
+    Args:
+        message: Error description.
+        status: Exit status to return.
+    """
+
+    print(f"fsg: {message}", file=sys.stderr)
+    return status