docs(contributing): clone with --depth 1: the newest commit only, and how to get the history when you need it

HumanBean commented

2026-11-13 14:45:25 +00:00

Owner

Why

On release day, git clones of Longshot were one of the biggest loads on git.magicbean.dev, whose upload link was saturated. Cloning the newest commit only (--depth 1) halves each contributor's download.

What changed

CONTRIBUTING.md, Get started, step 1: git clone --depth 1 … (and jj's --depth 1). A short paragraph says what still works (git pull, branches, pull requests), what needs the history (git log/git blame past the clone, a version name from the tags, cutting a release with scripts/release.py), and how to get it: git fetch --unshallow --tags.
The same change for the launcher: LongshotLauncher PR 41.

Flags and settings

None.

Measurements

main: 2331f46 (2026-11-13)
this PR: docs/shallow-clone @ 0ccdf27
Hardware: not applicable (a docs change); clones from git.magicbean.dev to a Linux PC
Scene: not applicable
Method: du -sh .git of git clone --depth 1 against the size of the repository's packs on the server, after today's repack
How to reproduce: git clone --depth 1 https://git.magicbean.dev/MagicBeanDev/Longshot.git && du -sh Longshot/.git

	main @ `2331f46` (full clone)	this PR @ `0ccdf27` (`--depth 1`)
Longshot's `.git`	36 MB (the server's packs)	17 MB

Testing

Tested: a git clone --depth 1 of Longshot from git.magicbean.dev: 17 MB. In it, python -I nx2/version.py names the build by its commit (2331f46 (source cb01b5a3)), as the paragraph says; scripts/check_third_party.py uses the history only with --base. jj 0.47 has jj git clone --depth. python -I -B tests/run_all.py: 455 passed, 2 failed, 65 skipped; both failures fail the same way on main @ 2331f46 on this PC: test_bake_portability (no zstandard installed here) and test_display_pointer (a link error, win::rx_option undefined).

Not tested: a first build from a shallow clone (the build reads no git history beyond the version name above).

Needs other testers: None

Screenshots

Nothing on screen

Risk and rollback

A contributor who needs the history meets a shallow clone; the paragraph says how to deepen it. Reverting the commit restores the old instructions.

Reviewer notes

The game-side cost is the version name in a shallow build: a commit hash rather than v3.0.0-rc.3-5-g…. Players' builds come from the release zips, which carry version.txt, so they are unaffected.

Checklist

For everyone

One topic.
The title is a Conventional Commit (type(scope): description).
Rebased on current main.
python -I -B tests/run_all.py run and passing (any failure that also fails on main is named above).
Tested in the game, or what wasn't is named under Testing.
Testing filled in: what was tested, what wasn't, and what needs other testers (with test requests).
Measured: main and this PR at named commits, on the same PC, scene and settings, at least 2 interleaved runs each, the median reported.
No game files, dumps, build output or generated files.
third_party/ untouched (a new folder with a PROVENANCE.md instead).
The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled.

If applicable

AI assistance recorded with Assisted-by: / Co-Authored-By: trailers.
Docs updated.

🤖 Generated with Claude Code

