From a594bb3832fe238db039b5340a1576e1bba31f33 Mon Sep 17 00:00:00 2001
From: sneak <sneak@sneak.berlin>
Date: Sun, 4 Oct 2026 14:36:03 +0000
Subject: [PATCH] Move FORMAT.md to docs/ and contrib/ to bin/, fix bash script
 style (closes #74)

FORMAT.md moves to docs/ and every reference follows; its two relative
links to mfer/mf.proto now point up one directory, its text is otherwise
unchanged. contrib/usage.sh moves to bin/, not docs/: it is a script you
run (it builds mfer, then generates and checks a manifest of the repo),
not reading material. Both scripts now use #!/usr/bin/env bash,
set -euo pipefail and a main function. bin/gitrev.sh still exits non-zero
outside a git checkout, so the Makefile still falls back to unknown.
.gitignore now ignores only the built bin/mfer rather than all of bin/,
which holds tracked scripts.

Model: opus-5-5
---
 .gitignore                  |  2 +-
 AGENTS.md                   |  2 +-
 README.md                   |  2 +-
 bin/gitrev.sh               | 19 ++++++++++++-------
 bin/usage.sh                | 23 +++++++++++++++++++++++
 contrib/usage.sh            | 19 -------------------
 FORMAT.md => docs/FORMAT.md |  4 ++--
 7 files changed, 40 insertions(+), 31 deletions(-)
 create mode 100755 bin/usage.sh
 delete mode 100755 contrib/usage.sh
 rename FORMAT.md => docs/FORMAT.md (98%)

diff --git a/.gitignore b/.gitignore
index 9f07cc8..94cf6c9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,4 @@
-/bin/
+/bin/mfer
 /tmp
 /node_modules/
 *.tmp
diff --git a/AGENTS.md b/AGENTS.md
index bea12f1..5ff361e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -26,7 +26,7 @@ source for coding standards, formatting, linting, and workflow rules.
 - This is a Go library + CLI tool for generating `.mf` manifest files.
 - The proto definition is in `mfer/mf.proto`; generated `.pb.go` files are
   committed (required for `go get` compatibility).
-- The format specification is in `FORMAT.md`.
+- The format specification is in `docs/FORMAT.md`.
 - Open work, open design questions included, is tracked only in the repo's
   issues: https://git.eeqj.de/sneak/mfer/issues. There is no `TODO.md` and no
   TODO list in `README.md`; do not add either. For this repo this overrides the
diff --git a/README.md b/README.md
index 64c2c6e..edb1f46 100644
--- a/README.md
+++ b/README.md
@@ -242,7 +242,7 @@ are now tracked only in the [issues](https://git.eeqj.de/sneak/mfer/issues).
   as question 10 on [issue 82](https://git.eeqj.de/sneak/mfer/issues/82).
 
 - Should the on-disk serialization format be proto3 or json? Settled: it is
-  proto3, see `FORMAT.md` and `mfer/mf.proto`.
+  proto3, see `docs/FORMAT.md` and `mfer/mf.proto`.
 
 # Tool Examples
 
diff --git a/bin/gitrev.sh b/bin/gitrev.sh
index bc2d943..ab0821c 100644
--- a/bin/gitrev.sh
+++ b/bin/gitrev.sh
@@ -1,7 +1,12 @@
-#!/bin/bash
-#
-if [[ ! -z "$GITREV" ]]; then
-    echo $GITREV
-else
-    git describe --tags --always --dirty=-dirty
-fi
+#!/usr/bin/env bash
+set -euo pipefail
+
+main() {
+    if [[ -n "${GITREV:-}" ]]; then
+        echo "$GITREV"
+    else
+        git describe --tags --always --dirty=-dirty
+    fi
+}
+
+main "$@"
diff --git a/bin/usage.sh b/bin/usage.sh
new file mode 100755
index 0000000..0136715
--- /dev/null
+++ b/bin/usage.sh
@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# usage.sh - Generate and check a manifest from the repo
+# Run from repo root: bin/usage.sh
+
+cleanup() {
+    rm -rf "$TMPDIR"
+}
+
+main() {
+    TMPDIR=$(mktemp -d)
+    MANIFEST="$TMPDIR/index.mf"
+    trap cleanup EXIT
+
+    echo "Building mfer..."
+    go build -o "$TMPDIR/mfer" ./cmd/mfer
+
+    "$TMPDIR/mfer" generate -o "$MANIFEST" .
+    "$TMPDIR/mfer" check --base . "$MANIFEST"
+}
+
+main "$@"
diff --git a/contrib/usage.sh b/contrib/usage.sh
deleted file mode 100755
index fdda16a..0000000
--- a/contrib/usage.sh
+++ /dev/null
@@ -1,19 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-# usage.sh - Generate and check a manifest from the repo
-# Run from repo root: ./contrib/usage.sh
-
-TMPDIR=$(mktemp -d)
-MANIFEST="$TMPDIR/index.mf"
-
-cleanup() {
-    rm -rf "$TMPDIR"
-}
-trap cleanup EXIT
-
-echo "Building mfer..."
-go build -o "$TMPDIR/mfer" ./cmd/mfer
-
-"$TMPDIR/mfer" generate -o "$MANIFEST" .
-"$TMPDIR/mfer" check --base . "$MANIFEST"
diff --git a/FORMAT.md b/docs/FORMAT.md
similarity index 98%
rename from FORMAT.md
rename to docs/FORMAT.md
index e634a80..6ff067c 100644
--- a/FORMAT.md
+++ b/docs/FORMAT.md
@@ -19,7 +19,7 @@ An `.mf` file consists of two parts, concatenated:
 There is no length prefix or version byte between the magic and the protobuf
 message. The protobuf message extends to the end of the file.
 
-See [`mfer/mf.proto`](mfer/mf.proto) for exact field numbers and types.
+See [`mfer/mf.proto`](../mfer/mf.proto) for exact field numbers and types.
 
 ## Outer Message (`MFFileOuter`)
 
@@ -143,6 +143,6 @@ The recommended MIME type for `.mf` files is `application/octet-stream`. The
 
 ## Reference
 
-- Proto definition: [`mfer/mf.proto`](mfer/mf.proto)
+- Proto definition: [`mfer/mf.proto`](../mfer/mf.proto)
 - Reference implementation:
   [git.eeqj.de/sneak/mfer](https://git.eeqj.de/sneak/mfer)