git0 0.2.99 → 0.3.0

package/benchmark/README.md

@@ -0,0 +1,104 @@
+# Benchmark: tarball + lazy history vs. `git clone`
+
+What this measures, and why git0 downloads a repository the way it does.
+
+```bash
+bun run bench                    # the default repo set
+bun run bench facebook/react     # or whichever repos you care about
+```
+
+It hits github.com, so it is not part of `bun test` and never runs in CI — the
+file is a `.bench.ts`, which Bun's test runner does not collect.
+
+## The number that matters
+
+Not "how long did the download take". **How long until you can run the
+project.** That is the clock the user is actually watching, and it stops when
+the files are on disk — when `bun install` can start and the editor has
+something to index. Git history is not on that path: nothing about installing
+dependencies or opening a file needs `git log`.
+
+So every strategy is measured twice:
+
+| column | means |
+| --- | --- |
+| **time to files** | source tree on disk — install can start, IDE can open |
+| **time to history** | full commit history available — `git log`, `git blame`, branches |
+
+## The four strategies
+
+| strategy | what it does |
+| --- | --- |
+| `git clone` | the baseline — the command git0 replaces |
+| `git clone --depth=1` | the usual "clone can be fast too" answer |
+| `git0` | codeload tarball, extracted as it streams |
+| `git0 --history` | the tarball, then `.git` attached afterwards |
+
+## Why the tarball wins on time-to-files
+
+Three reasons, and only the third is about size.
+
+**A clone is serial; a tarball overlaps.** `git clone` is a negotiation: the
+client says what it has, the server walks the object graph, counts and compresses
+objects into a pack, sends it, and only then does the client resolve deltas and
+write a working tree. The first file appears near the *end*. A codeload tarball
+is a single pre-made gzip stream of one commit, so git0 pipes the response
+straight into a `tar` extractor — bytes are being written to disk while the rest
+is still arriving. Download and extraction are the same wall-clock interval
+instead of two consecutive ones.
+
+**The server has already done the work.** GitHub caches tarballs. A clone makes
+the remote pack objects for your particular request; a tarball is usually served
+from cache, and is never a per-request computation on the remote's CPU.
+
+**History is most of the bytes.** For anything long-lived the object database
+dwarfs the checkout — every version of every file that ever existed, against one
+copy of the current ones. The `on disk` column in the table is where that shows
+up, and it is the size the tarball never transfers.
+
+`--depth=1` closes most of the gap on time-to-files, which is exactly why it is
+in the table. It is still a pack negotiation rather than a cached file, and it
+leaves you with a repository that cannot do the thing you wanted history for —
+`git log` shows one commit, and blame is useless. It buys speed by giving up the
+feature.
+
+## Why "lazy" history is not a trick
+
+`git0 --history` ends in the same state as `git clone`: a working tree with a
+complete `.git` beside it. The difference is ordering. Extraction finishes,
+and the history clone starts *there* — in parallel with the IDE launching and
+dependencies installing, both of which take their own seconds and neither of
+which touches `.git`.
+
+So the honest comparison is two numbers, and the table gives both:
+
+- **time to files** — git0 is far ahead, because it is not waiting on history.
+- **time to history** — roughly `git clone`, plus the tarball it already
+  finished. You pay a little more for the complete result, and get to start
+  working well before it arrives.
+
+The mechanics of attaching it (bare clone into a temporary directory, renamed
+into place, `core.bare` flipped, index refreshed from `HEAD` so `git status` is
+clean without touching the extracted files) are in
+[`src/history.ts`](../src/history.ts).
+
+## Reading a run
+
+```text
+### expressjs/express
+
+| strategy | repo | time to files | time to history | on disk | vs git clone |
+| --- | --- | --- | --- | --- | --- |
+| git clone | expressjs/express | … | … | … | — |
+| git clone --depth=1 | expressjs/express | … | — | … | …× |
+| git0 | expressjs/express | … | — | … | …× |
+| git0 --history | expressjs/express | … | … | … | …× |
+```
+
+`vs git clone` is the time-to-files ratio against the baseline — `4.00×` means
+the working tree was ready in a quarter of the time. A `—` in **time to
+history** means that strategy never produces a usable history, which is a result
+about the strategy and not a gap in the measurement.
+
+Run it against your own repositories before quoting any of it: the ratios depend
+on how much history the project has and on the network between you and GitHub.

package/benchmark/report.ts

