fsg 0.1.0__py3-none-any.whl

fsg/__init__.py

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

fsg/__main__.py

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

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

fsg/config.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import argparse
+import tomllib
+from pathlib import Path
+from typing import Any
+
+CONFIG_FILE = ".fsg.toml"
+PYPROJECT_FILE = "pyproject.toml"
+
+
+class Config:
+    """Holds the render options read from a .fsg.toml file or the [tool.fsg] table of a pyproject.toml."""
+
+    def __init__(self, values: dict[str, Any] | None = None, source: Path | None = None) -> None:
+        """Validates and stores the option values together with the file they were read from.
+
+        Args:
+            values: Option table with the keys path, depth, dirs-only, exclude, fence and ascii.
+            source: File the values were read from, or None when no config file was found.
+
+        Raises:
+            ValueError: A key is unknown or a value has the wrong type.
+        """
+
+        self.source = source
+        self.path: Path | None = None
+        self.depth: int | None = None
+        self.dirs_only: bool | None = None
+        self.exclude: list[str] = []
+        self.fence: bool | None = None
+        self.use_ascii: bool | None = None
+        for key, value in (values or {}).items():
+            self._set(key, value)
+
+    @classmethod
+    def find(cls, start: Path) -> Config:
+        """Searches the start directory and its parents for a .fsg.toml or a pyproject.toml with a [tool.fsg] table.
+
+        The first directory containing either file wins; inside one directory .fsg.toml takes precedence.
+        Returns an empty Config when nothing is found.
+
+        Args:
+            start: Directory the search begins in.
+
+        Raises:
+            ValueError: A config file is not valid TOML or holds invalid options.
+        """
+
+        start = Path(start).resolve()
+        for directory in (start, *start.parents):
+            config_file = directory / CONFIG_FILE
+            if config_file.is_file():
+                return cls(cls._load(config_file), config_file)
+            pyproject = directory / PYPROJECT_FILE
+            if pyproject.is_file():
+                table = cls._load(pyproject).get("tool", {}).get("fsg")
+                if table is not None:
+                    return cls(table, pyproject)
+        return cls()
+
+    def merge(self, args: argparse.Namespace) -> dict[str, Any]:
+        """Returns the ProjectTree options, taking each value from the arguments when given, else from the config, else the default.
+
+        Exclude patterns from the config and the arguments are combined.
+
+        Args:
+            args: Parsed command line arguments holding depth, dirs_only, exclude, fence and use_ascii.
+        """
+
+        return {
+            "depth": args.depth if args.depth is not None else self.depth,
+            "dirs_only": self._pick(args.dirs_only, self.dirs_only, False),
+            "exclude": [*self.exclude, *args.exclude],
+            "fence": self._pick(args.fence, self.fence, True),
+            "use_ascii": self._pick(args.use_ascii, self.use_ascii, False),
+        }
+
+    @staticmethod
+    def _pick(argument: bool | None, configured: bool | None, default: bool) -> bool:
+        """Returns the argument value when set, otherwise the configured value when set, otherwise the default.
+
+        Args:
+            argument: Value from the command line, or None.
+            configured: Value from the config file, or None.
+            default: Value used when neither is set.
+        """
+
+        if argument is not None:
+            return argument
+        if configured is not None:
+            return configured
+        return default
+
+    @staticmethod
+    def _load(path: Path) -> dict[str, Any]:
+        """Parses a TOML file and returns its top-level table.
+
+        Args:
+            path: File to parse.
+
+        Raises:
+            ValueError: The file is not valid TOML.
+        """
+
+        try:
+            with path.open("rb") as file:
+                return tomllib.load(file)
+        except tomllib.TOMLDecodeError as error:
+            raise ValueError(f"{path}: invalid TOML: {error}") from None
+
+    def _set(self, key: str, value: Any) -> None:
+        """Checks the type of one option value and stores it on the matching attribute.
+
+        A path is resolved against the directory of the config file.
+
+        Args:
+            key: Option name as written in the config file.
+            value: Parsed TOML value.
+
+        Raises:
+            ValueError: The key is unknown or the value has the wrong type.
+        """
+
+        if key == "path":
+            if not isinstance(value, str):
+                raise ValueError(f"{self.source}: path must be a string")
+            self.path = self.source.parent / value if self.source else Path(value)
+        elif key == "depth":
+            if not isinstance(value, int) or isinstance(value, bool) or value < 1:
+                raise ValueError(f"{self.source}: depth must be an integer of at least 1")
+            self.depth = value
+        elif key in ("dirs-only", "fence", "ascii"):
+            if not isinstance(value, bool):
+                raise ValueError(f"{self.source}: {key} must be true or false")
+            setattr(self, {"dirs-only": "dirs_only", "ascii": "use_ascii"}.get(key, key), value)
+        elif key == "exclude":
+            if not isinstance(value, list) or not all(isinstance(pattern, str) for pattern in value):
+                raise ValueError(f"{self.source}: exclude must be a list of strings")
+            self.exclude = list(value)
+        else:
+            raise ValueError(f"{self.source}: unknown option '{key}'")

