computer/git: clone full history, and fill three CLI gaps

clone defaulted to depth 1. That made it fast, but it quietly cost
the caller their history: pushing such a clone somewhere else sent
only the single commit it had fetched, reported success, and left a
remote whose tip hash matched while every earlier commit was
missing. A content diff against that remote passes, so nothing
surfaces the loss until someone looks for a parent that is not
there. Default to full history and leave the shallow case to an
explicit --depth, where the caller is choosing speed knowingly.

Three smaller gaps go with it. cat-file grew -t and -s, which
readObject already had the type and size for. log grew --format and
its --pretty alias over the commonly scripted placeholders, leaving
an unrecognized one as written so it shows up in the output rather
than vanishing. help grew a per-command form; it previously ignored
its argument and reprinted the list, which left no way to discover
a command's flags except guessing and reading the exit code.

Author: aron-cf

.changeset/git-full-history-clone.md

@@ -0,0 +1,11 @@
+---
+"@cloudflare/computer": minor
+---
+
+`git clone` now fetches the full history by default instead of a single commit. The shallow default was faster, but a caller who cloned a repository and then pushed it somewhere else sent only the one commit it had fetched: the push reported success and the remote's tip matched, while every earlier commit was missing. Pass `--depth` to ask for a shallow clone when the history genuinely is not needed.
+
+`git cat-file` gained `-t` and `-s` to report an object's type and size, alongside the existing `-p`. Exactly one of the three is required, as in real git.
+
+`git log` gained `--format` and its alias `--pretty`, expanding the placeholders `%H`, `%h`, `%s`, `%b`, `%an`, `%ae`, `%ad`, `%cn`, `%ce`, `%cd`, and `%%`, plus the named format `oneline`. A placeholder outside that set is left as written so it is visible in the output rather than silently dropped.
+
+`git help <command>` now prints the usage line for one command instead of ignoring its argument and reprinting the full list. Only the flags this wrapper accepts are listed, so the output says what works here rather than what real git would take.

docs/13_git_interface.md

@@ -44,6 +44,10 @@ clean       fetch         reset         rev-parse     switch
                                         update-ref
 ```
 
+`git help` lists these, and `git help <command>` prints the usage line for
+one of them, covering only the flags this wrapper accepts. Asking for a
+command that is not supported reports that rather than reprinting the list.
+
 Global options accepted before the subcommand:
 
 - **`-C <path>`** — run the subcommand as though invoked from
@@ -412,6 +416,7 @@ ws.git.log({
 | `-n <N>` | `depth` |
 | `-<N>` (e.g. `-1`, `-5`) | `depth` |
 | `--oneline` | (CLI formatter) |
+| `--format=<spec>` / `--pretty=<spec>` | (CLI formatter) |
 | `<ref>` (positional) | `ref` |
 
 The positional `<ref>` accepts revision suffixes (`HEAD~2`,
@@ -423,6 +428,12 @@ blocks; `--oneline` collapses each entry to `<short-oid>
 message, tree, parent, author, committer) so callers can
 format their own way.
 
+`--format=<spec>` (and its alias `--pretty=<spec>`) expands the
+placeholders `%H`, `%h`, `%s`, `%b`, `%an`, `%ae`, `%ad`, `%cn`, `%ce`,
+`%cd`, and `%%`, plus the named format `oneline`. A placeholder outside
+that set is left as written, so an unsupported one is visible in the
+output rather than silently dropped.
+
 *Not mapped:* `--graph`, `--all`, `--since`, `--until`,
 `-p`, `--stat`, `--follow`, `--reverse`.
 
@@ -545,7 +556,7 @@ ws.git.clone({
   dir?: string,
   ref?: string,
   paths?: string[],         // partial checkout only
-  depth?: number,           // default 1
+  depth?: number,           // default: full history
   singleBranch?: boolean,
   noTags?: boolean,
   headers?: Record<string, string>,
@@ -564,6 +575,11 @@ ws.git.clone({
 | `<url>` (positional) | `url` |
 | `<dir>` (positional) | `dir` |
 
+Clone fetches the full history unless `--depth` asks otherwise. A shallow
+clone is faster, but it can only push the commits it actually fetched: the
+push succeeds and the remote's tip matches, while every earlier commit is
+missing. Ask for a shallow clone when the history genuinely is not needed.
+
 When `<dir>` is omitted, the CLI derives it from the last path
 segment of the URL, stripping a trailing `.git` — `git clone
 https://github.com/owner/repo.git` lands in `./repo`, matching
@@ -869,19 +885,21 @@ readback that the typed API serves better directly.
 ### `cat-file`
 
 ```
-git cat-file -p <oid>[:<path>]
+git cat-file (-p|-t|-s) <oid>[:<path>]
 ```
 
 ```ts
 ws.git.catFile({
   dir?: string,
   oid: string,
   filepath?: string,
-}): Promise<{ oid: string; bytes: Uint8Array }>
+}): Promise<{ oid: string; bytes: Uint8Array; type?: string }>
 ```
 
-Supports the `<oid>:<path>` shorthand for tree subreads.
-*Not mapped:* `-t` type, `-s` size, `--batch`.
+Supports the `<oid>:<path>` shorthand for tree subreads. `-p` prints the
+object's bytes, `-t` its type, and `-s` its size in bytes; exactly one of
+the three is required, as in real git.
+*Not mapped:* `--batch`.
 
 ### `update-ref`
 

packages/computer/src/git/cli.test.ts

@@ -1754,11 +1754,11 @@ describe("runGitCli — cat-file", () => {
     });
   });
 
-  it("without -p is an error", async () => {
+  it("without a mode flag is an error", async () => {
     const { client } = fakeClient();
     const res = await runGitCli(client, { argv: ["cat-file", "a".repeat(40)] });
     expect(res.exitCode).toBe(129);
-    expect(res.stderr).toContain("only -p is supported");
+    expect(res.stderr).toContain("one of -p, -t, or -s is required");
   });
 });
 
@@ -2340,3 +2340,110 @@ describe("runGitCli — end-to-end against an in-process Workspace", () => {
     expect(res.stdout).toBe("");
   });
 });