## Why On release day, git clones of Longshot were one of the biggest loads on git.magicbean.dev, whose upload link was saturated. Cloning the newest commit only (`--depth 1`) halves each contributor's download. ## What changed - `CONTRIBUTING.md`, *Get started*, step 1: `git clone --depth 1 …` (and jj's `--depth 1`). A short paragraph says what still works (`git pull`, branches, pull requests), what needs the history (`git log`/`git blame` past the clone, a version name from the tags, cutting a release with `scripts/release.py`), and how to get it: `git fetch --unshallow --tags`. - The same change for the launcher: [LongshotLauncher PR 41](https://git.magicbean.dev/MagicBeanDev/LongshotLauncher/pulls/41). ## Flags and settings None. ## Measurements main: 2331f46 (2026-11-13) this PR: docs/shallow-clone @ 0ccdf27 Hardware: not applicable (a docs change); clones from git.magicbean.dev to a Linux PC Scene: not applicable Method: `du -sh .git` of `git clone --depth 1` against the size of the repository's packs on the server, after today's repack How to reproduce: `git clone --depth 1 https://git.magicbean.dev/MagicBeanDev/Longshot.git && du -sh Longshot/.git` | | main @ 2331f46 (full clone) | this PR @ 0ccdf27 (`--depth 1`) | |---|---|---| | Longshot's `.git` | 36 MB (the server's packs) | 17 MB | ## Testing **Tested:** a `git clone --depth 1` of Longshot from git.magicbean.dev: 17 MB. In it, `python -I nx2/version.py` names the build by its commit (`2331f46 (source cb01b5a3)`), as the paragraph says; `scripts/check_third_party.py` uses the history only with `--base`. jj 0.47 has `jj git clone --depth`. `python -I -B tests/run_all.py`: 455 passed, 2 failed, 65 skipped; both failures fail the same way on `main` @ 2331f46 on this PC: `test_bake_portability` (no `zstandard` installed here) and `test_display_pointer` (a link error, `win::rx_option` undefined). **Not tested:** a first build from a shallow clone (the build reads no git history beyond the version name above). **Needs other testers:** None ## Screenshots Nothing on screen ## Risk and rollback A contributor who needs the history meets a shallow clone; the paragraph says how to deepen it. Reverting the commit restores the old instructions. ## Reviewer notes The game-side cost is the version name in a shallow build: a commit hash rather than `v3.0.0-rc.3-5-g…`. Players' builds come from the release zips, which carry `version.txt`, so they are unaffected. ## Checklist ### For everyone - [x] One topic. - [x] The title is a Conventional Commit (`type(scope): description`). - [x] Rebased on current `main`. - [x] `python -I -B tests/run_all.py` run and passing (any failure that also fails on `main` is named above). - [x] Tested in the game, or what wasn't is named under Testing. - [x] Testing filled in: what was tested, what wasn't, and what needs other testers (with test requests). - [x] Measured: main and this PR at named commits, on the same PC, scene and settings, at least 2 interleaved runs each, the median reported. - [x] No game files, dumps, build output or generated files. - [x] `third_party/` untouched (a new folder with a `PROVENANCE.md` instead). - [x] The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled. ### If applicable - [x] AI assistance recorded with `Assisted-by:` / `Co-Authored-By:` trailers. - [x] Docs updated. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

HumanBean added 1 commit

2026-11-13 14:45:25 +00:00

docs(contributing): clone with --depth 1: the newest commit only, and how to get the history when you need it

CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped

Details

CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped

Details

CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped

Details

Third-party parts / The same as upstream (pull_request) Has been skipped

Details

CI / Conventional Commit title (pull_request) Successful in 3s

Details

CI / Workflow lint (actionlint) (pull_request) Successful in 7s

Details

Third-party parts / As their notes say (pull_request) Successful in 7s

Details

PR description / Description follows the template (pull_request_target) Successful in 3s

Details

0ccdf274ab

Co-Authored-By: Claude Opus 5.5 <[email protected]>

HumanBean referenced this pull request from MagicBeanDev/LongshotLauncher

2026-11-13 14:45:35 +00:00

docs: clone with --depth 1: the newest commit only, and how to get the history when you need it #41

HumanBean commented

2026-11-13 14:45:49 +00:00

Author

Owner

Needs other testers: None, in the form the description check reads.

HumanBean changed title from ~~WIP: docs(contributing): clone with --depth 1: the newest commit only, and how to get the history when you need it~~ to docs(contributing): clone with --depth 1: the newest commit only, and how to get the history when you need it

2026-11-13 14:45:49 +00:00

HumanBean referenced this pull request from a commit

2026-11-13 14:47:04 +00:00

docs: clone with --depth 1: the newest commit only, and how to get the history when you need it (#41)

HumanBean merged commit dd02c6cca9 into main

2026-11-13 14:47:05 +00:00

HumanBean deleted branch docs/shallow-clone

2026-11-13 14:47:06 +00:00

HumanBean referenced this pull request from a commit

2026-11-13 14:47:06 +00:00

docs(contributing): clone with --depth 1: the newest commit only, and how to get the history when you need it (#214)