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, 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:

python -m pip install .

Then open the repository you want to document:

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.

Web — click to edit, then copy the Markdown.

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.

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

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

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:

- 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:

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.

./
├── .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

Development and support

Contributing · Maintenance · Changelog · Privacy

Report bugs through GitHub issues, vulnerabilities through private security reporting, and conduct concerns to conduct@reponomics.org.

MIT licensed. Before 1.0, interfaces and the document format may change between releases.