+
+describe("runGitCli — cat-file type and size", () => {
+  it("-t reports the object type", async () => {
+    const { client } = fakeClient(
+      {},
+      {
+        catFile: () => ({
+          oid: "a".repeat(40),
+          bytes: new TextEncoder().encode("hello\n"),
+          type: "commit" as const,
+        }),
+      },
+    );
+    const res = await runGitCli(client, { argv: ["cat-file", "-t", "a".repeat(40)] });
+    expect(res.exitCode).toBe(0);
+    expect(res.stdout).toBe("commit\n");
+  });
+
+  it("-s reports the object size in bytes", async () => {
+    const { client } = fakeClient(
+      {},
+      {
+        catFile: () => ({
+          oid: "a".repeat(40),
+          bytes: new TextEncoder().encode("hello\n"),
+        }),
+      },
+    );
+    const res = await runGitCli(client, { argv: ["cat-file", "-s", "a".repeat(40)] });
+    expect(res.exitCode).toBe(0);
+    expect(res.stdout).toBe("6\n");
+  });
+
+  it("rejects combining -p and -t", async () => {
+    const { client } = fakeClient();
+    const res = await runGitCli(client, { argv: ["cat-file", "-p", "-t", "a".repeat(40)] });
+    expect(res.exitCode).toBe(129);
+    expect(res.stderr).toMatch(/mutually exclusive/);
+  });
+});
+
+describe("runGitCli — help for one command", () => {
+  it("prints usage for a named command", async () => {
+    const { client } = fakeClient();
+    const res = await runGitCli(client, { argv: ["help", "log"] });
+    expect(res.exitCode).toBe(0);
+    expect(res.stdout).toMatch(/^usage: git log /);
+    expect(res.stdout).toMatch(/--oneline/);
+  });
+
+  it("still prints the command list when given no argument", async () => {
+    const { client } = fakeClient();
+    const res = await runGitCli(client, { argv: ["help"] });
+    expect(res.exitCode).toBe(0);
+    expect(res.stdout).toMatch(/Supported workspace git commands/);
+  });
+
+  it("reports an unknown command rather than reprinting the list", async () => {
+    const { client } = fakeClient();
+    const res = await runGitCli(client, { argv: ["help", "rebase"] });
+    expect(res.exitCode).toBe(1);
+    expect(res.stderr).toMatch(/no help available for 'rebase'/);
+  });
+});
+
+describe("runGitCli — log --format", () => {
+  const sample = (oid: string, msg: string): CommitView => ({
+    oid,
+    message: msg,
+    tree: "",
+    parent: [],
+    author: { name: "A", email: "a@x", timestamp: 1_700_000_000, timezoneOffset: 0 },
+    committer: { name: "C", email: "c@x", timestamp: 1_700_000_000, timezoneOffset: 0 },
+  });
+
+  it("expands the common placeholders", async () => {
+    const { client } = fakeClient({}, { log: () => [sample("a".repeat(40), "second")] });
+    const res = await runGitCli(client, { argv: ["log", "--format=%h %s (%an)"] });
+    expect(res.exitCode).toBe(0);
+    expect(res.stdout).toBe("aaaaaaa second (A)\n");
+  });
+
+  it("expands the full hash and the committer separately from the author", async () => {
+    const { client } = fakeClient({}, { log: () => [sample("a".repeat(40), "x")] });
+    const res = await runGitCli(client, { argv: ["log", "--format=%H|%an|%cn"] });
+    expect(res.stdout).toBe(`${"a".repeat(40)}|A|C\n`);
+  });
+
+  it("treats --pretty as an alias and understands the oneline format", async () => {
+    const { client } = fakeClient({}, { log: () => [sample("a".repeat(40), "second")] });
+    const res = await runGitCli(client, { argv: ["log", "--pretty=oneline"] });
+    expect(res.exitCode).toBe(0);
+    expect(res.stdout).toBe("aaaaaaa second\n");
+  });
+
+  it("leaves an unknown placeholder as written", async () => {
+    const { client } = fakeClient({}, { log: () => [sample("a".repeat(40), "x")] });
+    const res = await runGitCli(client, { argv: ["log", "--format=%h %zz"] });
+    expect(res.stdout).toBe("aaaaaaa %zz\n");
+  });
+
+  it("rejects --format combined with --oneline", async () => {
+    const { client } = fakeClient();
+    const res = await runGitCli(client, { argv: ["log", "--oneline", "--format=%h"] });
+    expect(res.exitCode).toBe(129);
+  });
+});