git0 0.2.99 → 0.3.0

package/src/download.ts

@@ -29,6 +29,156 @@ export function getAvailableDirectoryName(basePath: string): string {
   }
 }
 
+/**
+ * Cleans a repository-relative sub-path into the form the tarball uses:
+ * forward slashes, no leading or trailing separator, no `.` segments.
+ *
+ * Every sub-path eventually becomes a prefix match against archive entry names
+ * and then a path joined onto the extraction directory, so this is also the
+ * gate that keeps a crafted path from escaping that directory: a `..` segment
+ * is rejected outright rather than normalized away, because the only honest
+ * reading of `packages/../../etc` in a "download this folder" argument is that
+ * something is wrong with it.
+ *
+ * @param raw - Sub-path as typed or parsed out of a URL; `null`/empty means
+ *   "the whole repository".
+ * @returns The normalized sub-path, or `''` for the whole repository.
+ * @throws When the path contains a `..` segment.
+ *
+ * @example
+ * normalizeSubPath('/.continue/agents/'); // → '.continue/agents'
+ * normalizeSubPath(null);                 // → ''
+ * normalizeSubPath('../../etc');          // throws
+ */
+export function normalizeSubPath(raw?: string | null): string {
+  if (!raw) return '';
+
+  const segments = raw
+    .replace(/\\/g, '/')
+    .split('/')
+    .filter(segment => segment.length > 0 && segment !== '.');
+
+  if (segments.includes('..')) {
+    throw new Error(`Invalid path "${raw}" — ".." segments are not allowed.`);
+  }
+
+  return segments.join('/');
+}
+
+/**
+ * Builds the `tar` entry filter that keeps only a sub-path of the archive.
+ *
+ * GitHub wraps every tarball in one top-level directory named after the commit
+ * (`owner-repo-abc1234/`), so the first segment of each entry name is dropped
+ * before comparing. The filter runs in tar's *parser*, ahead of the unpacker's
+ * `strip`, which is what makes filtering by the repository-relative path
+ * possible at all — and what makes it cheap: a filtered-out entry is skipped in
+ * the stream and never reaches the disk, so downloading one folder of a large
+ * repository writes one folder.
+ *
+ * @param subPath - Normalized sub-path; `''` keeps everything.
+ * @returns A predicate suitable for `tar.x({ filter })`.
+ *
+ * @example
+ * const keep = subPathFilter('src/lib');
+ * keep('react-abc123/src/lib/index.ts'); // → true
+ * keep('react-abc123/src/library.ts');   // → false — prefix, not a path segment
+ */
+export function subPathFilter(subPath: string): (entryPath: string) => boolean {
+  if (!subPath) return () => true;
+
+  const prefix = `${subPath}/`;
+
+  return (entryPath: string) => {
+    const relative = entryPath
+      .replace(/\\/g, '/')
+      .split('/')
+      .slice(1)
+      .join('/')
+      .replace(/\/+$/, '');
+
+    return relative === subPath || relative.startsWith(prefix);
+  };
+}
+
+/**
+ * Moves an extracted sub-path up to the root of the extraction directory, so
+ * `git0 owner/repo/tree/main/packages/ui` leaves the contents of `ui/` in the
+ * target folder rather than `packages/ui/` nested inside it.
+ *
+ * Done after extraction rather than with a larger `tar` `strip` on purpose: the
+ * right strip depth depends on whether the sub-path names a file or a folder,
+ * which a `owner/repo/some/path` shorthand does not say. Hoisting reads that
+ * off the disk instead of guessing, and costs one rename — the files never move
+ * across a filesystem, because the staging directory is a sibling of the target.
+ *
+ * @param extractPath - Directory the tarball was extracted into.
+ * @param subPath - Normalized sub-path that was extracted.
+ * @throws When the sub-path is not present in the repository.
+ *
+ * @example
+ * // extractPath/packages/ui/{package.json,src} → extractPath/{package.json,src}
+ * hoistSubPath(extractPath, 'packages/ui');
+ */
+export function hoistSubPath(extractPath: string, subPath: string): void {
+  if (!subPath) return;
+
+  const landed = path.join(extractPath, subPath);
+  if (!fs.existsSync(landed)) {
+    throw new Error(
+      `"${subPath}" was not found in this repository — check the path and the branch.`
+    );
+  }
+
+  // Park the payload outside the target before clearing the wrapper directories,
+  // otherwise removing `packages/` would take `packages/ui` with it.
+  const staging = fs.mkdtempSync(path.join(path.dirname(extractPath), '.git0-hoist-'));
+  const parked = path.join(staging, 'payload');
+
+  try {
+    fs.renameSync(landed, parked);
+    fs.rmSync(path.join(extractPath, subPath.split('/')[0]), { recursive: true, force: true });
+
+    if (fs.statSync(parked).isDirectory()) {
+      for (const child of fs.readdirSync(parked)) {
+        fs.renameSync(path.join(parked, child), path.join(extractPath, child));
+      }
+    } else {
+      fs.renameSync(parked, path.join(extractPath, path.basename(subPath)));
+    }
+  } finally {
+    fs.rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+/**
+ * The folder name a sub-path download should default to.
+ *
+ * The repository name is the wrong default here — downloading
+ * `debate-ai.com/.continue/agents` into a folder called `debate-ai.com` claims
+ * to hold a site and holds two config files. The last segment of the path is
+ * what the user asked for, except when the path names a *file*, where the
+ * enclosing folder is the meaningful name and the file keeps its own.
+ *
+ * @param subPath - Normalized sub-path.
+ * @param type - `'blob'` or `'tree'` when a GitHub URL said which; omitted for
+ *   the `owner/repo/some/path` shorthand, which is treated as a folder.
+ * @returns The folder name, or `undefined` to fall back to the repository name.
+ *
+ * @example
+ * subPathDirName('packages/ui', 'tree');              // → 'ui'
+ * subPathDirName('.continue/agents/x.yaml', 'blob');  // → 'agents'
+ * subPathDirName('readme.md', 'blob');                // → undefined (repo name)
+ */
+export function subPathDirName(subPath: string, type?: string): string | undefined {
+  if (!subPath) return undefined;
+
+  const segments = subPath.split('/');
+  if (type === 'blob') segments.pop();
+
+  return segments.pop();
+}
+
 /**
  * Streams a GitHub tarball response directly into a `tar` extractor.
  *
@@ -36,18 +186,27 @@ export function getAvailableDirectoryName(basePath: string): string {
  * tarball (e.g. `owner-repo-abc1234/`) so files land directly in
  * `extractPath`.
  *
+ * When `subPath` is set, entries outside it are dropped as they are parsed —
+ * they are never written, so a partial download really is partial.
+ *
  * @param res - The `ReadableStream` body from the GitHub API response.
  * @param extractPath - Absolute directory to extract into (must already exist).
+ * @param subPath - Normalized repository-relative path to limit extraction to;
+ *   `''` extracts the whole repository.
  * @returns Promise that resolves when extraction is complete.
  *
  * @internal
  */
-async function streamTarball(res: ReadableStream, extractPath: string): Promise<void> {
+async function streamTarball(
+  res: ReadableStream,
+  extractPath: string,
+  subPath = ''
+): Promise<void> {
   const { Readable } = await import('stream');
   const nodeStream = Readable.fromWeb(res);
   await new Promise<void>((resolve, reject) => {
     nodeStream
-      .pipe(tar.x({ C: extractPath, strip: 1 }))
+      .pipe(tar.x({ C: extractPath, strip: 1, filter: subPathFilter(subPath) }))
       .on('finish', resolve)
       .on('error', reject);
   });
@@ -77,23 +236,44 @@ async function streamToFile(res: ReadableStream, dest: string): Promise<void> {
  * Downloads a GitHub repository tarball and extracts it into a local directory.
  *
  * The function first attempts to download the `master` branch; if that request
- * returns an error it retries with `main`. The extracted directory name is
- * derived from the repository name, with a numeric suffix appended when the
- * target already exists (see {@link getAvailableDirectoryName}).
+ * returns an error it retries with `main`. A `ref` from a deep GitHub URL
+ * (`/tree/<branch>/…`) is used as-is and skips that fallback. The extracted
+ * directory name is derived from the repository — or from the sub-path, when
+ * one is given — with a numeric suffix appended when the target already exists
+ * (see {@link getAvailableDirectoryName}).
+ *
+ * `subPath` limits the download to one folder or file of the repository. GitHub
+ * serves the whole tarball either way, but the entries outside the sub-path are
+ * discarded in the stream rather than written, and what is kept is hoisted to
+ * the root of the target folder (see {@link hoistSubPath}).
  *
  * @param callGithub - Pre-configured `grab` instance bound to the GitHub API.
  * @param repo - GitHub URL (`https://github.com/owner/repo`) or `owner/repo`.
- * @param targetDir - Optional custom folder name; defaults to the repo name.
+ * @param targetDir - Optional custom folder name; defaults to the repo name, or
+ *   to the sub-path's own name when `subPath` is set.
+ * @param options.subPath - Repository-relative folder or file to limit the
+ *   download to.
+ * @param options.subPathType - `'blob'` or `'tree'` when the URL said which.
+ * @param options.ref - Branch, tag or commit to download.
  * @returns Absolute path of the directory the repo was extracted into.
  *
  * @example
  * const dir = await downloadRepo(callGithub, 'https://github.com/facebook/react');
  * // → '/current/working/dir/react'
+ *
+ * @example
+ * // Just one folder of a large repo:
+ * const dir = await downloadRepo(callGithub, 'facebook/react', null, {
+ *   subPath: 'packages/react-dom',
+ *   subPathType: 'tree',
+ * });
+ * // → '/current/working/dir/react-dom'
  */
 export async function downloadRepo(
   callGithub: Function,
   repo: string,
-  targetDir: string | null = null
+  targetDir: string | null = null,
+  options: { subPath?: string | null; subPathType?: string; ref?: string } = {}
 ): Promise<string> {
   const parsed = gitUrlParse(repo);
 
@@ -103,22 +283,44 @@ export async function downloadRepo(
     parsed.owner = parsed.owner.split('/').slice(-1)[0];
   }
 
-  const defaultDir = path.resolve(process.cwd(), targetDir?.length ? targetDir : parsed.name);
+  const subPath = normalizeSubPath(options.subPath);
+  const defaultName =
+    (targetDir?.length ? targetDir : undefined) ??
+    subPathDirName(subPath, options.subPathType) ??
+    parsed.name;
+
+  const defaultDir = path.resolve(process.cwd(), defaultName);
   const extractPath = getAvailableDirectoryName(defaultDir);
 
   fs.mkdirSync(extractPath, { recursive: true });
 
-  console.log(chalk.blue(`📦 Downloading ${parsed.name} into ${path.basename(extractPath)}...`));
+  const what = subPath ? `${parsed.name}/${subPath}` : parsed.name;
+  console.log(chalk.blue(`📦 Downloading ${what} into ${path.basename(extractPath)}...`));
 
-  const defaultBranch = (parsed as any).default_branch || 'master';
+  const requestedRef = options.ref || (parsed as any).ref || '';
+  const defaultBranch = requestedRef || (parsed as any).default_branch || 'master';
   const tarballUrl = `/repos/${parsed.owner}/${parsed.name}/tarball/${defaultBranch}`;
-  const params = { onStream: (res: ReadableStream) => streamTarball(res, extractPath) };
+  const params = { onStream: (res: ReadableStream) => streamTarball(res, extractPath, subPath) };
 
   let response = await callGithub(tarballUrl, params);
+  // Only guess at the branch when the caller did not name one.
+  if (response.error && !requestedRef) {
+    response = await callGithub(tarballUrl.replace(/\/master$/, '/main'), params);
+  }
+
+  // A failed request leaves an empty directory behind. Saying so beats letting
+  // the next step report a missing sub-path, or the install step report a
+  // project with no files in it.
   if (response.error) {
-    response = await callGithub(tarballUrl.replace('/master', '/main'), params);
+    fs.rmSync(extractPath, { recursive: true, force: true });
+    throw new Error(
+      `Could not download ${parsed.owner}/${parsed.name}` +
+        `${requestedRef ? ` at ${requestedRef}` : ''}: ${response.error}`
+    );
   }
 
+  hoistSubPath(extractPath, subPath);
+
   return extractPath;
 }
 

package/src/github-api.ts

@@ -6,6 +6,92 @@ import { getCurrentPlatform } from './platform.js';
 import { categorizeReleasesByPlatform, filterReleasesByPlatform } from './releases.js';
 import { downloadRepo, downloadPackage } from './download.js';
 
+/**
+ * What the CLI was pointed at: a repository, and optionally one path inside it.
+ */
+export interface RepoTarget {
+  /** Repository owner. */
+  owner: string;
+  /** Repository name. */
+  name: string;
+  /** Canonical `https://github.com/owner/name` URL. */
+  href: string;
+  /** Branch, tag or commit named by the URL, or `''`. */
+  ref: string;
+  /** Repository-relative path to limit the download to, or `''`. */
+  subPath: string;
+  /** `'blob'` when the path names a file, `'tree'` when a folder, `''` when unstated. */
+  subPathType: string;
+}
+
+/**
+ * Parses a GitHub reference — including one that points *into* a repository —
+ * into the pieces a download needs.
+ *
+ * The deep forms are the ones people actually have in the clipboard. A link
+ * copied out of the GitHub UI carries the branch and the path
+ * (`/tree/main/packages/ui`, `/blob/main/src/index.ts`), and that is exactly
+ * the scope the user is asking for, so it is read rather than thrown away and
+ * the whole repository downloaded instead. The `owner/repo/path` shorthand is
+ * handled separately from `git-url-parse`, which reads every leading segment of
+ * a plain path as part of the owner.
+ *
+ * @param query - URL, shorthand, or an unrelated search string.
+ * @returns A {@link RepoTarget}, or `false` when the input is not a GitHub
+ *   reference (i.e. it should be treated as a search query).
+ *
+ * @example
+ * parseTarget('https://github.com/debate/debate-ai.com/blob/master/.continue/agents/new-config.yaml');
+ * // → { owner: 'debate', name: 'debate-ai.com', ref: 'master',
+ * //     subPath: '.continue/agents/new-config.yaml', subPathType: 'blob', … }
+ *
+ * @example
+ * parseTarget('facebook/react/packages/react-dom');
+ * // → { owner: 'facebook', name: 'react', subPath: 'packages/react-dom', subPathType: '', … }
+ *
+ * parseTarget('react starter'); // → false
+ */
+export function parseTarget(query: string): RepoTarget | false {
+  const looksLikeUrl =
+    query.includes('github.com') ||
+    query.startsWith('git@github.com:') ||
+    query.startsWith('https://') ||
+    query.startsWith('git://');
+
+  if (!looksLikeUrl) {
+    // `owner/repo`, optionally followed by a path into the repository.
+    const shorthand = query.match(/^([\w-]+)\/([\w.-]+)(?:\/(.+))?$/);
+    if (!shorthand) return false;
+
+    const [, owner, name, subPath = ''] = shorthand;
+    return {
+      owner,
+      name,
+      href: `https://github.com/${owner}/${name}`,
+      ref: '',
+      subPath,
+      subPathType: '',
+    };
+  }
+
+  const parsed = gitUrlParse(query) as any;
+  if (!parsed?.owner || !parsed?.name) return false;
+
+  // Forks arrive with the fork chain in `owner`, e.g. "upstream/fork".
+  const owner = parsed.owner.includes('/')
+    ? parsed.owner.split('/').slice(-1)[0]
+    : parsed.owner;
+
+  return {
+    owner,
+    name: parsed.name,
+    href: `https://github.com/${owner}/${parsed.name}`,
+    ref: parsed.ref || '',
+    subPath: parsed.filepath || '',
+    subPathType: parsed.filepathtype || '',
+  };
+}
+
 /**
  * GitHub API client for searching repositories, downloading source tarballs,
  * and fetching release assets.
@@ -66,14 +152,20 @@ class GithubAPI {
    *
    * @param repo      - Full GitHub URL or `owner/repo` shorthand.
    * @param targetDir - Optional extraction folder name; defaults to the repo name.
+   * @param options   - `subPath` / `subPathType` / `ref`, as produced by
+   *   {@link parseTarget}, to download one folder of the repository.
    * @returns Absolute path of the extracted project directory.
    *
    * @example
    * const dir = await github.downloadRepo('https://github.com/vitejs/vite');
    * // → '/current/working/dir/vite'
    */
-  async downloadRepo(repo: string, targetDir: string | null = null): Promise<string> {
-    return downloadRepo(this.callGithub, repo, targetDir);
+  async downloadRepo(
+    repo: string,
+    targetDir: string | null = null,
+    options: { subPath?: string | null; subPathType?: string; ref?: string } = {}
+  ): Promise<string> {
+    return downloadRepo(this.callGithub, repo, targetDir, options);
   }
 
   /**
@@ -177,6 +269,20 @@ class GithubAPI {
    *
    * github.parseURL('just a search query'); // → false
    */
+  /**
+   * Parses a GitHub reference into owner, repo, ref and sub-path.
+   *
+   * Delegates to {@link parseTarget}. Prefer this over {@link parseURL} for
+   * anything that downloads — it is the one that understands `/tree/` and
+   * `/blob/` links.
+   *
+   * @param query - URL, `owner/repo[/path]` shorthand, or a search string.
+   * @returns A {@link RepoTarget}, or `false` for a search string.
+   */
+  parseTarget(query: string): RepoTarget | false {
+    return parseTarget(query);
+  }
+
   parseURL(query: string): ReturnType<typeof gitUrlParse> | false {
     if (
       query.includes('github.com') ||

package/src/history.ts

@@ -0,0 +1,225 @@
+import chalk from 'chalk';
+import { execFile } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { promisify } from 'util';
+
+const run = promisify(execFile);
+
+/**
+ * Runs `git` with an argument array — never a shell string, so a repository URL
+ * can never be read as extra arguments or as shell syntax.
+ *
+ * @param args - Arguments passed straight to `git`.
+ * @param cwd - Working directory for the command.
+ * @returns The command's stdout, trimmed.
+ * @throws Whatever `execFile` throws on a non-zero exit.
+ *
+ * @internal
+ */
+async function git(args: string[], cwd?: string): Promise<string> {
+  const { stdout } = await run('git', args, { cwd, maxBuffer: 1024 * 1024 * 64 });
+  return stdout.trim();
+}
+
+/**
+ * Returns true when a usable `git` binary is on `PATH`.
+ *
+ * git0's whole point is working without one, so every history feature is gated
+ * on this rather than assuming it.
+ *
+ * @example
+ * if (!(await gitAvailable())) console.log('install git first');
+ */
+export async function gitAvailable(): Promise<boolean> {
+  try {
+    await git(['--version']);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Rejects anything that is not a plain scheme-qualified remote.
+ *
+ * The URLs git0 builds are assembled from a parsed owner and repo name, so this
+ * is belt-and-braces — but a value that reaches `git clone` decides what gets
+ * executed and where it is written, and `ext::<command>`, a bare local path or
+ * a leading `-` are the classic ways to turn a clone into something else.
+ * `file://` is allowed because it is an ordinary remote and it is what the
+ * tests clone from; the schemes that hand git a command to run are not.
+ *
+ * @param url - Remote URL to check.
+ * @returns The URL, unchanged.
+ * @throws When the URL is not an http(s), git or file remote.
+ *
+ * @internal
+ */
+function assertSafeRemote(url: string): string {
+  if (!/^(https?|git|file):\/\/[^\s]+$/.test(url)) {
+    throw new Error(`Refusing to clone from "${url}" — expected an https:// repository URL.`);
+  }
+  return url;
+}
+
+/**
+ * Attaches a repository's full Git history to an already-extracted source
+ * folder, turning it into a normal working clone.
+ *
+ * **Why this is not just `git clone`.** A clone is one serial operation: the
+ * remote counts and packs every object in the repository's history, sends the
+ * pack, and only then writes a working tree you can run. Nothing can start
+ * until all of it finishes. git0 splits that in two — the codeload tarball is a
+ * pre-made, already-compressed snapshot of one commit that extracts *while it
+ * downloads*, so files exist and `bun install` can start almost immediately;
+ * the history is then fetched into `.git` alongside the install, which is
+ * mostly waiting on the network and on npm anyway. The end state is identical
+ * to a clone. The difference is that the thing you were trying to do started at
+ * the beginning rather than at the end. See `benchmark/` for the numbers.
+ *
+ * The clone lands in a temporary directory first and is renamed into place only
+ * once it succeeds, so an interrupted download leaves no half-written `.git`
+ * for the next command to trip over.
+ *
+ * @param extractPath - Directory holding the already-extracted source.
+ * @param repoUrl - `https://github.com/owner/repo` to fetch history from.
+ * @param options.mirror - Use `--mirror` instead of `--bare`, keeping every ref
+ *   (notes, remote-tracking refs, pull refs) rather than branches and tags.
+ * @param options.ref - Branch or tag the source snapshot came from, so the
+ *   working tree is matched against the right commit.
+ * @returns Path to the created `.git` directory.
+ * @throws When `git` is missing, the clone fails, or `.git` already exists.
+ *
+ * @example
+ * await attachGitHistory('/work/react', 'https://github.com/facebook/react');
+ * // /work/react is now a normal git repo: `git log` works, `git status` is clean
+ */
+export async function attachGitHistory(
+  extractPath: string,
+  repoUrl: string,
+  options: { mirror?: boolean; ref?: string } = {}
+): Promise<string> {
+  assertSafeRemote(repoUrl);
+
+  const gitDir = path.join(extractPath, '.git');
+  if (fs.existsSync(gitDir)) {
+    throw new Error(`${gitDir} already exists — not overwriting it.`);
+  }
+  if (!(await gitAvailable())) {
+    throw new Error('git is not installed, so the history cannot be downloaded.');
+  }
+
+  const staging = fs.mkdtempSync(path.join(path.dirname(extractPath), '.git0-history-'));
+  const cloned = path.join(staging, 'repo.git');
+
+  try {
+    await git(['clone', options.mirror ? '--mirror' : '--bare', '--quiet', repoUrl, cloned]);
+    fs.renameSync(cloned, gitDir);
+  } catch (error) {
+    fs.rmSync(staging, { recursive: true, force: true });
+    throw error;
+  }
+  fs.rmSync(staging, { recursive: true, force: true });
+
+  // A bare clone has no working tree and no remote-tracking refs. Both are
+  // needed for the extracted files to read as a normal checkout.
+  await git(['config', '--local', '--bool', 'core.bare', 'false'], extractPath);
+  await git(['config', '--local', '--bool', 'core.logallrefupdates', 'true'], extractPath);
+  await git(
+    ['config', '--local', 'remote.origin.fetch', '+refs/heads/*:refs/remotes/origin/*'],
+    extractPath
+  );
+  await git(['fetch', '--quiet', 'origin'], extractPath).catch(() => {});
+
+  if (options.ref) {
+    // The tarball came from this ref, so HEAD has to agree with what is on disk.
+    await git(['symbolic-ref', 'HEAD', `refs/heads/${options.ref}`], extractPath).catch(() => {});
+  }
+
+  // Populates the index from HEAD without touching the files the tarball wrote,
+  // which is what makes `git status` come back clean instead of showing the
+  // whole repository as deleted.
+  await git(['reset', '--mixed', '--quiet', 'HEAD'], extractPath).catch(() => {});
+
+  return gitDir;
+}
+
+/**
+ * Clones only a repository's history — no working files — into `<name>.git`.
+ *
+ * This is the `git clone --mirror` shape: the directory holds what would
+ * normally live inside `.git`, placed at its root. `--mirror` is the default
+ * here rather than `--bare` because the reason to want history without files is
+ * almost always to keep or move it, and `--bare` quietly leaves out notes and
+ * remote-tracking refs.
+ *
+ * @param repoUrl - `https://github.com/owner/repo` to mirror.
+ * @param targetDir - Directory to create; must not already exist.
+ * @param options.bare - Use `--bare` (branches and tags only) instead.
+ * @returns The created directory's path.
+ * @throws When `git` is missing, the target exists, or the clone fails.
+ *
+ * @example
+ * await cloneHistoryOnly('https://github.com/facebook/react', '/work/react.git');
+ * // → '/work/react.git' — inspect it with:
+ * //   git --git-dir=/work/react.git log --all --oneline
+ */
+export async function cloneHistoryOnly(
+  repoUrl: string,
+  targetDir: string,
+  options: { bare?: boolean } = {}
+): Promise<string> {
+  assertSafeRemote(repoUrl);
+
+  if (fs.existsSync(targetDir)) {
+    throw new Error(`${targetDir} already exists — not overwriting it.`);
+  }
+  if (!(await gitAvailable())) {
+    throw new Error('git is not installed, so the history cannot be downloaded.');
+  }
+
+  await git(['clone', options.bare ? '--bare' : '--mirror', '--quiet', repoUrl, targetDir]);
+  return targetDir;
+}
+
+/**
+ * Kicks off {@link attachGitHistory} without blocking the caller, and reports
+ * how it went when it lands.
+ *
+ * This is the lazy half of the feature. It is started *after* extraction has
+ * finished — the files are on disk, so the IDE can open them and the installer
+ * can run — and then left to overlap with those. History is the one part of a
+ * clone nothing is waiting on: nobody needs `git log` to run `bun install`.
+ *
+ * Failures are reported and swallowed. A missing `git`, a private repository or
+ * a dropped connection should cost the user their history, not the project they
+ * just downloaded and are already working in.
+ *
+ * @param extractPath - Directory holding the extracted source.
+ * @param repoUrl - Repository to fetch history from.
+ * @param options - Forwarded to {@link attachGitHistory}.
+ * @returns A promise the caller can await at the very end, which never rejects.
+ *
+ * @example
+ * const history = attachGitHistoryLazily(dir, url); // returns immediately
+ * await installDependencies(dir);                   // runs alongside it
+ * await history;                                    // settle before exiting
+ */
+export function attachGitHistoryLazily(
+  extractPath: string,
+  repoUrl: string,
+  options: { mirror?: boolean; ref?: string } = {}
+): Promise<void> {
+  console.log(chalk.blue('⏳ Fetching .git history in the background...'));
+
+  return attachGitHistory(extractPath, repoUrl, options).then(
+    () => {
+      console.log(chalk.green('✅ Git history attached — `git log` is ready.'));
+    },
+    (error: any) => {
+      console.log(chalk.yellow(`⚠️  Could not attach git history: ${error.message}`));
+      console.log(chalk.gray('   The downloaded source is unaffected.'));
+    }
+  );
+}