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. Install from PyPI:

python -m pip install treestamp

Then open the repository you want to document:

cd /path/to/your/project
treestamp

Or, run it directly with no installation:

pipx run 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.

To include an attribution footer, press t in the terminal editor or select Add “Maintained with treestamp” footer in the web editor's settings. This option is off by default. It adds Maintained with [treestamp](https://github.com/reponomics/treestamp) below the closing code fence (or below the Markdown list) and above <!-- treestamp:end -->. Loading or updating the document preserves the choice; toggle it off to remove the trailer.

<!-- 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 "treestamp==0.3.0"
    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: v0.3.0
    hooks:
      - id: treestamp-check

Both examples pin the latest release. Run the check for source changes too, not just changes to Markdown.

Project Structure

Maintained by treestamp.

./
├── .github/ (8 files, 2 folders)
├── assets/ (2 files, 1 folder)
├── docs/ (6 files)
├── 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/  # Hosted editor: a FastAPI adapter over the same package
│   ├── scripts/ (3 files)
│   ├── src/ (1 folder)
│   ├── tests/ (14 files, 2 folders)
│   ├── Dockerfile
│   ├── README.md
│   ├── fly.preview.toml
│   ├── fly.toml
│   ├── package.json
│   └── pyproject.toml
└── README.md

Development and support

Contributing · Maintenance · Governance · Design · Security assessment · Verifying releases · 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.