Port of Entry

A zsh hook quietly stamps a passport each time you enter a git repository, and once a month it prints the passport so you can see which projects you really worked in. The hook appends one line to a log whenever your shell enters a repository from outside it, prints nothing and starts no process; port list turns that log into a plain table of days per repository, and port pages prints an A6 passport: a cover with the stay limit, visa pages with one rubber stamp per repository, and a two-line machine-readable zone. The only input is that log, written by your own shell on the real clock as you work. Nothing is sampled, generated or estimated.

Install

From this folder, add the hook to your shell (zsh only):

echo "source $PWD/port.zsh" >> ~/.zshrc

Python 3 (standard library only) runs through uv. The PDF needs Chromium or Google Chrome; set $CHROME to its binary if it is not found under the usual names.

Commands

port list [YYYY-MM] [--as-of YYYY-MM-DD]          # the month as a table
port pages [YYYY-MM] [--as-of YYYY-MM-DD] [--out DIR]   # writes passport-YYYY-MM.html
port pages --pdf                                   # also writes passport-YYYY-MM.pdf

Without the hook loaded, the same commands run from this folder as uv run --no-project port.py list. The month defaults to the current one and the as-of date to today, or to the last day of a past month.

The log

One line per entry at $PORT_LOG, by default ${XDG_DATA_HOME:-~/.local/share}/port/log.tsv: the local time with its offset, a tab, the absolute path of the repository root.

2026-10-13T09:14:02+0300	/code/thing

Moving between folders inside one repository writes nothing. A repository at $HOME (a dotfiles repository) counts as outside every repository. Opening a terminal inside a repository counts as entering it, because sourcing the hook records the folder the shell starts in.

How days are counted

The unit is the git root, the nearest folder above you that holds a .git file or folder. The count is distinct local calendar days with at least one entry, so forty entries on one day are one day. The window is the 180 days ending on the as-of date, both ends included, and entries after the as-of date do not count. A root with 90 or more days in its window is Resident, a root with fewer is a visitor (visitor 71 of 90), and a Resident root that falls back below 90 is stamped again with RE-ENTRY. A line that cannot be read is never counted and never hidden: its line number is printed on the passport.

The first Resident box can appear no earlier than the 90th distinct day on which one repository was entered, so a new passport carries only stamps for its first three months or more.

Checks

uv run python -m unittest          # rules, HTML, and the hook in a real zsh
sh render.sh passport-2026-10.html # PDF, first visa page screenshot, page count

The qa/ folder holds the scripts used once on the build machine (screenshots, the real terminal session); BUILD.md records what they showed.

Colophon

Printed on cream, ruled in sage, set in whatever monospace the machine already has. The stamps are drawn by rule from a hash of the repository and the month, so a reprint lands every stamp where it landed before; only the line that says when the copy was printed changes.

Files