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.

Write directly from the terminal editor

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

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

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.

Snapshots, paths, and existing documents

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.

Windows

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 for development setup.

This repository's own treestamp

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