fsg/constants.py

@@ -0,0 +1,13 @@
+UNICODE_GLYPHS = {"branch": "├── ", "last": "└── ", "pipe": "│   ", "space": "    "}
+ASCII_GLYPHS = {"branch": "|-- ", "last": "`-- ", "pipe": "|   ", "space": "    "}
+
+IGNORED = {
+    ".git", ".svn", ".hg",
+    ".idea", ".vscode",
+    "__pycache__", ".mypy_cache", ".pytest_cache", ".ruff_cache",
+    ".venv", "venv", "env",
+    "node_modules", "target", "dist", "build", "out",
+    ".godot", ".import",
+    ".DS_Store", "Thumbs.db",
+    "uv.lock",
+}

fsg/hooks/__init__.py

@@ -0,0 +1,5 @@
+from fsg.hooks.git_hook import GitHook
+from fsg.hooks.hook import Hook
+from fsg.hooks.pre_commit_hook import PreCommitHook
+
+__all__ = ["GitHook", "Hook", "PreCommitHook"]

fsg/hooks/git_hook.py

@@ -0,0 +1,69 @@
+import shlex
+import subprocess
+from pathlib import Path
+
+from fsg.hooks.hook import Hook
+
+MARKER = "# fsg: keep the directory tree up to date"
+
+
+class GitHook(Hook):
+    """Writes the fsg step into the native pre-commit hook script of the repository."""
+
+    def location(self) -> Path:
+        """Returns the pre-commit script inside the hooks directory git reports, honouring core.hooksPath."""
+
+        result = subprocess.run(
+            ["git", "rev-parse", "--git-path", "hooks"],
+            cwd=self.repository,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            check=True,
+        )
+        hooks = Path(result.stdout.strip())
+        if not hooks.is_absolute():
+            hooks = self.repository / hooks
+        return hooks / "pre-commit"
+
+    def install(self) -> bool:
+        """Creates the executable script or adds the fsg step to the existing one.
+
+        In an existing script the step goes before a final exit line, otherwise at the end.
+        Returns False without writing when the script already contains the fsg step.
+        """
+
+        path = self.location()
+        if not path.exists():
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text("#!/bin/sh\n" + self._step(), encoding="utf-8", newline="\n")
+            path.chmod(0o755)
+            return True
+        lines = path.read_text(encoding="utf-8").splitlines(keepends=True)
+        if any(line.strip() == MARKER for line in lines):
+            return False
+        position = len(lines)
+        content = [index for index, line in enumerate(lines) if line.strip() and not line.lstrip().startswith("#")]
+        if content and lines[content[-1]].split()[0] == "exit":
+            position = content[-1]
+        if lines and not lines[-1].endswith("\n"):
+            lines[-1] += "\n"
+        lines.insert(position, self._step())
+        path.write_text("".join(lines), encoding="utf-8", newline="\n")
+        return True
+
+    def _step(self) -> str:
+        """Returns the shell block that updates the target and aborts the commit when the tree was outdated, or shows the error when the check fails otherwise."""
+
+        target = shlex.quote(self.target)
+        return (
+            f"{MARKER}\n"
+            "if command -v fsg >/dev/null 2>&1; then\n"
+            f"  fsg --check {target} >/dev/null 2>&1\n"
+            "  case $? in\n"
+            "    0) ;;\n"
+            f"    1) fsg --update {target}; echo \"fsg: add {self.target} and commit again\"; exit 1 ;;\n"
+            f"    *) fsg --check {target}; exit 1 ;;\n"
+            "  esac\n"
+            "fi\n"
+        )

