# VideoGuideMaker / Video2Guide — Deploy Guide ## TL;DR To ship code changes to https://huggingface.co/spaces/joemartis/Video2Guide: ```bash ~/bin/deploy-hf ``` That's the whole deploy. Wait ~1–3 minutes for HF to rebuild. --- ## Where everything lives | Thing | Location | |---|---| | Local checkout | `/Users/jmartis/Documents/GitHub/VideoGuideMaker` | | GitHub repo (source of truth) | https://github.com/JoeMartis/VideoGuideMaker | | HF Space (live site) | https://huggingface.co/spaces/joemartis/Video2Guide | | Deploy script | `/Users/jmartis/bin/deploy-hf` | ## Remotes inside the repo ``` github → https://github.com/JoeMartis/VideoGuideMaker.git (source) origin → https://huggingface.co/spaces/joemartis/Video2Guide (live site) ``` (There's also a duplicate `space` remote pointing at HF; harmless, ignore it.) --- ## How code reaches production ``` You ask Claude → Claude commits to claude/general-session-* branch on GitHub ↓ Auto-merge bot opens & merges PR into main on GitHub ↓ You run `deploy-hf` ↓ Script pulls main, strips video files from history, force-pushes to HF ↓ HF rebuilds Docker container (~1–3 min) → live ``` You don't push to GitHub yourself. Claude handles all writes; the bot merges; `deploy-hf` reads. --- ## What `deploy-hf` does, step by step ```bash #!/usr/bin/env bash set -euo pipefail cd /Users/jmartis/Documents/GitHub/VideoGuideMaker # 1. Fetch the latest main from GitHub git fetch github main # 2. Throwaway working branch built fresh from GitHub each run git checkout -B hf-deploy github/main # 3. Strip every video file from the entire git history. # HF rejects any file >10MB not in LFS; a few old commits # include big .m4v / .mp4 sample inputs that have to be gone. git filter-repo --invert-paths \ --path-glob '*.mp4' --path-glob '*.m4v' \ --path-glob '*.mov' --path-glob '*.mkv' --path-glob '*.webm' \ --force # 4. filter-repo defensively drops `origin`; re-add (silent if it's there) git remote add origin https://huggingface.co/spaces/joemartis/Video2Guide 2>/dev/null || true # 5. Force-push to HF. Force is required because each filter-repo run # produces a new SHA chain — content matches, history doesn't. git push origin hf-deploy:main --force ``` You never need to touch your real local `main` — the script lives on a separate `hf-deploy` branch. --- ## Verifying a deploy worked After running `deploy-hf`: ```bash curl -s https://huggingface.co/api/spaces/joemartis/Video2Guide | \ python3 -c 'import json,sys; d=json.load(sys.stdin); print("sha:", d.get("sha"), "stage:", d.get("runtime",{}).get("stage"))' ``` - `stage: BUILDING` → still building, wait - `stage: RUNNING` → live - `sha: ` → the commit currently deployed (different from your local SHA because of the filter-repo rewrite — that's expected) You can also watch the build live in the **Logs** tab on the Space page. --- ## Adding new code changes You don't run git for code changes. Tell Claude what you want, e.g.: - "Default the LLM toggles to off" - "When I pick an alternate frame, update the OCR text" - "Remove the TL;DR mode" Claude will: 1. Make the edits 2. Run the test suite (for backend changes) 3. Commit on `claude/general-session-*` and push 4. The auto-merge bot opens a PR and merges it into `main` Then **you** run `deploy-hf` to push it to HF. --- ## Troubleshooting **`'github' does not appear to be a git repository`** The script's `cd` is landing somewhere without your remotes set up. Either fix the `cd` line or run the script from inside the right folder. **`error: unknown option 'force~'` (or any `~` typo)** Open `~/bin/deploy-hf` in `nano`, look for stray `~` characters, remove them. **HF push rejected with `files larger than 10 MiB`** A new video file in history slipped past the glob list. Run the script's filter-repo step again with the offending extension added. **HF push rejected with `non-fast-forward`** You ran `git push origin main:main` directly instead of using `deploy-hf`. Don't push to HF from your real `main` — go through the script. **Build fails on HF** Open the Space's Logs tab. Most common cause: a Python import error or missing dependency. Tell Claude the error message. **`deploy-hf` works but the site looks unchanged** Browser cache. Hard-reload (Cmd-Shift-R) or open the Space URL in a private window. --- ## Important rules 1. **Never paste your GitHub token in chat or commit it to a file.** If you ever do, immediately revoke at https://github.com/settings/tokens. 2. **Never put videos in `git add`.** They're in `.gitignore`, but if you `git add -f` past it, you'll need to filter-repo them out again. 3. **Don't manually push to HF `main`.** Always use `deploy-hf`. Manual pushes will fail because of history mismatch. 4. **Don't filter-repo on your real `main` branch.** The script does this on a throwaway `hf-deploy` branch on purpose. Your `main` should always track `github/main` cleanly. --- ## Known limitations - **GitHub `main` history still contains the big videos** in old commits. Anyone cloning the repo fresh from GitHub still downloads them. The clean history only exists on HF and in your throwaway `hf-deploy` branch. Living with this; not worth more pain to fully unify. - **Each `deploy-hf` run does a force-push to HF.** This is intentional and safe — HF is a deploy target, not a collaboration repo. --- If something breaks, tell Claude the error and what you ran. Don't paste tokens. That's it.