just-git 1.1.11 → 1.2.0

package/README.md

@@ -18,11 +18,10 @@ npm install just-git
 
 ### Client
 
-Provide any `FileSystem` implementation and call `git.exec()`:
-
 ```ts
-import { createGit } from "just-git";
+import { createGit, MemoryFileSystem } from "just-git";
 
+const fs = new MemoryFileSystem();
 const git = createGit({ identity: { name: "Alice", email: "alice@example.com" } });
 
 await git.exec("git init", { fs, cwd: "/repo" });
@@ -31,7 +30,7 @@ await git.exec('git commit -m "initial commit"', { fs, cwd: "/repo" });
 await git.exec("git log --oneline", { fs, cwd: "/repo" });
 ```
 
-Tokenization handles single and double quotes. Pass `env` as a plain object when needed (e.g. `GIT_AUTHOR_NAME`).
+`MemoryFileSystem` is a minimal in-memory filesystem included with just-git. You can also provide your own implementation of the `FileSystem` interface (e.g. wrapping `node:fs/promises`). Tokenization handles single and double quotes. Pass `env` as a plain object when needed (e.g. `GIT_AUTHOR_NAME`).
 
 For a full virtual shell with file I/O, pipes, and scripting, pair with [just-bash](https://github.com/vercel-labs/just-bash):
 
@@ -81,14 +80,15 @@ Uses web-standard `Request`/`Response` — works with Bun, Hono, Cloudflare Work
 
 `createGit(options?)` accepts:
 
-| Option          | Description                                                                                                                                                                                                                                        |
-| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `identity`      | Author/committer override. With `locked: true`, always wins over env vars and git config. Without `locked`, acts as a fallback.                                                                                                                    |
-| `credentials`   | `(url) => HttpAuth \| null` callback for Smart HTTP transport auth.                                                                                                                                                                                |
-| `disabled`      | `GitCommandName[]` of subcommands to block (e.g. `["push", "rebase"]`).                                                                                                                                                                            |
-| `network`       | `{ allowed?: string[], fetch?: FetchFunction }` to restrict HTTP access and/or provide a custom `fetch`. `allowed` accepts hostnames (`"github.com"`) or URL prefixes (`"https://github.com/myorg/"`). Set to `false` to block all network access. |
-| `hooks`         | `GitHooks` config object with named callback properties. See [Hooks](#hooks).                                                                                                                                                                      |
-| `resolveRemote` | `(url) => GitRepo \| null` callback for cross-VFS remote resolution. See [Multi-agent collaboration](#multi-agent-collaboration).                                                                                                                  |
+| Option          | Description                                                                                                                                                                                                                                                |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `identity`      | Author/committer override. With `locked: true`, always wins over env vars and git config. Without `locked`, acts as a fallback.                                                                                                                            |
+| `credentials`   | `(url) => HttpAuth \| null` callback for Smart HTTP transport auth.                                                                                                                                                                                        |
+| `disabled`      | `GitCommandName[]` of subcommands to block (e.g. `["push", "rebase"]`).                                                                                                                                                                                    |
+| `network`       | `{ allowed?: string[], fetch?: FetchFunction }` to restrict HTTP access and/or provide a custom `fetch`. `allowed` accepts hostnames (`"github.com"`) or URL prefixes (`"https://github.com/myorg/"`). Set to `false` to block all network access.         |
+| `config`        | `{ locked?, defaults? }` config overrides. `locked` values always win over `.git/config`; `defaults` supply fallbacks when a key is absent. Keys are dotted config names (e.g. `"push.default"`, `"merge.ff"`). See [Config overrides](#config-overrides). |
+| `hooks`         | `GitHooks` config object with named callback properties. See [Hooks](#hooks).                                                                                                                                                                              |
+| `resolveRemote` | `(url) => GitRepo \| null` callback for cross-VFS remote resolution. See [Multi-agent collaboration](#multi-agent-collaboration).                                                                                                                          |
 
 ```ts
 const git = createGit({
@@ -96,6 +96,10 @@ const git = createGit({
   credentials: async (url) => ({ type: "bearer", token: "ghp_..." }),
   disabled: ["rebase"],
   network: false, // no HTTP access
+  config: {
+    locked: { "push.default": "nothing" },
+    defaults: { "merge.ff": "only" },
+  },
 });
 ```
 
@@ -159,6 +163,30 @@ const git = createGit({
 
 Available pre-hooks: `preCommit`, `commitMsg`, `mergeMsg`, `preMergeCommit`, `preCheckout`, `prePush`, `preFetch`, `preClone`, `prePull`, `preRebase`, `preReset`, `preClean`, `preRm`, `preCherryPick`, `preRevert`, `preStash`. Available post-hooks: `postCommit`, `postMerge`, `postCheckout`, `postPush`, `postFetch`, `postClone`, `postPull`, `postReset`, `postClean`, `postRm`, `postCherryPick`, `postRevert`, `postStash`. Low-level events: `onRefUpdate`, `onRefDelete`, `onObjectWrite`. Command-level: `beforeCommand`, `afterCommand`.
 
+## Config overrides
+
+Control git config values at the operator level, without touching `.git/config`. Works like the `identity` option — `locked` values always win, `defaults` act as fallbacks.
+
+```ts
+const git = createGit({
+  config: {
+    locked: {
+      "push.default": "nothing", // agent must always specify a refspec
+      "merge.conflictstyle": "diff3", // always show base in conflict markers
+    },
+    defaults: {
+      "pull.rebase": "true", // default to rebase-on-pull (agent can change)
+      "merge.ff": "only", // default to ff-only (agent can change)
+    },
+  },
+});
+```
+
+- **`locked`** — values that take absolute precedence. The agent can run `git config set` (the write succeeds on the VFS), but the locked value always wins on every read. Useful for enforcing policies.
+- **`defaults`** — fallback values when a key is absent from `.git/config`. The agent _can_ override these with `git config set`. Useful for sensible defaults without restricting the agent.
+
+Applied transparently via `getConfigValue()` — all commands respect overrides automatically. Any dotted config key works (e.g. `"merge.ff"`, `"push.default"`, `"pull.rebase"`, `"merge.conflictstyle"`, `"branch.autoSetupMerge"`).
+
 ## Repo module
 
 `just-git/repo` provides a high-level API for working with repositories programmatically — reading commits, diffing trees, creating objects, and merging — without going through command execution. This is what you use inside hooks (all hook payloads include `repo: GitRepo`) and anywhere else you need direct repo access.
@@ -253,7 +281,7 @@ See [CLI.md](docs/CLI.md) for full usage details.
 | Command                           | Flags / options                                                                                                                                                                                                                                                                |
 | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `init [<dir>]`                    | `--bare`, `--initial-branch`                                                                                                                                                                                                                                                   |
-| `clone <repo> [<dir>]`            | `--bare`, `-b <branch>`                                                                                                                                                                                                                                                        |
+| `clone <repo> [<dir>]`            | `--bare`, `-b <branch>`, `--depth`                                                                                                                                                                                                                                             |
 | `blame <file>`                    | `-L <start>,<end>`, `-l`/`--long`, `-e`/`--show-email`, `-s`/`--suppress`, `-p`/`--porcelain`, `--line-porcelain`                                                                                                                                                              |
 | `add <paths>`                     | `.`, `--all`/`-A`, `--update`/`-u`, `--force`/`-f`, `-n`/`--dry-run`, glob pathspecs                                                                                                                                                                                           |
 | `rm <paths>`                      | `--cached`, `-r`, `-f`, `-n`/`--dry-run`, glob pathspecs                                                                                                                                                                                                                       |
@@ -275,10 +303,10 @@ See [CLI.md](docs/CLI.md) for full usage details.
 | `rebase <upstream>`               | `--onto <newbase>`, `--abort`, `--continue`, `--skip`                                                                                                                                                                                                                          |
 | `stash`                           | `push`, `pop`, `apply`, `list`, `drop`, `show`, `clear`, `-m`, `-u`/`--include-untracked`, `stash@{N}`                                                                                                                                                                         |
 | `remote`                          | `add`, `remove`/`rm`, `rename`, `set-url`, `get-url`, `-v`                                                                                                                                                                                                                     |
-| `config`                          | `get`, `set`, `unset`, `list`, `--list`/`-l`, `--unset`                                                                                                                                                                                                                        |
-| `fetch [<remote>] [<refspec>...]` | `--all`, `--tags`, `--prune`/`-p`                                                                                                                                                                                                                                              |
+| `config`                          | `get`, `set`, `unset`, `list`, `--list`/`-l`, `--unset`, `--get-all`, `--add`                                                                                                                                                                                                  |
+| `fetch [<remote>] [<refspec>...]` | `--all`, `--tags`, `--prune`/`-p`, `--depth`, `--unshallow`                                                                                                                                                                                                                    |
 | `push [<remote>] [<refspec>...]`  | `--force`/`-f`, `-u`/`--set-upstream`, `--all`, `--tags`, `--delete`/`-d`                                                                                                                                                                                                      |
-| `pull [<remote>] [<branch>]`      | `--ff-only`, `--no-ff`, `--rebase`/`-r`, `--no-rebase`                                                                                                                                                                                                                         |
+| `pull [<remote>] [<branch>]`      | `--ff-only`, `--no-ff`, `--rebase`/`-r`, `--no-rebase`, `--depth`, `--unshallow`                                                                                                                                                                                               |
 | `bisect`                          | `start`, `bad`/`good`/`new`/`old`, `skip`, `reset`, `log`, `replay`, `run`, `terms`, `visualize`/`view`, `--term-new`/`--term-old`, `--no-checkout`, `--first-parent`                                                                                                          |
 | `clean`                           | `-f`, `-n`/`--dry-run`, `-d`, `-x`, `-X`, `-e`/`--exclude`                                                                                                                                                                                                                     |
 | `reflog`                          | `show [<ref>]`, `exists`, `-n`/`--max-count`                                                                                                                                                                                                                                   |

package/dist/{hooks-OMCbhUGB.d.ts → hooks-Boa35Qx_.d.ts}

@@ -186,6 +186,8 @@ interface GitContext extends GitRepo {
     networkPolicy?: NetworkPolicy | false;
     /** Resolves remote URLs to GitRepos on potentially different VFS instances. */
     resolveRemote?: RemoteResolver;
+    /** Operator-provided config overrides (locked values + defaults). */
+    configOverrides?: ConfigOverrides;
 }
 type DiffStatus = "added" | "deleted" | "modified";
 interface TreeDiffEntry {
@@ -220,6 +222,21 @@ interface IdentityOverride {
     email: string;
     locked?: boolean;
 }
+/**
+ * Operator-level config overrides. Applied on every `getConfigValue()` read:
+ *
+ * - `locked` values take absolute precedence — the agent cannot override
+ *   them via `git config`. Writes still succeed on the VFS (so the agent
+ *   doesn't see errors), but the locked value always wins on read.
+ * - `defaults` supply fallback values when a key is absent from
+ *   `.git/config`. The agent *can* override these with `git config`.
+ *
+ * Keys are dotted config names, e.g. `"push.default"`, `"merge.ff"`.
+ */
+interface ConfigOverrides {
+    locked?: Record<string, string>;
+    defaults?: Record<string, string>;
+}
 type FetchFunction = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 interface NetworkPolicy {
     /**
@@ -341,7 +358,7 @@ interface PostPullEvent {
     readonly repo: GitRepo;
     readonly remote: string;
     readonly branch: string | null;
-    readonly strategy: "up-to-date" | "fast-forward" | "three-way";
+    readonly strategy: "up-to-date" | "fast-forward" | "three-way" | "rebase";
     readonly commitHash: ObjectId | null;
 }
 interface PreResetEvent {
@@ -480,4 +497,4 @@ interface GitHooks {
 }
 declare function composeGitHooks(...hookSets: (GitHooks | undefined)[]): GitHooks;
 
-export { type Identity as $, type AfterCommandEvent as A, type BeforeCommandEvent as B, type CredentialProvider as C, type PrePullEvent as D, type ExecResult as E, type FileSystem as F, type GitHooks as G, type HttpAuth as H, type IdentityOverride as I, type PrePushEvent as J, type PreRebaseEvent as K, type PreResetEvent as L, type MergeMsgEvent as M, type NetworkPolicy as N, type ObjectStore as O, type PostCheckoutEvent as P, type PreRevertEvent as Q, type RemoteResolver as R, type PreRmEvent as S, type PreStashEvent as T, type RefDeleteEvent as U, type RefEntry as V, type RefUpdateEvent as W, type Rejection as X, composeGitHooks as Y, isRejection as Z, type ObjectId as _, type RefStore as a, type TreeDiffEntry as a0, type Commit as a1, type ObjectType as a2, type RawObject as a3, type Ref as a4, type FetchFunction as b, type GitContext as c, type CommitMsgEvent as d, type FileStat as e, type GitRepo as f, type ObjectWriteEvent as g, type PostCherryPickEvent as h, type PostCleanEvent as i, type PostCloneEvent as j, type PostCommitEvent as k, type PostFetchEvent as l, type PostMergeEvent as m, type PostPullEvent as n, type PostPushEvent as o, type PostResetEvent as p, type PostRevertEvent as q, type PostRmEvent as r, type PostStashEvent as s, type PreCheckoutEvent as t, type PreCherryPickEvent as u, type PreCleanEvent as v, type PreCloneEvent as w, type PreCommitEvent as x, type PreFetchEvent as y, type PreMergeCommitEvent as z };
+export { isRejection as $, type AfterCommandEvent as A, type BeforeCommandEvent as B, type CredentialProvider as C, type PreFetchEvent as D, type ExecResult as E, type FileSystem as F, type GitContext as G, type HttpAuth as H, type IdentityOverride as I, type PreMergeCommitEvent as J, type PrePullEvent as K, type PrePushEvent as L, type MergeMsgEvent as M, type NetworkPolicy as N, type ObjectId as O, type PostCheckoutEvent as P, type PreRebaseEvent as Q, type RemoteResolver as R, type PreResetEvent as S, type PreRevertEvent as T, type PreRmEvent as U, type PreStashEvent as V, type RefDeleteEvent as W, type RefEntry as X, type RefUpdateEvent as Y, type Rejection as Z, composeGitHooks as _, type GitRepo as a, type Identity as a0, type TreeDiffEntry as a1, type Commit as a2, type ObjectType as a3, type RawObject as a4, type Ref as a5, type GitHooks as b, type ObjectStore as c, type RefStore as d, type ConfigOverrides as e, type FetchFunction as f, type FileStat as g, type CommitMsgEvent as h, type ObjectWriteEvent as i, type PostCherryPickEvent as j, type PostCleanEvent as k, type PostCloneEvent as l, type PostCommitEvent as m, type PostFetchEvent as n, type PostMergeEvent as o, type PostPullEvent as p, type PostPushEvent as q, type PostResetEvent as r, type PostRevertEvent as s, type PostRmEvent as t, type PostStashEvent as u, type PreCheckoutEvent as v, type PreCherryPickEvent as w, type PreCleanEvent as x, type PreCloneEvent as y, type PreCommitEvent as z };

package/dist/index.d.ts

@@ -1,5 +1,53 @@
-import { F as FileSystem, E as ExecResult, G as GitHooks, C as CredentialProvider, I as IdentityOverride, N as NetworkPolicy, R as RemoteResolver, O as ObjectStore, a as RefStore, b as FetchFunction, c as GitContext } from './hooks-OMCbhUGB.js';
-export { A as AfterCommandEvent, B as BeforeCommandEvent, d as CommitMsgEvent, e as FileStat, f as GitRepo, H as HttpAuth, M as MergeMsgEvent, g as ObjectWriteEvent, P as PostCheckoutEvent, h as PostCherryPickEvent, i as PostCleanEvent, j as PostCloneEvent, k as PostCommitEvent, l as PostFetchEvent, m as PostMergeEvent, n as PostPullEvent, o as PostPushEvent, p as PostResetEvent, q as PostRevertEvent, r as PostRmEvent, s as PostStashEvent, t as PreCheckoutEvent, u as PreCherryPickEvent, v as PreCleanEvent, w as PreCloneEvent, x as PreCommitEvent, y as PreFetchEvent, z as PreMergeCommitEvent, D as PrePullEvent, J as PrePushEvent, K as PreRebaseEvent, L as PreResetEvent, Q as PreRevertEvent, S as PreRmEvent, T as PreStashEvent, U as RefDeleteEvent, V as RefEntry, W as RefUpdateEvent, X as Rejection, Y as composeGitHooks, Z as isRejection } from './hooks-OMCbhUGB.js';
+import { O as ObjectId, G as GitContext, a as GitRepo, F as FileSystem, E as ExecResult, b as GitHooks, C as CredentialProvider, I as IdentityOverride, N as NetworkPolicy, R as RemoteResolver, c as ObjectStore, d as RefStore, e as ConfigOverrides, f as FetchFunction, g as FileStat } from './hooks-Boa35Qx_.js';
+export { A as AfterCommandEvent, B as BeforeCommandEvent, h as CommitMsgEvent, H as HttpAuth, M as MergeMsgEvent, i as ObjectWriteEvent, P as PostCheckoutEvent, j as PostCherryPickEvent, k as PostCleanEvent, l as PostCloneEvent, m as PostCommitEvent, n as PostFetchEvent, o as PostMergeEvent, p as PostPullEvent, q as PostPushEvent, r as PostResetEvent, s as PostRevertEvent, t as PostRmEvent, u as PostStashEvent, v as PreCheckoutEvent, w as PreCherryPickEvent, x as PreCleanEvent, y as PreCloneEvent, z as PreCommitEvent, D as PreFetchEvent, J as PreMergeCommitEvent, K as PrePullEvent, L as PrePushEvent, Q as PreRebaseEvent, S as PreResetEvent, T as PreRevertEvent, U as PreRmEvent, V as PreStashEvent, W as RefDeleteEvent, X as RefEntry, Y as RefUpdateEvent, Z as Rejection, _ as composeGitHooks, $ as isRejection } from './hooks-Boa35Qx_.js';
+
+/** Depth value that represents "full history" (used by --unshallow). */
+declare const INFINITE_DEPTH = 2147483647;
+/** Shallow boundary delta: what to add/remove from `.git/shallow`. */
+interface ShallowUpdate {
+    /** Commits to add to the shallow boundary. */
+    shallow: ObjectId[];
+    /** Commits to remove from the shallow boundary (now have full parents). */
+    unshallow: ObjectId[];
+}
+/**
+ * Read the set of shallow boundary commit hashes from `.git/shallow`.
+ * Returns an empty set if the file doesn't exist or is empty.
+ */
+declare function readShallowCommits(ctx: GitContext): Promise<Set<ObjectId>>;
+/**
+ * Write the shallow boundary set to `.git/shallow`.
+ * Removes the file if the set is empty (repo is no longer shallow).
+ */
+declare function writeShallowCommits(ctx: GitContext, hashes: Set<ObjectId>): Promise<void>;
+/** Check whether a repo is shallow (has a non-empty `.git/shallow` file). */
+declare function isShallowRepo(ctx: GitContext): Promise<boolean>;
+/**
+ * Merge a `ShallowUpdate` into the current `.git/shallow` file.
+ * Adds new shallow commits, removes unshallowed ones, persists the result.
+ */
+declare function applyShallowUpdates(ctx: GitContext, updates: ShallowUpdate, existing?: Set<ObjectId>): Promise<void>;
+/**
+ * Compute the shallow boundary for a depth-limited fetch.
+ *
+ * BFS from `wants` up to `depth` levels of commit parents. Commits
+ * at exactly depth N (whose parents would exceed the limit) become
+ * the new shallow boundary. Any commit in `clientShallows` that is
+ * now within the traversal depth gets unshallowed.
+ *
+ * The returned `shallow` set is the new boundary — commits whose
+ * parents the client should NOT expect to have. The `unshallow` set
+ * is commits that were previously shallow but are now within depth.
+ */
+declare function computeShallowBoundary(repo: GitRepo, wants: ObjectId[], depth: number, clientShallows: Set<ObjectId>): Promise<ShallowUpdate>;
+
+/** Options for shallow/depth-limited fetches. */
+interface ShallowFetchOptions {
+    /** Maximum commit depth from the wanted refs. */
+    depth?: number;
+    /** Commits currently in the client's `.git/shallow` file. */
+    existingShallows?: Set<ObjectId>;
+}
 
 /** Options for subcommand execution (mirrors just-bash's CommandExecOptions). */
 interface CommandExecOptions {
@@ -48,6 +96,11 @@ interface GitOptions {
      * and go through this store instead (e.g. SQLite-backed).
      */
     refStore?: RefStore;
+    /**
+     * Config overrides. `locked` values always win over `.git/config`;
+     * `defaults` supply fallbacks when a key is absent from config.
+     */
+    config?: ConfigOverrides;
 }
 /**
  * Bundle of operator-level extensions threaded into command handlers
@@ -62,6 +115,7 @@ interface GitExtensions {
     resolveRemote?: RemoteResolver;
     objectStore?: ObjectStore;
     refStore?: RefStore;
+    configOverrides?: ConfigOverrides;
 }
 /** Simplified context for {@link Git.exec}. */
 interface ExecContext {
@@ -75,6 +129,8 @@ declare class Git {
     private blocked;
     private hooks;
     private inner;
+    private locks;
+    private withLock;
     constructor(options?: GitOptions);
     /**
      * Run a git command from a string.
@@ -98,6 +154,38 @@ declare class Git {
 declare function tokenizeCommand(input: string): string[];
 declare function createGit(options?: GitOptions): Git;
 
+/**
+ * Minimal in-memory filesystem implementing the just-git {@link FileSystem}
+ * interface. Supports files, directories, and symlinks.
+ *
+ * ```ts
+ * const fs = new MemoryFileSystem({ "/repo/README.md": "# Hello" });
+ * ```
+ */
+declare class MemoryFileSystem implements FileSystem {
+    private data;
+    constructor(initialFiles?: Record<string, string | Uint8Array>);
+    private ensureParents;
+    private resolve;
+    private resolveParent;
+    readFile(path: string): Promise<string>;
+    readFileBuffer(path: string): Promise<Uint8Array>;
+    writeFile(path: string, content: string | Uint8Array): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FileStat>;
+    lstat(path: string): Promise<FileStat>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    readdir(path: string): Promise<string[]>;
+    rm(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+    readlink(path: string): Promise<string>;
+    symlink(target: string, linkPath: string): Promise<void>;
+}
+
 /**
  * Walk up from `startPath` looking for a git repository.
  * Checks for both normal repos (`.git/` subdirectory) and bare repos
@@ -106,4 +194,4 @@ declare function createGit(options?: GitOptions): Git;
  */
 declare function findRepo(fs: FileSystem, startPath: string): Promise<GitContext | null>;
 
-export { type CommandContext, type CommandExecOptions, CredentialProvider, type ExecContext, ExecResult, FetchFunction, FileSystem, Git, type GitCommandName, GitContext, type GitExtensions, GitHooks, type GitOptions, IdentityOverride, NetworkPolicy, ObjectStore, RefStore, RemoteResolver, createGit, findRepo, tokenizeCommand };
+export { type CommandContext, type CommandExecOptions, ConfigOverrides, CredentialProvider, type ExecContext, ExecResult, FetchFunction, FileStat, FileSystem, Git, type GitCommandName, GitContext, type GitExtensions, GitHooks, type GitOptions, GitRepo, INFINITE_DEPTH, IdentityOverride, MemoryFileSystem, NetworkPolicy, ObjectStore, RefStore, RemoteResolver, type ShallowFetchOptions, type ShallowUpdate, applyShallowUpdates, computeShallowBoundary, createGit, findRepo, isShallowRepo, readShallowCommits, tokenizeCommand, writeShallowCommits };