fsg/hooks/hook.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+PRE_COMMIT_CONFIG = ".pre-commit-config.yaml"
+
+
+class Hook:
+    """Adds the fsg update step for one target file to the commit hooks of a git repository."""
+
+    def __init__(self, repository: Path, target: str) -> None:
+        """Stores the repository root and the target file path relative to it.
+
+        Args:
+            repository: Root directory of the git working tree.
+            target: Path of the file holding the markers, relative to the repository root, using forward slashes.
+        """
+
+        self.repository = Path(repository)
+        self.target = target
+
+    @staticmethod
+    def repository_root(start: Path) -> Path | None:
+        """Returns the root of the git working tree containing the start directory, or None outside a repository.
+
+        Args:
+            start: Directory to start from.
+        """
+
+        try:
+            result = subprocess.run(
+                ["git", "rev-parse", "--show-toplevel"],
+                cwd=start,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                check=False,
+            )
+        except (FileNotFoundError, NotADirectoryError):
+            return None
+        if result.returncode != 0:
+            return None
+        return Path(result.stdout.strip())
+
+    @classmethod
+    def for_repository(cls, repository: Path, target: str) -> Hook:
+        """Returns a PreCommitHook when the repository root holds a .pre-commit-config.yaml, otherwise a GitHook.
+
+        Args:
+            repository: Root directory of the git working tree.
+            target: Path of the file holding the markers, relative to the repository root, using forward slashes.
+        """
+
+        from fsg.hooks.git_hook import GitHook
+        from fsg.hooks.pre_commit_hook import PreCommitHook
+
+        if (Path(repository) / PRE_COMMIT_CONFIG).is_file():
+            return PreCommitHook(repository, target)
+        return GitHook(repository, target)
+
+    def location(self) -> Path:
+        """Returns the file the hook is written to."""
+
+        raise NotImplementedError
+
+    def install(self) -> bool:
+        """Adds the fsg step to the hook file and returns False when it is already present."""
+
+        raise NotImplementedError

fsg/hooks/pre_commit_hook.py

@@ -0,0 +1,74 @@
+import json
+import re
+from importlib.metadata import version
+from pathlib import Path
+
+from fsg.hooks.hook import PRE_COMMIT_CONFIG, Hook
+
+REPOSITORY_URL = "https://github.com/KarnesTH/fsg"
+
+
+class PreCommitHook(Hook):
+    """Appends the fsg repository entry to the repos list of an existing .pre-commit-config.yaml."""
+
+    def location(self) -> Path:
+        """Returns the .pre-commit-config.yaml in the repository root."""
+
+        return self.repository / PRE_COMMIT_CONFIG
+
+    def install(self) -> bool:
+        """Inserts the fsg entry after the last line of the repos block, keeping every other line unchanged.
+
+        The entry uses the indentation of the first existing list item and the line endings of the file.
+        Returns False without writing when the file already references the fsg repository.
+
+        Raises:
+            ValueError: The file has no block-style repos key at the top level.
+        """
+
+        path = self.location()
+        with path.open(encoding="utf-8", newline="") as file:
+            text = file.read()
+        if "karnesth/fsg" in text.lower():
+            return False
+        newline = "\r\n" if "\r\n" in text else "\n"
+        lines = text.splitlines(keepends=True)
+        start = next((index for index, line in enumerate(lines) if line.rstrip() == "repos:"), None)
+        if start is None:
+            raise ValueError(f"{path}: no 'repos:' block found, add the fsg hook manually")
+        last = start
+        indent = None
+        for index in range(start + 1, len(lines)):
+            line = lines[index]
+            stripped = line.strip()
+            if not stripped or stripped.startswith("#"):
+                continue
+            if not line[0].isspace() and not stripped.startswith("-"):
+                break
+            if indent is None and stripped.startswith("-"):
+                indent = line[: len(line) - len(line.lstrip())]
+            last = index
+        if not lines[last].endswith(("\n", "\r")):
+            lines[last] += newline
+        lines.insert(last + 1, self._entry(indent if indent is not None else "  ", newline))
+        with path.open("w", encoding="utf-8", newline="") as file:
+            file.write("".join(lines))
+        return True
+
+    def _entry(self, indent: str, newline: str) -> str:
+        """Returns the repos list item for fsg, pinned to the installed version.
+
+        Args:
+            indent: Whitespace placed before the list dash.
+            newline: Line break sequence of the file.
+        """
+
+        target = self.target if re.fullmatch(r"[\w./-]+", self.target) else json.dumps(self.target)
+        lines = [
+            f"{indent}- repo: {REPOSITORY_URL}",
+            f"{indent}  rev: v{version('fsg')}",
+            f"{indent}  hooks:",
+            f"{indent}    - id: fsg",
+            f"{indent}      args: [--update, {target}]",
+        ]
+        return newline.join(lines) + newline