@@ -0,0 +1,142 @@
+/**
+ * One measured run of one strategy against one repository.
+ */
+export interface Measurement {
+  /** Strategy label, e.g. `'git clone'` or `'git0 --history'`. */
+  strategy: string;
+  /** `owner/repo` that was fetched. */
+  repo: string;
+  /**
+   * Milliseconds until the source tree was on disk — the moment `bun install`
+   * could start and therefore the moment the clock that matters stops.
+   */
+  timeToFiles: number;
+  /**
+   * Milliseconds until the full commit history was available, or `null` for a
+   * strategy that never produces one (a tarball, a shallow clone).
+   */
+  timeToHistory: number | null;
+  /** Bytes written to disk, when the runner measured it. */
+  bytesOnDisk?: number;
+  /** Set when the run failed; the other numbers are then meaningless. */
+  error?: string;
+}
+
+/**
+ * Formats a duration the way a benchmark reader wants to read it: milliseconds
+ * while they are small enough to compare at a glance, seconds after that.
+ *
+ * @param ms - Duration in milliseconds, or `null` for "never happened".
+ * @returns A short human-readable string.
+ *
+ * @example
+ * formatDuration(842);   // → '842ms'
+ * formatDuration(12400); // → '12.40s'
+ * formatDuration(null);  // → '—'
+ */
+export function formatDuration(ms: number | null): string {
+  if (ms === null) return '—';
+  return ms < 1000 ? `${Math.round(ms)}ms` : `${(ms / 1000).toFixed(2)}s`;
+}
+
+/**
+ * Formats a byte count in binary units.
+ *
+ * @param bytes - Size in bytes, or `undefined` when it was not measured.
+ * @returns A short human-readable string.
+ *
+ * @example
+ * formatBytes(1536);      // → '1.5 KiB'
+ * formatBytes(undefined); // → '—'
+ */
+export function formatBytes(bytes?: number): string {
+  if (bytes === undefined) return '—';
+
+  const units = ['B', 'KiB', 'MiB', 'GiB'];
+  let value = bytes;
+  let unit = 0;
+
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+
+  return `${unit === 0 ? value : value.toFixed(1)} ${units[unit]}`;
+}
+
+/**
+ * How much sooner a strategy got to a usable working tree than the baseline.
+ *
+ * Expressed against `git clone` because that is the command git0 replaces, and
+ * as a ratio because the absolute numbers are dominated by the repository's
+ * size and the network between you and GitHub.
+ *
+ * @param measurements - Every run for one repository.
+ * @param baseline - Strategy to compare against.
+ * @returns Map of strategy to speedup (`2` means "half the time"), skipping the
+ *   baseline itself and any run that failed.
+ *
+ * @example
+ * speedups([
+ *   { strategy: 'git clone', repo: 'a/b', timeToFiles: 8000, timeToHistory: 8000 },
+ *   { strategy: 'git0',      repo: 'a/b', timeToFiles: 2000, timeToHistory: null },
+ * ]);
+ * // → Map { 'git0' => 4 }
+ */
+export function speedups(
+  measurements: Measurement[],
+  baseline = 'git clone'
+): Map<string, number> {
+  const reference = measurements.find(m => m.strategy === baseline && !m.error);
+  const result = new Map<string, number>();
+  if (!reference || reference.timeToFiles <= 0) return result;
+
+  for (const measurement of measurements) {
+    if (measurement.error || measurement.strategy === baseline) continue;
+    if (measurement.timeToFiles <= 0) continue;
+    result.set(measurement.strategy, reference.timeToFiles / measurement.timeToFiles);
+  }
+
+  return result;
+}
+
+/**
+ * Renders the measurements as a GitHub-flavoured markdown table.
+ *
+ * Markdown rather than aligned columns so a run can be pasted straight into an
+ * issue or a PR, which is where benchmark numbers are actually argued about.
+ *
+ * @param measurements - Runs to render, in the order they should appear.
+ * @returns The table, without a trailing newline.
+ *
+ * @example
+ * console.log(formatTable(results));
+ */
+export function formatTable(measurements: Measurement[]): string {
+  const gains = speedups(measurements);
+
+  const rows = measurements.map(measurement => {
+    if (measurement.error) {
+      return `| ${measurement.strategy} | ${measurement.repo} | failed: ${measurement.error} | | | |`;
+    }
+
+    const gain = gains.get(measurement.strategy);
+
+    return [
+      '',
+      measurement.strategy,
+      measurement.repo,
+      formatDuration(measurement.timeToFiles),
+      formatDuration(measurement.timeToHistory),
+      formatBytes(measurement.bytesOnDisk),
+      gain ? `${gain.toFixed(2)}×` : '—',
+      '',
+    ].join(' | ').trim();
+  });
+
+  return [
+    '| strategy | repo | time to files | time to history | on disk | vs git clone |',
+    '| --- | --- | --- | --- | --- | --- |',
+    ...rows,
+  ].join('\n');
+}

package/benchmark/tarball-vs-clone.bench.ts

