hyperframes/scripts/check-large-files.sh

#!/bin/sh
# Reject large binaries committed straight into the git pack instead of LFS.
#
# Why this exists: the repo's history carries hundreds of MB of binaries that
# should have been LFS — a 31 MB ONNX model, nested HDR-regression MP4s that
# dodged non-recursive .gitattributes globs, demo clips, scratch renders. Each
# was "noticed later and deleted," but a raw commit lives in history forever and
# every clone pays for it. This hook stops the next one at commit time.
#
# Rule: any staged file larger than $MAX_KB that is NOT routed through Git LFS
# fails the commit. Fix by either adding an LFS pattern in .gitattributes for
# that path/extension, or not committing the file (assets/, gitignore, etc.).
#
# Usage:
#   check-large-files.sh                 # default: check the staged file set
#   check-large-files.sh <file> [<file>] # explicit files (handy for testing)
#   check-large-files.sh --range <base> <head>  # files a commit range adds or changes (CI)
#
# The staged and range modes size the blob git stores, not the file on disk, so
# a file matching an LFS pattern but added without git-lfs installed is caught.
#
# We read the staged set ourselves rather than taking lefthook's {staged_files}
# expansion, which splits paths containing spaces into separate args.

set -u

MAX_KB="${HF_MAX_NONLFS_KB:-500}"

# staged (default): the index; range: what <head> adds over <base>; files: paths on disk.
MODE=staged
RANGE_BASE=""
RANGE_HEAD=""
if [ "${1:-}" = "--range" ]; then
  [ "$#" -eq 3 ] || { echo "usage: $0 --range <base> <head>" >&2; exit 2; }
  MODE=range
  RANGE_BASE="$2"
  RANGE_HEAD="$3"
  shift 3
elif [ "$#" -gt 0 ]; then
  MODE=files
fi
# Git modes name paths from the repository root; files mode keeps the caller's paths.
if [ "$MODE" != files ]; then
  cd "$(git rev-parse --show-toplevel)" || { echo "ERROR: not inside a git repository." >&2; exit 2; }
fi

# Emit a "<raw diff header>" record then a path record per entry, NUL-separated and
# unquoted. The header carries the new mode and blob id, so blobs are read by id,
# never by a path git could parse as revision syntax. Renames count as additions.
list_files() {
  case "$MODE" in
    range) git diff -z --raw --no-abbrev --no-renames --diff-filter=ACMT "$RANGE_BASE" "$RANGE_HEAD" ;;
    staged) git diff -z --raw --no-abbrev --no-renames --diff-filter=ACMT --cached ;;
    files) for f in "$@"; do printf 'file\0%s\0' "$f"; done ;;
  esac
}

# Blob ids under registry/ in the tree being checked, listed on first need.
list_registry_ids() {
  [ -s "$regids" ] && return
  if [ "$MODE" = range ]; then
    git ls-tree -r "$RANGE_HEAD" -- registry | awk '{print $3}'
  else
    git ls-files -s -- registry | awk '{print $2}'
  fi > "$regids"
}

read_bytes() {
  if [ "$MODE" = files ]; then cat -- "$1"; else git cat-file blob "$2"; fi
}

violations="$(mktemp)"
errors="$(mktemp)"
paths="$(mktemp)"
blob="$(mktemp)"
regids="$(mktemp)"
trap 'rm -f "$violations" "$errors" "$paths" "$blob" "$regids"' EXIT INT TERM

# A git error (bad ref, not a repo) must fail the check, not pass an empty list.
list_files "$@" > "$paths" || { echo "ERROR: could not list the files to check." >&2; exit 2; }
# Records are NUL-separated, so a newline byte can only come from a filename; sh cannot
# keep such a name whole, so refuse it rather than check the wrong files.
if [ "$(tr -cd '\n' < "$paths" | wc -c)" -gt 0 ]; then
  echo "ERROR: a file name contains a newline; rename it." >&2
  exit 2
fi