fsg/readme_section.py

@@ -0,0 +1,89 @@
+from pathlib import Path
+
+START_MARKER = "<!-- fsg:start -->"
+END_MARKER = "<!-- fsg:end -->"
+
+
+class ReadmeSection:
+    """Reads, compares and replaces the block between the fsg markers of a text file."""
+
+    def __init__(self, path: Path) -> None:
+        """Reads the file without newline translation and locates the block between the start and end marker.
+
+        The start marker counts only on a line of its own outside a fenced code block;
+        the end marker is the first one following it.
+
+        Args:
+            path: Path of the file holding the markers.
+
+        Raises:
+            FileNotFoundError: The file does not exist.
+            ValueError: A marker is missing or the end marker precedes the start marker.
+        """
+
+        self.path = Path(path)
+        with self.path.open(encoding="utf-8", newline="") as file:
+            self.text = file.read()
+        self.newline = "\r\n" if "\r\n" in self.text else "\n"
+        start = self._find_start()
+        end = self.text.find(END_MARKER, start + len(START_MARKER)) if start != -1 else -1
+        if start == -1 or end == -1:
+            raise ValueError(f"missing {START_MARKER} / {END_MARKER} markers")
+        self.inner_start = start + len(START_MARKER)
+        self.inner_end = end
+
+    def content(self) -> str:
+        """Returns the text between the markers."""
+
+        return self.text[self.inner_start:self.inner_end]
+
+    def is_current(self, tree: str) -> bool:
+        """Returns whether the block between the markers equals the tree on its own lines.
+
+        Args:
+            tree: Rendered tree, using \\n line breaks.
+        """
+
+        return self.content() == self._block(tree)
+
+    def update(self, tree: str) -> bool:
+        """Writes the tree between the markers when it differs, keeping the rest of the file, and returns whether the file was changed.
+
+        Args:
+            tree: Rendered tree, using \\n line breaks.
+        """
+
+        block = self._block(tree)
+        if self.content() == block:
+            return False
+        self.text = self.text[:self.inner_start] + block + self.text[self.inner_end:]
+        self.inner_end = self.inner_start + len(block)
+        with self.path.open("w", encoding="utf-8", newline="") as file:
+            file.write(self.text)
+        return True
+
+    def _find_start(self) -> int:
+        """Returns the offset of the first start marker standing alone on a line outside a fenced code block, or -1."""
+
+        offset = 0
+        fence = ""
+        for line in self.text.splitlines(keepends=True):
+            stripped = line.strip()
+            if fence:
+                if stripped.startswith(fence):
+                    fence = ""
+            elif stripped.startswith(("```", "~~~")):
+                fence = stripped[:3]
+            elif stripped == START_MARKER:
+                return offset + line.index(START_MARKER)
+            offset += len(line)
+        return -1
+
+    def _block(self, tree: str) -> str:
+        """Returns the tree surrounded by line breaks, using the newline style of the file.
+
+        Args:
+            tree: Rendered tree, using \\n line breaks.
+        """
+
+        return self.newline + tree.replace("\n", self.newline) + self.newline

fsg/trees/__init__.py

@@ -0,0 +1,5 @@
+from fsg.trees.git_project_tree import GitProjectTree
+from fsg.trees.plain_project_tree import PlainProjectTree
+from fsg.trees.project_tree import ProjectTree
+
+__all__ = ["GitProjectTree", "PlainProjectTree", "ProjectTree"]

fsg/trees/git_project_tree.py

@@ -0,0 +1,44 @@
+import subprocess
+from pathlib import Path
+
+from fsg.trees.project_tree import ProjectTree
+
+
+class GitProjectTree(ProjectTree):
+    """Collects the paths git reports as tracked or untracked but not ignored."""
+
+    @staticmethod
+    def is_repository(root: Path) -> bool:
+        """Returns whether the given path lies inside the working tree of a git repository.
+
+        Args:
+            root: Path to check.
+        """
+
+        try:
+            result = subprocess.run(
+                ["git", "rev-parse", "--is-inside-work-tree"],
+                cwd=root,
+                capture_output=True,
+                text=True,
+            encoding="utf-8",
+                check=False,
+            )
+        except (FileNotFoundError, NotADirectoryError):
+            return False
+        return result.returncode == 0 and result.stdout.strip() == "true"
+
+    def collect(self) -> list[list[str]]:
+        """Returns the paths listed by git ls-files, split into their path parts."""
+
+        result = subprocess.run(
+            ["git", "ls-files", "--cached", "--others", "--exclude-standard", "-z"],
+            cwd=self.root,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            check=False,
+        )
+        if result.returncode != 0:
+            return []
+        return [entry.split("/") for entry in result.stdout.split("\0") if entry]

