Metadata-Version: 2.5
Name: treestamp
Version: 0.1.1
Summary: Generate and maintain directory trees for project documentation
Project-URL: Homepage, https://treestamp.reponomics.org
Project-URL: Documentation, https://github.com/reponomics/treestamp#readme
Project-URL: Repository, https://github.com/reponomics/treestamp
Project-URL: Issues, https://github.com/reponomics/treestamp/issues
Author: Reponomics
License-Expression: MIT
License-File: LICENSE
Keywords: ci,directory-tree,documentation,pre-commit,readme
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.11
Requires-Dist: textual<9,>=8.2.8
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: certifi>=2026.10.19; extra == 'dev'
Requires-Dist: mypy>=1.14; extra == 'dev'
Requires-Dist: pip>=26.2.2; extra == 'dev'
Requires-Dist: pre-commit>=4.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Requires-Dist: twine>=6; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">
    <picture>
        <img src="https://raw.githubusercontent.com/reponomics/treestamp/main/assets/TREESTAMP_BANNER.png" alt="treestamp banner">
    </picture>
</div>

# treestamp

Turn your repository into a directory tree for your README. Choose what to show, add short notes, and copy the result—from your terminal or browser.

## Quickstart

### 1. Generate a treestamp

**In your browser:** [Open the web editor](https://treestamp.reponomics.org/), enter a public GitHub repository URL, and choose **Load repo → Create treestamp**. Nothing to install.

**In your terminal:** Requires Python 3.11+ and Git. Until the first PyPI release, install from a checkout of this repository:

```bash
python -m pip install .
```

Then open the repository you want to document:

```bash
cd /path/to/your/project
treestamp
```

Choose **New document** and accept `.` for the repository root. The terminal editor uses staged files, so stage your source changes before opening it.

### 2. Edit the tree

Expand the useful parts, hide the noise, and add a note. Both editors show you the tree as you work.

**Terminal — hide, annotate, preview.**

![Terminal editor: hide a directory, annotate the entry point, and preview the finished tree.](https://raw.githubusercontent.com/reponomics/treestamp/main/assets/demos/terminal.gif)

**Web — click to edit, then copy the Markdown.**

![Web editor: expand source files, hide tooling, add a note, and copy the complete treestamp.](https://raw.githubusercontent.com/reponomics/treestamp/main/assets/demos/web.gif)

### 3. Add it to your README

Choose **Copy** in the terminal editor or **Copy treestamp** on the web, then paste into your README. The copied block already includes the Markdown fence and Treestamp markers—keep the whole block so you can reopen it later.

````markdown
<!-- treestamp:start -->
```sh
./
├── docs/ (2 files)
├── src/  # Application code
│   ├── app.py
│   ├── search.py
│   └── storage.py
├── LICENSE
└── README.md
```
<!-- treestamp:end -->
````

Hidden entries also produce a small configuration comment; keep that with the copied tree. The web editor exports to your clipboard and never writes to GitHub.

<details>
<summary>Write directly from the terminal editor</summary>

Add these empty markers to your README, starting in column one:

```html
<!-- treestamp:start -->
<!-- treestamp:end -->
```

Choose **Write to existing** in the terminal editor and enter `README.md`. Treestamp fills the region and preserves the surrounding text. **Write new file** creates a separate document instead.

</details>

## Check your README automatically

`treestamp check README.md` checks whether the tree matches the repository. It never writes to the document and exits with code `1` when the tree needs attention. Open the document in an editor to review it.

**GitHub Actions:** after checking out your repository and setting up Python 3.11+, add this step:

```yaml
- name: Check the README tree
  run: |
    python -m pip install "git+https://github.com/reponomics/treestamp.git@25722b884e29dd8a4ff65e22c782f4e11ea98922"
    treestamp check README.md
```

**Local pre-commit:** add this to `.pre-commit-config.yaml`, then run `pre-commit install`:

```yaml
repos:
  - repo: https://github.com/reponomics/treestamp
    rev: 25722b884e29dd8a4ff65e22c782f4e11ea98922
    hooks:
      - id: treestamp-check
```

Both examples pin a reviewed source revision until the first package release. Run the check for source changes too, not just changes to Markdown.

<details>
<summary>Snapshots, paths, and existing documents</summary>

Choose **Load document** in either editor to reopen a treestamped README. The terminal editor reads the selected local repository's Git index; the web editor reads a public GitHub repository's default-branch HEAD. Both keep a frozen snapshot for the editing session. A failed load keeps your accepted draft.

Document paths are relative to the selected repository root, even when displaying a subtree. The terminal accepts another checkout with `treestamp /path/to/repository`. Paths outside that repository, symlink document paths, and paths crossing into submodules are not supported. Treestamp never stages or commits files.

New trees start with immediate children and collapsed directories. Counts include hidden children. Symlinks and submodules appear as leaves. Choose Unicode, ASCII, or Markdown-list output in the editor. Annotations are single-line notes; unsupported filenames or annotations are rejected before output is written or copied.

Web snapshots are cached temporarily; load the repository again if one is no longer available. See [privacy](https://github.com/reponomics/treestamp/blob/main/PRIVACY.md).

</details>

<details>
<summary>Windows</summary>

Use a terminal and font that display Unicode tree characters, or choose ASCII output. Treestamp emits UTF-8; printed output uses LF line endings, while writing into an existing document preserves its line endings. Windows filesystem restrictions still apply. See [CONTRIBUTING](https://github.com/reponomics/treestamp/blob/main/.github/CONTRIBUTING.md) for development setup.

</details>

<details>
<summary>This repository's own treestamp</summary>

<!-- treestamp:start -->
<!-- treestamp:config
hidden = [".dockerignore", ".gitignore", ".pre-commit-config.yaml", ".pre-commit-hooks.yaml", ".python-version", "src/treestamp/__init__.py", "src/treestamp/__main__.py", "src/treestamp/py.typed"]
-->
```sh
./
├── .github/ (7 files, 2 folders)
├── assets/ (2 files, 1 folder)
├── scripts/ (6 files)  # Installed-package acceptance
├── src/
│   └── treestamp/  # Shared model and terminal editor
│       ├── cli.py
│       ├── codec.py
│       ├── document.py
│       ├── editor.py
│       ├── errors.py
│       ├── gitio.py
│       ├── maintenance.py
│       ├── model.py
│       ├── session.py
│       ├── sources.py
│       ├── tui.py
│       └── tui_dialogs.py
├── tests/ (16 files)  # Contract and integration tests
├── web/ (6 files, 3 folders)  # Hosted editor: a FastAPI adapter over the same package
├── .nvmrc
├── .tool-versions
├── CHANGELOG.md
├── LICENSE
├── MAINTENANCE.md
├── Makefile
├── PRIVACY.md
├── README.md
├── pyproject.toml
└── uv.lock
```
<!-- treestamp:end -->

</details>

## Development and support

[Contributing](https://github.com/reponomics/treestamp/blob/main/.github/CONTRIBUTING.md) · [Maintenance](https://github.com/reponomics/treestamp/blob/main/MAINTENANCE.md) · [Changelog](https://github.com/reponomics/treestamp/blob/main/CHANGELOG.md) · [Privacy](https://github.com/reponomics/treestamp/blob/main/PRIVACY.md)

Report bugs through [GitHub issues](https://github.com/reponomics/treestamp/issues), vulnerabilities through [private security reporting](https://github.com/reponomics/treestamp/security/advisories/new), and conduct concerns to [conduct@reponomics.org](mailto:conduct@reponomics.org).

[MIT licensed](https://github.com/reponomics/treestamp/blob/main/LICENSE). Before `1.0`, interfaces and the document format may change between releases.
