install.sh: shallow clone, about 215 MB to download instead of 351

[ZLHad]

What

install.sh now clones only the newest commit (git clone --depth 1 --single-branch), so a fresh install downloads about 215 MB instead of 351 MB, and the clone takes about 420 MB on disk instead of 547 MB.

Fresh clone of main at a881f4f (measured 2026-10-04, macOS)	Download (pack, decimal MB)	On disk (du -sh)	of which .git
before: full clone	351 MB	547 MB	336 MB
after: --depth 1 --single-branch	215 MB	419 MB	208 MB

The real installer, run against GitHub with --no-refs --no-skill, comes to 626 MB: the 419 MB clone plus 207 MB of node_modules. Adding the 195 MB of reference repos gives about 825 MB, down from 935 MB.

Why

After #51, most of .git is old versions of the sample films (showcase/04-intro-film/media/final.mp4 alone is 48 MB, and v3's media moved to v3/). People who only make videos don't need that history.

How re-running the installer updates a checkout

Shallow checkout (.git/shallow exists):

1. It stops, before fetching anything, in two cases:
   • the checkout isn't on a branch that tracks the repo (@{u} doesn't resolve: a detached HEAD, or a branch of your own);
   • it has commits of your own (@{u}..HEAD isn't empty and HEAD isn't a shallow boundary).
2. Otherwise it runs git fetch -q --depth 1, then git reset -q --keep '@{u}'. The new commit's parent isn't fetched, so there is nothing to fast-forward along. reset --keep moves the branch and leaves untracked and ignored files (LOCAL.md, projects/) and edits to untouched files alone.
3. If reset --keep refuses because it would overwrite an edited file, or an untracked file that isn't ignored:
   • origin/main is put back where it was, so git status and the next run see the checkout unchanged;
   • a plain git pull would still fail in that state, because the fetched commit stays grafted in .git/shallow; it failed before this change too. The README tells shallow installs to update by re-running the installer, and keeps git pull for full clones.
   • the installer prints a hint: stash and stash pop for edited files, move untracked ones out of the way.

Full clone (made by hand, or by an earlier installer): still git pull --ff-only. I checked that a --depth 1 fetch turns a full clone shallow (rev-list --count origin/main is 1 afterwards), so full clones don't go through the shallow path.

Docs

• README.md / README.zh-CN.md:
  • the clone bullet in "Start in 30 seconds" (420 MB, without history);
  • the total (825 MB instead of 935);
  • the "What gets downloaded" row (about 215 MB to download, 420 MB on disk);
  • before the by-hand block, a note that contributors who want the history should clone normally (git clone https://github.com/ZLHad/OpenVideoHarness.git, about 550 MB);
  • "To update" now says to re-run the install command with the same options, and shows how to pass them to the one-line install (| bash -s -- --no-refs).
• showcase/04-intro-film/v3/README*: the git checkout 7057c74 -- showcase/04-intro-film instruction fails in a depth-1 clone. It now says to run git fetch --depth 1 origin <full sha> first; I checked that GitHub serves this by-SHA fetch.
• The install.sh header comment, and CHANGELOG (Unreleased).
• Wiki Getting-Started.md / 快速开始.md: the same changes are committed locally (wiki 1bba66a) but not pushed. I'll push them once this PR is merged, so the wiki doesn't describe an installer that isn't live yet.

How I tested it

• Synthetic remote. A harness runs the real install.sh against a local synthetic remote (stub engines, --no-refs --no-skill). It has 50 checks:
  • a fresh install is shallow, with one commit and a single-branch refspec;
  • a re-run after two new commits reaches the tip, stays at depth 1, and keeps LOCAL.md, projects/ and an edit to an untouched file;
  • a re-run with nothing new changes nothing;
  • an edit clash exits 1, names the file, keeps the edit and puts origin/main back; after stash, the re-run succeeds;
  • a commit of your own stops the update;
  • an untracked file in the way exits 1, prints the right hint and keeps the file;
  • a manual git pull, then a clash, then stash, then a re-run succeeds, with no false "own commits";
  • a branch of your own without upstream exits 1, fetches nothing and prints no git fatal:;
  • a detached HEAD stops the update;
  • an upstream configured with origin/main missing, plus a commit of your own, stops the update;
  • a full clone keeps its history and fast-forwards.
• Results. All 50 checks pass under macOS /bin/bash 3.2 and bash 5, and again with the script piped on stdin, as curl | bash runs it. They pass with git 2.43.0 and with Apple Git 2.39.5. The first commit's install.sh fails 12 of them; those are the cases an independent review found.
• End to end against GitHub. I ran an install, then a re-run on the shallow checkout. Both exit 0, and git status is clean afterwards.
• CI. tools/ci.sh --committed passes with shellcheck 0.11.0 and pyflakes, both under bash 5 and with VH_BASH=/bin/bash.
• Review. An independent reviewer (fresh context) reviewed the first commit, and its findings are fixed in the second. The reviewer then re-ran its edge cases on git 2.43.0 and Apple Git 2.39.5; its last notes are fixed in the third commit: the git pull wording, quieting rev-parse on 2.39, and the hint for a missing origin/main.