fsg/trees/plain_project_tree.py

@@ -0,0 +1,34 @@
+from collections.abc import Iterator
+from pathlib import Path
+
+from fsg.constants import IGNORED
+from fsg.trees.project_tree import ProjectTree
+
+
+class PlainProjectTree(ProjectTree):
+    """Collects the paths by walking the directory, skipping well-known generated entries."""
+
+    def collect(self) -> list[list[str]]:
+        """Returns the paths found below the root, split into their path parts."""
+
+        return list(self._walk(self.root, []))
+
+    def _walk(self, directory: Path, parts: list[str]) -> Iterator[list[str]]:
+        """Yields the path parts of every entry below a directory, recursing into subdirectories.
+
+        Args:
+            directory: Directory to list.
+            parts: Path parts of that directory relative to the root.
+        """
+
+        try:
+            children = list(directory.iterdir())
+        except OSError:
+            return
+        for child in sorted(children, key=lambda path: path.name.lower()):
+            if child.name in IGNORED:
+                continue
+            if child.is_dir() and not child.is_symlink():
+                yield from self._walk(child, parts + [child.name])
+            else:
+                yield parts + [child.name]

fsg/trees/project_tree.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+from fnmatch import fnmatchcase
+from pathlib import Path
+from typing import Any
+
+from fsg.constants import ASCII_GLYPHS, IGNORED, UNICODE_GLYPHS
+
+
+class ProjectTree:
+    """Collects the relevant paths of a project directory and renders them as a tree."""
+
+    def __init__(
+        self,
+        root: Path,
+        *,
+        use_ascii: bool = False,
+        depth: int | None = None,
+        dirs_only: bool = False,
+        exclude: Iterable[str] = (),
+        fence: bool = True,
+    ) -> None:
+        """Resolves and stores the root directory of the project together with the render options.
+
+        Args:
+            root: Path of the directory to render.
+            use_ascii: Draws the branches with ASCII characters instead of box-drawing characters.
+            depth: Number of levels below the root to render, or None for all levels.
+            dirs_only: Renders directories only and leaves out files.
+            exclude: Glob patterns matched case-sensitively against every path part and every relative path prefix.
+            fence: Wraps the rendered tree in a Markdown code fence.
+        """
+
+        self.root = Path(root).resolve()
+        self.glyphs = ASCII_GLYPHS if use_ascii else UNICODE_GLYPHS
+        self.depth = depth
+        self.dirs_only = dirs_only
+        self.exclude = tuple(exclude)
+        self.fence = fence
+
+    @classmethod
+    def for_path(cls, root: Path, **options: Any) -> ProjectTree:
+        """Returns a GitProjectTree when the path lies inside a working git repository, otherwise a PlainProjectTree.
+
+        Args:
+            root: Path of the directory to render.
+            **options: Render options passed on to the constructor.
+        """
+
+        from fsg.trees.git_project_tree import GitProjectTree
+        from fsg.trees.plain_project_tree import PlainProjectTree
+
+        if GitProjectTree.is_repository(root):
+            return GitProjectTree(root, **options)
+        return PlainProjectTree(root, **options)
+
+    def collect(self) -> list[list[str]]:
+        """Returns the relative paths to render, as lists of path parts."""
+
+        raise NotImplementedError
+
+    def render(self) -> str:
+        """Returns the tree as one string, wrapped in a Markdown code fence unless fence is disabled."""
+
+        body = "\n".join([f"{self.root.name}/", *self._lines(self._nodes(), "", 1)])
+        return f"```plaintext\n{body}\n```" if self.fence else body
+
+    def _nodes(self) -> dict[str, dict]:
+        """Turns the collected paths into nested dicts, dropping paths that contain an ignored or excluded part."""
+
+        tree: dict[str, dict] = {}
+        for parts in self.collect():
+            if any(part in IGNORED for part in parts) or self._is_excluded(parts):
+                continue
+            current = tree
+            for part in parts:
+                current = current.setdefault(part, {})
+        return tree
+
+    def _is_excluded(self, parts: list[str]) -> bool:
+        """Returns whether any part name or any slash-joined prefix of the parts matches an exclude pattern.
+
+        Args:
+            parts: Path parts relative to the root.
+        """
+
+        for index, part in enumerate(parts):
+            prefix = "/".join(parts[: index + 1])
+            if any(fnmatchcase(part, pattern) or fnmatchcase(prefix, pattern) for pattern in self.exclude):
+                return True
+        return False
+
+    def _lines(self, nodes: dict[str, dict], prefix: str, level: int) -> Iterator[str]:
+        """Yields the rendered lines for one level of the node tree and recurses into its children up to the depth limit.
+
+        Args:
+            nodes: Mapping of entry name to its child nodes.
+            prefix: Indentation string carried over from the parent levels.
+            level: Level of the given nodes below the root, starting at 1.
+        """
+
+        entries = sorted(nodes.items(), key=lambda item: (not item[1], item[0].lower()))
+        if self.dirs_only:
+            entries = [entry for entry in entries if entry[1]]
+        for index, (name, children) in enumerate(entries):
+            is_last = index == len(entries) - 1
+            connector = self.glyphs["last"] if is_last else self.glyphs["branch"]
+            yield f"{prefix}{connector}{name}{'/' if children else ''}"
+            if children and (self.depth is None or level < self.depth):
+                indent = self.glyphs["space"] if is_last else self.glyphs["pipe"]
+                yield from self._lines(children, prefix + indent, level + 1)

