Fallow

Fallow is a terminal command that makes a project directory read-only for a chosen number of seasons, refuses to let you work in it until the next English quarter day, and keeps a plain field book in your home directory that says what really happened while it rested. It changes nothing but permission bits and its own book: no file is deleted, moved, copied or rewritten, and reading, cat and git log keep working. You can leave at any time with --trespass or a plain chmod; the book then writes down, in plain words, what was found. Its input is a real directory you own, the modes and modification times your file system already keeps, and your machine's own calendar.

Run it

Go 1.22 or later, Linux or macOS, no dependencies.

CGO_ENABLED=0 go build -o fallow .
./fallow rest ~/side-project --seasons 2
./fallow plough ~/side-project
./fallow plough ~/side-project --trespass
./fallow status
./fallow status ~/side-project

A season is three calendar months. A field may be ploughed on the first quarter day (25 Mar, 24 Jun, 29 Sep, 25 Dec) on or after N seasons from the day it was rested. --seasons is required, from 1 to 40. fallow status prints the field book: a heading with the seal of the last entry, a table with the columns FIELD, RESTED, SEASONS, PLOUGH FROM, STATE and CROP, and for each resting field what the file system shows since the rest. fallow status DIR reads one directory and writes nothing; a copy made with cp -a, tar or rsync -a is recognised by the locked modes it carries.

Exit status is 0 when done, 1 when refused (one sentence on stderr, ending "Nothing was changed."), 2 for a usage error. FALLOW_TODAY=YYYY-MM-DD replaces today's date for testing, never a modification time, and every command says so on stderr.

Checks

go vet ./... && go test -v ./...   # the date table, plan counts, row validation, the chain, plurals
bash test/e2e.sh                   # acceptance checks 2 to 7 and 9 on a real git repository, Linux
bash test/pane.sh                  # acceptance check 8 in a real tmux pane; writes out/pane-*.txt

Both scripts run in a throwaway HOME and never touch your own directories or book. test/shots.py renders the pane captures in out/ to shots/ with Playwright; it is a test aid, not part of the tool. BUILD.md lists every acceptance check with the command that ran it and what it printed.

The book

~/.fallow-book is plain UTF-8 text, opened only for appending, under an exclusive lock.

  1. The first line is a # comment, written once.
  2. Each entry starts with entry N, counting from 1, and runs to the next entry line.
  3. Its second line is after and the seal of the entry before it, or after - for entry 1.
  4. A seal is the first 12 hex digits of the SHA-256 of an entry's exact bytes.
  5. Other lines are key value: did, date, at, field, seasons, from, and counts.
  6. did is rested, ploughed or trespassed.
  7. A rested entry ends with manifest rows, MMMM path: the octal mode each locked entry had.
  8. A closing entry names the rest it closes with of, and freezes what was found in changed and writable.
  9. Change, delete or insert anything in an earlier entry and the next one no longer names it.
  10. You can recompute every seal by hand with sha256sum.

Ceilings

  1. One chmod undoes the lock. The book and the evidence are the point.
  2. Someone who changes a file and then puts its modification time back leaves no mark.
  3. The last entry of the book can only be checked against a seal somebody kept.
  4. Root is not bound by permissions; only the book will hold.
  5. A hard link to a file outside the field shares its permission bits.
  6. A field moved or copied while resting can be recognised by status DIR from the locked modes it carries, but cannot be ploughed under its new name. The match goes by modes alone, so a directory that merely shares a few locked modes shows a small m of a large k.
  7. The lock is promised to read commands such as git log. Nothing is promised about commands that write. With git 2.43, git status --short in a resting repository was observed to answer and exit 0, which is an observation, not a promise.
  8. The book holds one line per locked entry, so a field with tens of thousands of writable files writes as many lines on every rest. Fallow never compacts the book.

Colophon

Written in Go, standard library only. Tested on Linux in a borrowed home directory, on a copy of its own source. Dates are kept as calendar dates, so daylight saving has never moved a quarter day. The book is set in whatever monospace your terminal has. No field was ploughed before its day except where the book says so.

normal is dead

Files