diff --git a/README.md b/README.md index e554dfb12..aa2a0781c 100644 --- a/README.md +++ b/README.md @@ -124,7 +124,7 @@ Checked by is the test your platform runs on its own, replicated here from its s ## Build your own pack -Clone the repo and generate packs for any platform, emulator, or system: +Packs are built from a clone, and the clone carries the collection: its checkout alone is over 7.7 GB. `git clone --depth 1 https://github.com/Abdess/retrobios.git` leaves the history out. Files kept as release assets are downloaded when a pack needs them. Then generate packs for any platform, emulator, or system: ```bash # The pack of a platform, as released diff --git a/scripts/generate_readme.py b/scripts/generate_readme.py index e845201a0..2dd324168 100644 --- a/scripts/generate_readme.py +++ b/scripts/generate_readme.py @@ -40,6 +40,7 @@ from nativemode import check_label import release_record from siteguides import install_command from validate_pr import LARGE_FILE_ISSUE_URL +from largefiles import load_registered_paths from verify import verify_platform @@ -447,6 +448,29 @@ REPO = "Abdess/retrobios" UPLOAD_URL = f"https://github.com/{REPO}/upload/main/bios" +def clone_line(db: dict) -> str: + """How to get the clone the commands below run in, and its size. + + Said bare, "clone the repo" started a multi-gigabyte transfer for a user + after a 20 MB --required-only pack. The size counts the collection files + the repository commits, a floor: release assets are fetched only when a + pack needs them. + """ + assets = set(load_registered_paths()) + committed = sum( + entry.get("size", 0) for entry in db.get("files", {}).values() + if entry.get("path") not in assets + ) + return ( + "Packs are built from a clone, and the clone carries the collection:" + f" its checkout alone is over {format_size(committed)}." + f" `git clone --depth 1 https://github.com/{REPO}.git` leaves the" + " history out. Files kept as release assets are downloaded when a" + " pack needs them. Then generate packs for any platform, emulator," + " or system:" + ) + + def _existing_contributor_block(readme_path: str = "README.md") -> list[str]: """The contributors already published, read back from the file. @@ -767,7 +791,7 @@ def generate_readme(db: dict, platforms_dir: str, db_path: str = "database.json" "", "## Build your own pack", "", - "Clone the repo and generate packs for any platform, emulator, or system:", + clone_line(db), "", "```bash", "# The pack of a platform, as released", diff --git a/tests/test_doc_pages.py b/tests/test_doc_pages.py index e4b85bfea..bc7a6a5a7 100644 --- a/tests/test_doc_pages.py +++ b/tests/test_doc_pages.py @@ -2031,3 +2031,22 @@ class RegionFreeRuleNamesWhereItDoesNotHold(unittest.TestCase): if drops: with self.subTest(platform=platform, file=name): self.assertRegex(bullet, rf"(?i)\b{re.escape(platform)}\b") + + +class BuildYourOwnPackSaysWhatTheCloneCosts(unittest.TestCase): + """The README sent a user after a minimal pack to "Clone the repo", with no + command and no size, and the clone runs to several gigabytes.""" + + def test_readme_gives_the_clone_command_and_its_size(self): + import generate_readme + + db = json.loads((ROOT / "database.json").read_text(encoding="utf-8")) + line = generate_readme.clone_line(db) + self.assertIn("git clone --depth 1", line) + self.assertRegex(line, r"over \d+(\.\d)? GB") + section = _section((ROOT / "README.md").read_text(encoding="utf-8"), + "Build your own pack") + self.assertIn("git clone --depth 1", section) + + def test_advanced_usage_names_the_shallow_clone(self): + self.assertIn("--depth 1", _page("advanced-usage.md").split("## Custom packs")[0]) diff --git a/wiki/advanced-usage.md b/wiki/advanced-usage.md index 8ee0f0c17..ecc7a801d 100644 --- a/wiki/advanced-usage.md +++ b/wiki/advanced-usage.md @@ -19,7 +19,8 @@ boot, with no message saying why. It is not a guarantee either: source profiles can document files nobody has dumped or that only the user can provide, all of them visible in the [gap analysis](../gaps.md). -From a clone of the repository, `python scripts/generate_pack.py --platform +A clone carries the whole collection, several gigabytes, and `git clone +--depth 1` leaves its history out. From that clone, `python scripts/generate_pack.py --platform retroarch --region us` builds a narrower pack, `--required-only` the bare minimum each core needs to start, and `--no-game-data` keeps the firmware and leaves out the files a game reads. `--help` lists every way to build your own,