fsg-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,19 @@
+fsg/__init__.py,sha256=nYbZZ7HZoQz6t_Qr11yC4IUP7cBtO2pWbKNl-qmkgFk,132
+fsg/__main__.py,sha256=_eJ4SF_a5rJg1-wBkNJ6Cj5TPZb8B5Njydkc3PGCRRQ,81
+fsg/cli.py,sha256=WZs1Uzp3E-r_sCzIgngamK65JIXox6usLiN1l3jOzQE,7117
+fsg/config.py,sha256=n8qYNNAjpv-p3S649vyH-8CIrF7IBTQZb8Of2Pz7L0M,5497
+fsg/constants.py,sha256=FFnpodbPpdQx-iTHN395_jQwVYTfG9tA1f7HwIGElTU,465
+fsg/readme_section.py,sha256=8qTAeztwGge810OGcmkb9uxDSnRa6QpKxLumSVCy8SU,3230
+fsg/hooks/__init__.py,sha256=JHMpjdSifTt6DRwmnhLUAQSWl0bs_U8qpvLKgO9zhCs,170
+fsg/hooks/git_hook.py,sha256=msc5vByfPXvdIxvs8Y-idyEclcIAZHabi0KnGMQ6UTg,2651
+fsg/hooks/hook.py,sha256=kDyNGUrwFDs2oVM1U1p3lmoHSGcHrRoOfD7e2PMpsF8,2327
+fsg/hooks/pre_commit_hook.py,sha256=tzfytfpLN3RfJiB8RqUq6l9YFUYoqgrB79fiH3GmuKg,2907
+fsg/trees/__init__.py,sha256=4gU-RkrKlerEQ2vorjM94B_aVVvALGTKH86sEBBhx0w,223
+fsg/trees/git_project_tree.py,sha256=chdO4jF2UaSAMCMeBDtCAfAaDorC0yB9WQICIHqaeCE,1389
+fsg/trees/plain_project_tree.py,sha256=0g4bnOwnveD93M9AvT78MFIAHhKPWi7Ebc2b9CkD1tI,1197
+fsg/trees/project_tree.py,sha256=SSiQDEOdizdA3tM16jeAmXrM8kAlntiLZ607Jf1lxRg,4593
+fsg-0.1.0.dist-info/METADATA,sha256=NZWQFeIK29Bu1nll7b61SH2yYFJH8LTALFT_bBIIUMk,6149
+fsg-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+fsg-0.1.0.dist-info/entry_points.txt,sha256=b1R-8lEHlcnmtcDyOVlNPbaUH5m9i3Jy3P2WvcQm0tM,37
+fsg-0.1.0.dist-info/licenses/LICENSE,sha256=6AwFjMZ0hf2E5qU0Bi302AM5K9Uq0gOlGhxFrqOe5dM,1071
+fsg-0.1.0.dist-info/RECORD,,

fsg-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

fsg-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fsg = fsg.cli:main

fsg-0.1.0.dist-info/licenses/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.