@@ -0,0 +1,173 @@
+#!/usr/bin/env bun
+/**
+ * Measures how long each way of getting a GitHub repository onto your machine
+ * takes to reach the point where you can actually run the project.
+ *
+ * Run it:
+ *
+ * ```bash
+ * bun run bench                       # the default repo set
+ * bun run bench facebook/react        # or whichever repos you care about
+ * ```
+ *
+ * It talks to github.com, so the numbers move with your connection — the point
+ * is the ratio between the rows of one run, not any single figure. Nothing here
+ * runs in CI: it is a `.bench.ts`, which `bun test` does not collect.
+ *
+ * @see ./README.md for what the numbers mean and why they come out this way.
+ */
+import { execFile } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { promisify } from 'util';
+
+import GithubAPI from '../src/github-api.js';
+import { attachGitHistory } from '../src/history.js';
+import { formatTable, type Measurement } from './report.js';
+
+const run = promisify(execFile);
+
+/** Repositories measured when none are named on the command line. */
+const DEFAULT_REPOS = ['sindresorhus/is', 'expressjs/express', 'vitejs/vite'];
+
+/**
+ * Total size of a directory tree, in bytes.
+ *
+ * Included because it is half the explanation: a shallow tarball and a full
+ * clone of the same repository differ by however many megabytes of history the
+ * project has accumulated, and that difference is what the download is not
+ * waiting for.
+ *
+ * @param target - Directory to measure.
+ * @returns Size in bytes, counting file contents only.
+ */
+function directorySize(target: string): number {
+  let total = 0;
+
+  for (const entry of fs.readdirSync(target, { withFileTypes: true })) {
+    const full = path.join(target, entry.name);
+    if (entry.isDirectory()) total += directorySize(full);
+    else if (entry.isFile()) total += fs.statSync(full).size;
+  }
+
+  return total;
+}
+
+/**
+ * Times one strategy, cleaning up after itself whether or not it worked.
+ *
+ * @param strategy - Label for the report.
+ * @param repo - `owner/repo` being measured.
+ * @param work - Receives a scratch directory; returns when the *files* are
+ *   ready, and optionally a promise that settles when history is ready.
+ * @returns The measurement.
+ */
+async function measure(
+  strategy: string,
+  repo: string,
+  work: (workdir: string) => Promise<{ dir: string; history?: Promise<unknown> }>
+): Promise<Measurement> {
+  const workdir = fs.mkdtempSync(path.join(os.tmpdir(), 'git0-bench-'));
+  const started = performance.now();
+
+  try {
+    const { dir, history } = await work(workdir);
+    const timeToFiles = performance.now() - started;
+
+    let timeToHistory: number | null = null;
+    if (history) {
+      await history;
+      timeToHistory = performance.now() - started;
+    }
+
+    return {
+      strategy,
+      repo,
+      timeToFiles,
+      timeToHistory,
+      bytesOnDisk: directorySize(dir),
+    };
+  } catch (error: any) {
+    return { strategy, repo, timeToFiles: 0, timeToHistory: null, error: error.message };
+  } finally {
+    fs.rmSync(workdir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Runs every strategy against one repository.
+ *
+ * The four rows are the four honest answers to "get me this repo":
+ *
+ * - **git clone** — the baseline, and the only other row that ends with history.
+ * - **git clone --depth=1** — the usual "but you can make clone fast" reply.
+ *   It is fast, and it leaves you without the history you cloned for.
+ * - **git0** — tarball, extracted as it streams.
+ * - **git0 --history** — tarball first, history attached afterwards. Its
+ *   *time to files* is the row above; its *time to history* is where it lands
+ *   relative to `git clone`.
+ *
+ * @param repo - `owner/repo` to measure.
+ * @returns One measurement per strategy.
+ */
+async function benchmarkRepo(repo: string): Promise<Measurement[]> {
+  const url = `https://github.com/${repo}`;
+  const name = repo.split('/')[1];
+  const github = new GithubAPI();
+
+  const results: Measurement[] = [];
+
+  results.push(
+    await measure('git clone', repo, async workdir => {
+      const dir = path.join(workdir, name);
+      await run('git', ['clone', '--quiet', url, dir]);
+      return { dir };
+    })
+  );
+
+  results.push(
+    await measure('git clone --depth=1', repo, async workdir => {
+      const dir = path.join(workdir, name);
+      await run('git', ['clone', '--quiet', '--depth=1', url, dir]);
+      return { dir };
+    })
+  );
+
+  results.push(
+    await measure('git0', repo, async workdir => {
+      process.chdir(workdir);
+      const dir = await github.downloadRepo(url);
+      return { dir };
+    })
+  );
+
+  results.push(
+    await measure('git0 --history', repo, async workdir => {
+      process.chdir(workdir);
+      const dir = await github.downloadRepo(url);
+      // Started once the files exist, exactly as the CLI does it — the caller
+      // stops the "time to files" clock before this is awaited.
+      return { dir, history: attachGitHistory(dir, url) };
+    })
+  );
+
+  return results;
+}
+
+/**
+ * Entry point: measures every named repository and prints one table each.
+ */
+async function main(): Promise<void> {
+  const repos = process.argv.slice(2).filter(arg => !arg.startsWith('--'));
+  const cwd = process.cwd();
+
+  for (const repo of repos.length ? repos : DEFAULT_REPOS) {
+    console.log(`\n### ${repo}\n`);
+    const results = await benchmarkRepo(repo);
+    process.chdir(cwd);
+    console.log(formatTable(results));
+  }
+}
+
+main();