git0 0.2.98 → 0.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "git0",
     "description": "CLI tool to search GitHub repositories, download source & releases for your system, and instantly set up, then install dependencies and open code editor.",
-    "version": "0.2.98",
+    "version": "0.3.0",
     "author": "vtempest",
     "scripts": {
         "build": "bun build src/cli.ts --outdir dist --target node --format esm --sourcemap",
@@ -9,6 +9,7 @@
         "test:ci": "bun test --reporter=junit --reporter-outfile=./junit.xml --coverage --coverage-reporter=lcov --coverage-dir=./coverage",
         "docs": "cd docs-config && bun run build:docs",
         "demo": "bun src/cli.ts react template",
+        "bench": "bun benchmark/tarball-vs-clone.bench.ts",
         "publish:npm": "npm version patch && npm publish --access public",
         "test:watch": "vitest",
         "coverage": "vitest run --coverage"
@@ -45,7 +46,7 @@
         "url": "git+https://github.com/OpenSourceAGI/dev-tools-starter-agent.git",
         "directory": "packages/git0-repo-downloader"
     },
-    "homepage": "https://github.com/OpenSourceAGI/dev-tools-starter-agent/tree/master/packages/git0-repo-downloader",
+    "homepage": "https://git0.js.org",
     "devDependencies": {
         "@vitest/coverage-v8": "^4.1.0",
         "vitest": "^4.1.0"

package/readme.md

@@ -4,6 +4,7 @@
 
 <!-- template-git-repo:badges:start -->
 <p align="center">
+    <a href="https://git0.js.org"><img height="20px" src="https://img.shields.io/badge/App-blueviolet?style=for-the-badge&logo=googlechrome&logoColor=white" alt="Website" /></a>
     <a href="https://starterdocs.vtempest.workers.dev/docs/packages/git0-repo-downloader"><img src="https://img.shields.io/badge/Docs-blue?logo=ReadTheDocs&logoColor=white" alt="Documentation" /></a>
     <br />
     <a href="https://github.com/OpenSourceAGI/dev-tools-starter-agent/stargazers"><img src="https://img.shields.io/github/stars/OpenSourceAGI/dev-tools-starter-agent" alt="GitHub Stars" /></a>
@@ -33,6 +34,8 @@
 
 CLI tool to search GitHub repositories, download source & releases for your system, and instantly set up, then install dependencies and open code editor.
 
+**🌐 [git0.js.org](https://git0.js.org)**
+
 ## 🚀 Installation
 
 ```bash
@@ -55,6 +58,8 @@ bun install -g git0
 - **Smart IDE integration** - automatically opens projects in your preferred editor
 - **Cross-platform support** - works on Windows, macOS, and Linux
 - **Conflict resolution** - handles directory naming conflicts automatically
+- **Partial paths** - paste a `/tree/` or `/blob/` link and download just that folder or file
+- **Optional `.git` history** - `--history` attaches the full history *after* the source is already on disk
 - **Faster than git** - skips `.git` history and uncompresses while downloading
 
 ## 🎯 Usage
@@ -74,6 +79,119 @@ git0 facebook/react
 # Use git0 without installing, (only node needed)
 # (copy this line into your project's readme to help others setup)
 npx git0 facebook/react
+
+# Download only one folder — paste the GitHub link as you copied it
+g https://github.com/facebook/react/tree/main/packages/react-dom
+
+# ...or one file
+g https://github.com/debate/debate-ai.com/blob/master/.continue/agents/new-config.yaml
+
+# Same thing, without a URL
+git0 facebook/react/packages/react-dom
+git0 facebook/react --path=packages/react-dom
+
+# A specific branch, tag or commit
+git0 facebook/react --branch=v18.2.0
+
+# With the full .git history attached after the download
+git0 facebook/react --history
+
+# History only — no working files at all
+git0 facebook/react --history-only
+```
+
+### Options
+
+| Flag | What it does |
+| --- | --- |
+| `--path=<path>` | Download only that folder or file of the repository |
+| `--branch=<ref>` | Download a branch, tag or commit instead of the default branch |
+| `--history` | Also fetch the full `.git` history, in the background |
+| `--history-only` | Clone only the history — no working files |
+| `--mirror` | Keep every ref (notes, remote-tracking) when cloning history |
+
+## 📁 Partial Paths
+
+Copy a link out of the GitHub UI and git0 downloads exactly what the link points
+at, not the repository around it:
+
+```bash
+g https://github.com/facebook/react/tree/main/packages/react-dom
+# → ./react-dom/ — the contents of that folder, at the root
+```
+
+The branch and the path are both read off the URL. Entries outside the path are
+discarded as the tarball streams, so they are never written to disk, and what is
+kept is lifted to the root of the target folder — you get `react-dom/`, not
+`react/packages/react-dom/`.
+
+The folder is named after the path rather than the repository, because that is
+what you asked for. A `/blob/` link to a single file downloads that one file into
+its enclosing folder's name. Pass a second argument, or `--path` with any repo
+reference, if you'd rather name it yourself:
+
+```bash
+git0 facebook/react --path=packages/react-dom my-copy
+```
+
+## 🕐 Downloading With `.git` History
+
+By default git0 downloads a tarball — the source at one commit, no history. That
+is what makes it quick. When you *do* want the history, `--history` gets you both
+without giving up the speed:
+
+```bash
+git0 facebook/react --history
+```
+
+The source tarball lands first. The history is fetched **after** the archive has
+finished unzipping, in the background, while the IDE opens and dependencies
+install. You end up in exactly the state `git clone` would have left you in — a
+working tree with a full `.git` beside it, `git log` and `git blame` working,
+`git status` clean — except you started working several seconds earlier.
+
+**Why the lazy order is faster.** `git clone` is one serial operation: the remote
+counts and packs every object in the project's history, sends the pack, and only
+then writes files you can run. Nothing can start until all of it finishes. A
+GitHub tarball is a pre-made, cached, already-compressed snapshot of one commit,
+so git0 pipes it straight into a `tar` extractor — files are being written while
+the rest is still downloading. And history is the one part of a clone that
+nothing on the critical path is waiting for: `bun install` does not need `git
+log`. So it is fetched last, overlapping the install rather than blocking it.
+
+There is a benchmark for this in [`benchmark/`](./benchmark) — it measures
+*time until the project can run*, separately from *time until history is
+available*, for `git clone`, `git clone --depth=1`, git0, and `git0 --history`:
+
+```bash
+bun run bench facebook/react
+```
+
+### History Only
+
+To take the history and none of the working files — for a backup, a mirror, or
+to move a repository between hosts:
+
+```bash
+git0 facebook/react --history-only
+# → ./react.git/ — HEAD, config, objects/, refs/, packed-refs
+```
+
+That directory holds what normally lives inside `.git`, placed at its root: all
+the commits, branches and tags, no editable files. Read it without checking
+anything out, or restore a normal working copy from it:
+
+```bash
+git --git-dir=react.git log --all --oneline
+git clone react.git react
+```
+
+`--history-only` uses a bare clone (branches and tags). Add `--mirror` for every
+ref Git can fetch — notes, remote-tracking refs and the rest — which is what you
+want when the point is a complete backup:
+
+```bash
+git0 facebook/react --history-only --mirror
 ```
 
 ### Supported Project Types
@@ -104,11 +222,12 @@ git0 automatically detects and opens projects in your preferred IDE:
 
 ### What Happens After Download
 
-1. **Repository is downloaded** to your current directory
+1. **Repository is downloaded** to your current directory — only the requested path, if you named one
 2. **Project type is detected** automatically
 3. **Dependencies are installed** based on project type
 4. **IDE is launched** automatically (if available)
 5. **Development server starts** (for Node.js projects)
+6. **`.git` history is attached** in the background, if you passed `--history`
 
 If a directory with the same name exists, git0 automatically appends a number (e.g., `react-2`, `react-3`).
 

package/src/args.ts

@@ -0,0 +1,58 @@
+import chalk from 'chalk';
+
+/**
+ * The flags git0 accepts, and what they mean.
+ *
+ * Kept to a handful on purpose — the common case is one argument and no flags.
+ */
+export interface Flags {
+  /** `--path=<p>` — limit the download to one folder or file of the repo. */
+  path?: string;
+  /** `--branch=<ref>` — download a branch, tag or commit other than the default. */
+  branch?: string;
+  /** `--history` — also attach the full `.git` history, in the background. */
+  history: boolean;
+  /** `--history-only` — clone only the history, no working files. */
+  historyOnly: boolean;
+  /** `--mirror` — use `--mirror` rather than `--bare` when cloning history. */
+  mirror: boolean;
+}
+
+/**
+ * Splits `process.argv` into positional arguments and flags.
+ *
+ * Deliberately hand-rolled rather than pulled in: git0's surface is one
+ * positional argument and five flags, and the argument itself is frequently a
+ * URL, which most parsers are keen to mangle.
+ *
+ * @param argv - Arguments after the node binary and script name.
+ * @returns The positional arguments and the parsed flags.
+ *
+ * @example
+ * parseArgs(['facebook/react', '--history', '--path=packages/react-dom']);
+ * // → { positional: ['facebook/react'],
+ * //     flags: { history: true, path: 'packages/react-dom', … } }
+ */
+export function parseArgs(argv: string[]): { positional: string[]; flags: Flags } {
+  const positional: string[] = [];
+  const flags: Flags = { history: false, historyOnly: false, mirror: false };
+
+  for (const arg of argv) {
+    if (!arg.startsWith('--')) {
+      positional.push(arg);
+      continue;
+    }
+
+    const [name, ...rest] = arg.slice(2).split('=');
+    const value = rest.join('=');
+
+    if (name === 'path') flags.path = value;
+    else if (name === 'branch' || name === 'ref') flags.branch = value;
+    else if (name === 'history' || name === 'git') flags.history = true;
+    else if (name === 'history-only' || name === 'git-only') flags.historyOnly = true;
+    else if (name === 'mirror') flags.mirror = true;
+    else console.log(chalk.yellow(`Ignoring unknown flag: ${arg}`));
+  }
+
+  return { positional, flags };
+}

package/src/cli.ts

@@ -1,10 +1,14 @@
 #!/usr/bin/env node
 import inquirer from 'inquirer';
 import chalk from 'chalk';
-import GithubAPI from './github-api.js';
+import path from 'path';
+import GithubAPI, { type RepoTarget } from './github-api.js';
 import { openInIDE } from './ide.js';
 import { installDependencies } from './install.js';
 import { showPackageMenu } from './package-menu.js';
+import { attachGitHistoryLazily, cloneHistoryOnly } from './history.js';
+import { parseArgs, type Flags } from './args.js';
+import { getAvailableDirectoryName } from './download.js';
 import { printLogo } from './utils.js';
 import type { SearchResult } from './types.js';
 
@@ -17,19 +21,71 @@ const Github = new GithubAPI({ debug: false });
  * The IDE launch is deferred 500 ms so the extraction can finish writing files
  * before the editor tries to index them.
  *
- * @param repo       - GitHub URL (`https://…`) or `owner/repo` shorthand.
+ * With `--history`, the `.git` directory is fetched *after* extraction and runs
+ * alongside the IDE launch and the dependency install rather than in front of
+ * them — see {@link attachGitHistoryLazily} for why that ordering is the whole
+ * point.
+ *
+ * @param target     - Parsed repository reference, including any sub-path.
  * @param folderPath - Optional name for the extraction directory; defaults to
- *   the repository name.
+ *   the repository name, or the sub-path's name when one is given.
+ * @param flags      - Parsed CLI flags.
  *
  * @example
- * await downloadRepoAndSetup('https://github.com/vitejs/vite');
+ * await downloadRepoAndSetup(parseTarget('vitejs/vite') as RepoTarget);
  * // Downloads vite/, opens it in the first available IDE, runs bun install
  */
-async function downloadRepoAndSetup(repo: string, folderPath: string | null = null): Promise<void> {
+async function downloadRepoAndSetup(
+  target: RepoTarget,
+  folderPath: string | null = null,
+  flags: Flags = { history: false, historyOnly: false, mirror: false }
+): Promise<void> {
   printLogo();
-  const extractPath = await Github.downloadRepo(repo, folderPath);
+
+  const ref = flags.branch || target.ref;
+  const extractPath = await Github.downloadRepo(target.href, folderPath, {
+    subPath: flags.path ?? target.subPath,
+    subPathType: flags.path ? '' : target.subPathType,
+    ref,
+  });
+
+  // Started here, not awaited here: the files are on disk, so everything below
+  // can proceed while the history downloads.
+  const history = flags.history
+    ? attachGitHistoryLazily(extractPath, target.href, { mirror: flags.mirror, ref })
+    : Promise.resolve();
+
   setTimeout(() => openInIDE(extractPath), 500);
   await installDependencies(extractPath);
+  await history;
+}
+
+/**
+ * Handles `--history-only`: clones the repository's history into `<name>.git`
+ * and downloads no working files at all.
+ *
+ * @param target - Parsed repository reference.
+ * @param flags  - Parsed CLI flags.
+ *
+ * @internal
+ */
+async function downloadHistoryOnly(target: RepoTarget, flags: Flags): Promise<void> {
+  printLogo();
+
+  const targetDir = getAvailableDirectoryName(path.resolve(process.cwd(), `${target.name}.git`));
+  console.log(chalk.blue(`📦 Cloning ${target.name} history into ${path.basename(targetDir)}...`));
+
+  try {
+    await cloneHistoryOnly(target.href, targetDir, { bare: !flags.mirror });
+    console.log(chalk.green(`✅ History-only clone at ${targetDir}`));
+    console.log(chalk.white('  Read the log without checking anything out:'));
+    console.log(chalk.gray(`  git --git-dir="${targetDir}" log --all --oneline`));
+    console.log(chalk.white('  Or restore a working copy from it:'));
+    console.log(chalk.gray(`  git clone "${targetDir}" ${target.name}`));
+  } catch (error: any) {
+    console.error(chalk.red('❌ History clone failed:'), error.message);
+    process.exit(1);
+  }
 }
 
 /**
@@ -61,12 +117,19 @@ function formatRepoChoice(repo: SearchResult): string {
  * source code, or both when a repository has release assets.
  *
  * @param selectedRepo - The repository the user chose in the search results.
+ * @param flags        - Parsed CLI flags, forwarded to the source download.
  *
  * @internal
  */
-async function handleRepoDownload(selectedRepo: SearchResult): Promise<void> {
+async function handleRepoDownload(selectedRepo: SearchResult, flags: Flags): Promise<void> {
+  const target = Github.parseTarget(selectedRepo.url);
+  if (!target) {
+    console.log(chalk.yellow(`Could not parse repository URL: ${selectedRepo.url}`));
+    return;
+  }
+
   if (!selectedRepo.hasReleases && !selectedRepo.hasCompatibleReleases) {
-    await downloadRepoAndSetup(selectedRepo.url);
+    await downloadRepoAndSetup(target, null, flags);
     return;
   }
 
@@ -89,7 +152,7 @@ async function handleRepoDownload(selectedRepo: SearchResult): Promise<void> {
     );
   }
   if (downloadChoice === 'source' || downloadChoice === 'both') {
-    await downloadRepoAndSetup(selectedRepo.url);
+    await downloadRepoAndSetup(target, null, flags);
   }
 }
 
@@ -97,9 +160,10 @@ async function handleRepoDownload(selectedRepo: SearchResult): Promise<void> {
  * CLI entry point for the `git0` / `g` / `gg` commands.
  *
  * **Flow:**
- * 1. Parse `process.argv` for a search query or direct repo URL.
+ * 1. Parse `process.argv` into flags and a search query or direct repo URL.
  * 2. If the argument looks like a GitHub URL or `owner/repo`, download it
- *    directly — optionally into a custom folder (second CLI argument).
+ *    directly — optionally into a custom folder (second positional argument),
+ *    limited to a sub-path, and optionally with `.git` history.
  * 3. Otherwise, search GitHub and present an interactive list.
  * 4. After the user picks a repo, offer package vs. source download when
  *    releases are available.
@@ -111,23 +175,40 @@ async function handleRepoDownload(selectedRepo: SearchResult): Promise<void> {
  * //   git0 facebook/react
  * //   git0 https://github.com/vitejs/vite my-vite-copy
  *
+ * // Just one folder of it:
+ * //   git0 https://github.com/facebook/react/tree/main/packages/react-dom
+ * //   git0 facebook/react --path=packages/react-dom
+ *
+ * // With git history, fetched after the source is already on disk:
+ * //   git0 facebook/react --history
+ * //   git0 facebook/react --history-only
+ *
  * // Search:
  * //   git0 react template starter
  */
 async function main(): Promise<void> {
   printLogo();
 
-  const args = process.argv.slice(2);
-  if (!args.length) {
-    console.log(chalk.yellow('Usage: git0 <github-url | owner/repo | search-query>'));
+  const { positional, flags } = parseArgs(process.argv.slice(2));
+  if (!positional.length) {
+    console.log(chalk.yellow('Usage: git0 <github-url | owner/repo[/path] | search-query>'));
+    console.log(chalk.gray('  --path=<path>   download only that folder or file'));
+    console.log(chalk.gray('  --branch=<ref>  download a branch, tag or commit'));
+    console.log(chalk.gray('  --history       also fetch .git history, in the background'));
+    console.log(chalk.gray('  --history-only  clone only the history, no working files'));
+    console.log(chalk.gray('  --mirror        keep every ref when cloning history'));
     process.exit(1);
   }
 
-  const query = args.join(' ');
-  const parsed = Github.parseURL(query);
+  const query = positional.join(' ');
+  const target = Github.parseTarget(query);
 
-  if (parsed && parsed.owner && parsed.name) {
-    await downloadRepoAndSetup(parsed.href, args[1] ?? null);
+  if (target) {
+    if (flags.historyOnly) {
+      await downloadHistoryOnly(target, flags);
+      return;
+    }
+    await downloadRepoAndSetup(target, positional[1] ?? null, flags);
     return;
   }
 
@@ -144,7 +225,10 @@ async function main(): Promise<void> {
     choices: results.map(repo => ({ name: formatRepoChoice(repo), value: repo })),
   });
 
-  await handleRepoDownload(selectedRepo);
+  await handleRepoDownload(selectedRepo, flags);
 }
 
-main();
+main().catch((error: any) => {
+  console.error(chalk.red(`❌ ${error.message}`));
+  process.exit(1);
+});