Spaces:
Running
Download DEPLOY.md from joemartis/Video2Guide: direct link, hf CLI and curl.
- Browser
- Download file 5.71 kB
-
https://huggingface.co/spaces/joemartis/Video2Guide/resolve/main/DEPLOY.md
- Command line
-
hf download hf://spaces/joemartis/Video2Guide/DEPLOY.md
-
curl -L -o DEPLOY.md https://huggingface.co/spaces/joemartis/Video2Guide/resolve/main/DEPLOY.md
VideoGuideMaker / Video2Guide β Deploy Guide
TL;DR
To ship code changes to https://huggingface.co/spaces/joemartis/Video2Guide:
~/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
#!/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:
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, waitstage: RUNNINGβ livesha: <hash>β 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:
- Make the edits
- Run the test suite (for backend changes)
- Commit on
claude/general-session-*and push - 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
- 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.
- Never put videos in
git add. They're in.gitignore, but if yougit add -fpast it, you'll need to filter-repo them out again. - Don't manually push to HF
main. Always usedeploy-hf. Manual pushes will fail because of history mismatch. - Don't filter-repo on your real
mainbranch. The script does this on a throwawayhf-deploybranch on purpose. Yourmainshould always trackgithub/maincleanly.
Known limitations
- GitHub
mainhistory 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 throwawayhf-deploybranch. Living with this; not worth more pain to fully unify. - Each
deploy-hfrun 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.