| # Git and Xet storage |
|
|
| The Hugging Face remote is `git@hf.co:nmarshall/wormz-a` (`hf`). |
| The `main` branch contains the OpenWA master history with test payloads converted |
| to Git LFS pointers. Original authorship and commit messages are preserved, but |
| migration changes commit IDs. The original upstream history remains on local |
| `master` and `origin/*`; publish `main` to `hf`, not those original refs. |
|
|
| Source, scripts, manifests and documentation remain ordinary Git text. |
| Test replays, expected logs, snapshots, scheme fixtures, images and other assets |
| use Git LFS backed by Xet, including small textual test payloads. |
| `.gitattributes` declares this policy; `scripts/storage_policy.py` enforces it. |
| No original game installation or proprietary game assets are added by this setup. |
|
|
| ## Set up a checkout |
|
|
| Install Git, Python 3, Git LFS and Git Xet (the local Nix environment already |
| provides Git LFS and Git Xet), then run from the repository root: |
|
|
| ```sh |
| python3 scripts/setup-repository.py |
| git lfs pull hf |
| python3 scripts/storage_policy.py check --require-setup |
| ``` |
|
|
| For a fresh clone, use: |
|
|
| ```sh |
| git clone -o hf git@hf.co:nmarshall/wormz-a |
| cd wormz-a |
| python3 scripts/setup-repository.py |
| ``` |
|
|
| Setup is idempotent. It registers the required `openwa-code` clean filter, |
| Git LFS, the Xet custom transfer agent and `.githooks`. It refuses to replace |
| an existing local hooks path. The clean filter passes code through unchanged |
| and rejects misplaced payloads, non-UTF-8/binary content and code over 2 MiB. |
| Asset directory rules route even small text payloads through LFS. Documentation |
| and `.gitignore` files in `testdata/` are explicit ordinary-Git exceptions. |
|
|
| Commit and push normally: |
|
|
| ```sh |
| git add <paths> |
| git commit -m "area: short description" |
| git push hf main |
| ``` |
|
|
| The pre-commit hook validates staged Git blobs and attributes. The pre-push hook |
| validates newly reachable history and then runs `git lfs pre-push`; Git LFS uses |
| its registered Xet transfer agent when negotiated with Hugging Face. Files remain |
| fully materialized in the working tree, while Git stores only asset pointers. |
| Do not bypass the hooks. If adding a new payload format or directory, update both |
| `.gitattributes` and the classifier in `scripts/storage_policy.py`. |
|
|
| Adding attributes affects future staging, not existing history. Do not merge the |
| unmigrated upstream refs into `main`: that would reintroduce raw historical |
| payloads. Future upstream synchronization needs the corresponding LFS conversion |
| before integration. Do not rewrite published history or force-push implicitly. |
|
|