tr '\0' '\n' < "$paths" | while IFS= read -r header && IFS= read -r f; do
  [ -n "$f" ] || continue

  id=""
  if [ "$MODE" = files ]; then
    # Skip symlinks: `wc -c` would measure the link *target's* bytes, so a symlink
    # to a large LFS-tracked asset could be flagged even though the real blob is a
    # tiny pointer.
    [ -L "$f" ] && continue
    [ -f "$f" ] || continue
  else
    # ":<old mode> <new mode> <old id> <new id> <status>"
    set -- $header
    # A submodule (160000) records another repository's commit: nothing stored here.
    [ "$2" = 160000 ] && continue
    id="$4"
  fi

  # registry/ intentionally ships raw binary assets (block backgrounds, avatar
  # PNGs, .glb models, audio) so installed blocks stay portable without an LFS
  # round-trip. Those are the product, not accidental bloat — skip them here.
  case "$f" in registry/*) continue ;; esac
  # docs/public/catalog/ mirrors those assets for the docs site: exempt only an exact copy.
  case "$f" in docs/public/catalog/*)
    [ -n "$id" ] || id="$(git hash-object -- "$f")"
    list_registry_ids
    grep -qxF "$id" "$regids" && continue ;;
  esac

  # Text is exempt, whatever its size, because the cost this hook exists to stop
  # is a binary one. Git delta-compresses text, so a file that grows by a few KB
  # per commit adds a few KB to the pack. A binary of the same size re-enters the
  # pack whole on every edit, which is exactly how the history got its hundreds
  # of megabytes. `docs/changelog.mdx` is the case that forced this: half a
  # megabyte of release notes, a little larger every release, tripping a check
  # whose own error message says "large binaries".
  #
  # `grep -I` treats a file containing NUL bytes as binary, the same heuristic
  # git uses to print "Binary files differ". A generated blob of text is still
  # caught by review, not here.
  # Read once into a file so a failed read is an error, never an empty pass.
  read_bytes "$f" "$id" > "$blob" || { printf '%s\n' "$f" >> "$errors"; continue; }
  grep -qI . "$blob" && continue

  bytes="$(wc -c < "$blob" | tr -d ' ')"
  # Ceiling division: a sub-1024-byte file must report >=1 KB, never 0, so it
  # can't slip past a strict threshold (e.g. HF_MAX_NONLFS_KB=0). Plain
  # `bytes / 1024` would round a 512-byte binary down to 0 and pass it.
  kb=$(( (bytes + 1023) / 1024 ))
  [ "$kb" -le "$MAX_KB" ] && continue

  # A stored blob over the limit is raw bytes even when .gitattributes routes
  # the path through LFS (git-lfs was not installed). A file on disk under an
  # LFS pattern is the smudged copy of a pointer, so it passes.
  filter="$(git check-attr filter -- "$f" | sed 's/.*: //')"
  note=""
  if [ "$filter" = "lfs" ]; then
    [ "$MODE" = files ] && continue
    note=" — matches an LFS pattern but was stored raw; run \`git lfs install\` and re-add it"
  fi

  printf '%s\t%s\n' "$kb" "$f$note" >> "$violations"
done

if [ -s "$errors" ]; then
  echo "ERROR: could not read these files from git:" >&2
  sed 's/^/  • /' "$errors" >&2
  exit 2
fi

# `while` ran in a pipeline subshell, so it couldn't set a parent-shell flag —
# the violations file is the durable signal.
if [ -s "$violations" ]; then
  echo "ERROR: large binaries are being committed to git instead of LFS." >&2
  if [ "$MODE" = range ]; then
    echo "       (limit: ${MAX_KB} KB)" >&2
  else
    echo "       (limit: ${MAX_KB} KB — override per-commit with HF_MAX_NONLFS_KB)" >&2
  fi
  echo >&2
  while IFS='	' read -r kb f; do
    printf '  • %s (%s KB)\n' "$f" "$kb" >&2
  done < "$violations"
  echo >&2
  echo "Fix: add an LFS pattern for it in .gitattributes, e.g." >&2
  echo "       path/to/**/*.ext filter=lfs diff=lfs merge=lfs -text" >&2
  echo "     then re-stage the file. Or, if it should not be committed at all," >&2
  echo "     add it to .gitignore." >&2
  exit 1
fi