@ac-kit/cmd-git 0.1.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024-2026 Anthony Champagne and contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,36 @@
+# @ac-kit/cmd-git
+
+A typed wrapper over the `git` command-line program — not a reimplementation of
+git.
+
+Wrapping the real binary is the point: it gets credential helpers, SSH agents,
+config precedence, hooks and LFS for free, none of which a from-scratch
+implementation would match. What this adds is a typed signature per subcommand
+and a parser for the output.
+
+```ts
+import { gitRevParse, gitStatusV1Sync } from "@ac-kit/cmd-git";
+
+const head = await gitRevParse("HEAD", {
+  execOptions: { cwd: repository },
+});
+
+// `git status --porcelain=v1`, parsed into entries rather than left as text.
+for (const entry of await gitStatusV1Sync([], { execOptions: { cwd: repository } })) {
+  console.log(entry.path);
+}
+```
+
+Every wrapper takes an optional `AbortSignal` and passes `execOptions` —
+including `cwd`, the repository to run in — straight through to `execFile`. The
+`git` binary is spawned with an argv array, never through a shell, so there is
+no metacharacter interpretation to guard against.
+
+Covers `gitInit`, `gitCheckout`, `gitFetch`, `gitRemoteAdd`, `gitRevParse`,
+`gitSparseCheckoutInit`/`gitSparseCheckoutSet`, and `gitStatusV1Sync`.
+
+Requires `git` on `PATH`; it is not bundled. Node only.
+
+See the
+[generated API docs](https://anthochamp.github.io/node-essentials/api/cmd-git/)
+for the full reference.

package/dist/checkout.d.ts

@@ -0,0 +1,9 @@
+import type { GitCommandOptions } from "./command-options.js";
+/**
+ * Checks out `ref` (a branch, tag, or commit SHA) into the working tree at
+ * `options.execOptions.cwd`.
+ *
+ * @see https://git-scm.com/docs/git-checkout
+ */
+export declare function gitCheckout(ref: string, options?: GitCommandOptions): Promise<void>;
+//# sourceMappingURL=checkout.d.ts.map

package/dist/checkout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout.d.ts","sourceRoot":"","sources":["../src/checkout.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D;;;;;GAKG;AACH,wBAAsB,WAAW,CAChC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CAKf"}

package/dist/checkout.js

@@ -0,0 +1,14 @@
+import { execFileAsync } from "@ac-kit/node";
+/**
+ * Checks out `ref` (a branch, tag, or commit SHA) into the working tree at
+ * `options.execOptions.cwd`.
+ *
+ * @see https://git-scm.com/docs/git-checkout
+ */
+export async function gitCheckout(ref, options) {
+    await execFileAsync("git", ["checkout", "--quiet", ref], {
+        ...options?.execOptions,
+        signal: options?.signal ?? undefined,
+    });
+}
+//# sourceMappingURL=checkout.js.map

package/dist/checkout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout.js","sourceRoot":"","sources":["../src/checkout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAI7C;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAChC,GAAW,EACX,OAA2B;IAE3B,MAAM,aAAa,CAAC,KAAK,EAAE,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,CAAC,EAAE;QACxD,GAAG,OAAO,EAAE,WAAW;QACvB,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,SAAS;KACpC,CAAC,CAAC;AACJ,CAAC"}

package/dist/command-options.d.ts

@@ -0,0 +1,13 @@
+import type { ExecFileOptions } from "node:child_process";
+/** Common options accepted by every git-subcommand wrapper in this package. */
+export type GitCommandOptions = {
+    /** An optional AbortSignal that can be used to abort the operation. */
+    signal?: AbortSignal | null;
+    /**
+     * Additional options to pass to the underlying `execFileAsync` call,
+     * including `cwd` — the git repository to run the command in. Defaults to
+     * `execFileAsync`'s own default (`process.cwd()`) when omitted.
+     */
+    execOptions?: Omit<ExecFileOptions, "signal" | "encoding">;
+};
+//# sourceMappingURL=command-options.d.ts.map

package/dist/command-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-options.d.ts","sourceRoot":"","sources":["../src/command-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAQ1D,+EAA+E;AAC/E,MAAM,MAAM,iBAAiB,GAAG;IAC/B,uEAAuE;IACvE,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAE5B;;;;OAIG;IACH,WAAW,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,GAAG,UAAU,CAAC,CAAC;CAC3D,CAAC"}

package/dist/command-options.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=command-options.js.map

package/dist/command-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-options.js","sourceRoot":"","sources":["../src/command-options.ts"],"names":[],"mappings":""}

package/dist/fetch.d.ts

@@ -0,0 +1,26 @@
+import type { GitCommandOptions } from "./command-options.js";
+export type GitFetchOptions = GitCommandOptions & {
+    /**
+     * Object filter passed to `--filter`, e.g. `"blob:none"` to omit blob objects
+     * until a later checkout needs them.
+     *
+     * @see https://git-scm.com/docs/git-fetch#Documentation/git-fetch.txt---filterltfilter-specgt
+     */
+    filter?: string;
+    /**
+     * Shallow-fetch depth passed to `--depth` — only the history needed to
+     * resolve `refspec` is transferred.
+     *
+     * @see https://git-scm.com/docs/git-fetch#Documentation/git-fetch.txt---depthltdepthgt
+     */
+    depth?: number;
+};
+/**
+ * Fetches `refspec` (a branch, tag, or full commit SHA the remote exposes,
+ * reachable or not) from `remote` into the object store at
+ * `options.execOptions.cwd`.
+ *
+ * @see https://git-scm.com/docs/git-fetch
+ */
+export declare function gitFetch(remote: string, refspec: string, options?: GitFetchOptions): Promise<void>;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../src/fetch.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,MAAM,MAAM,eAAe,GAAG,iBAAiB,GAAG;IACjD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAC7B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,eAAe,GACvB,OAAO,CAAC,IAAI,CAAC,CAgBf"}

package/dist/fetch.js

@@ -0,0 +1,23 @@
+import { execFileAsync } from "@ac-kit/node";
+/**
+ * Fetches `refspec` (a branch, tag, or full commit SHA the remote exposes,
+ * reachable or not) from `remote` into the object store at
+ * `options.execOptions.cwd`.
+ *
+ * @see https://git-scm.com/docs/git-fetch
+ */
+export async function gitFetch(remote, refspec, options) {
+    const args = ["fetch", "--quiet"];
+    if (options?.filter !== undefined) {
+        args.push(`--filter=${options.filter}`);
+    }
+    if (options?.depth !== undefined) {
+        args.push(`--depth=${options.depth}`);
+    }
+    args.push(remote, refspec);
+    await execFileAsync("git", args, {
+        ...options?.execOptions,
+        signal: options?.signal ?? undefined,
+    });
+}
+//# sourceMappingURL=fetch.js.map

package/dist/fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.js","sourceRoot":"","sources":["../src/fetch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAsB7C;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC7B,MAAc,EACd,OAAe,EACf,OAAyB;IAEzB,MAAM,IAAI,GAAG,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAElC,IAAI,OAAO,EAAE,MAAM,KAAK,SAAS,EAAE,CAAC;QACnC,IAAI,CAAC,IAAI,CAAC,YAAY,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACzC,CAAC;IACD,IAAI,OAAO,EAAE,KAAK,KAAK,SAAS,EAAE,CAAC;QAClC,IAAI,CAAC,IAAI,CAAC,WAAW,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IACvC,CAAC;IAED,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE3B,MAAM,aAAa,CAAC,KAAK,EAAE,IAAI,EAAE;QAChC,GAAG,OAAO,EAAE,WAAW;QACvB,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,SAAS;KACpC,CAAC,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./checkout.js";
+export * from "./command-options.js";
+export * from "./fetch.js";
+export * from "./init.js";
+export * from "./remote.js";
+export * from "./rev-parse.js";
+export * from "./sparse-checkout.js";
+export * from "./status-v1.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+export * from "./checkout.js";
+export * from "./command-options.js";
+export * from "./fetch.js";
+export * from "./init.js";
+export * from "./remote.js";
+export * from "./rev-parse.js";
+export * from "./sparse-checkout.js";
+export * from "./status-v1.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC"}

package/dist/init.d.ts

@@ -0,0 +1,9 @@
+import type { GitCommandOptions } from "./command-options.js";
+/**
+ * Initializes a new, empty git repository (in `options.execOptions.cwd`, or the
+ * process's own working directory when omitted).
+ *
+ * @see https://git-scm.com/docs/git-init
+ */
+export declare function gitInit(options?: GitCommandOptions): Promise<void>;
+//# sourceMappingURL=init.d.ts.map

package/dist/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D;;;;;GAKG;AACH,wBAAsB,OAAO,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKxE"}

package/dist/init.js

@@ -0,0 +1,14 @@
+import { execFileAsync } from "@ac-kit/node";
+/**
+ * Initializes a new, empty git repository (in `options.execOptions.cwd`, or the
+ * process's own working directory when omitted).
+ *
+ * @see https://git-scm.com/docs/git-init
+ */
+export async function gitInit(options) {
+    await execFileAsync("git", ["init", "--quiet"], {
+        ...options?.execOptions,
+        signal: options?.signal ?? undefined,
+    });
+}
+//# sourceMappingURL=init.js.map

package/dist/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAI7C;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,OAA2B;IACxD,MAAM,aAAa,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE;QAC/C,GAAG,OAAO,EAAE,WAAW;QACvB,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,SAAS;KACpC,CAAC,CAAC;AACJ,CAAC"}

package/dist/remote.d.ts

@@ -0,0 +1,8 @@
+import type { GitCommandOptions } from "./command-options.js";
+/**
+ * Adds a remote named `name` pointing at `url` (in `options.execOptions.cwd`).
+ *
+ * @see https://git-scm.com/docs/git-remote#Documentation/git-remote.txt-emaddem
+ */
+export declare function gitRemoteAdd(name: string, url: string, options?: GitCommandOptions): Promise<void>;
+//# sourceMappingURL=remote.d.ts.map

package/dist/remote.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote.d.ts","sourceRoot":"","sources":["../src/remote.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D;;;;GAIG;AACH,wBAAsB,YAAY,CACjC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CAKf"}

package/dist/remote.js

@@ -0,0 +1,13 @@
+import { execFileAsync } from "@ac-kit/node";
+/**
+ * Adds a remote named `name` pointing at `url` (in `options.execOptions.cwd`).
+ *
+ * @see https://git-scm.com/docs/git-remote#Documentation/git-remote.txt-emaddem
+ */
+export async function gitRemoteAdd(name, url, options) {
+    await execFileAsync("git", ["remote", "add", name, url], {
+        ...options?.execOptions,
+        signal: options?.signal ?? undefined,
+    });
+}
+//# sourceMappingURL=remote.js.map

package/dist/remote.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote.js","sourceRoot":"","sources":["../src/remote.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAI7C;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CACjC,IAAY,EACZ,GAAW,EACX,OAA2B;IAE3B,MAAM,aAAa,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,CAAC,EAAE;QACxD,GAAG,OAAO,EAAE,WAAW;QACvB,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,SAAS;KACpC,CAAC,CAAC;AACJ,CAAC"}

package/dist/rev-parse.d.ts

@@ -0,0 +1,10 @@
+import type { GitCommandOptions } from "./command-options.js";
+/**
+ * Resolves `rev` (e.g. `"HEAD"`, a branch name, or a short SHA) to its full
+ * commit SHA at `options.execOptions.cwd`.
+ *
+ * @throws {ProcessExitWithOutputError} When `rev` cannot be resolved.
+ * @see https://git-scm.com/docs/git-rev-parse
+ */
+export declare function gitRevParse(rev: string, options?: GitCommandOptions): Promise<string>;
+//# sourceMappingURL=rev-parse.d.ts.map

package/dist/rev-parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rev-parse.d.ts","sourceRoot":"","sources":["../src/rev-parse.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D;;;;;;GAMG;AACH,wBAAsB,WAAW,CAChC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,iBAAiB,GACzB,OAAO,CAAC,MAAM,CAAC,CAQjB"}

package/dist/rev-parse.js

@@ -0,0 +1,17 @@
+import { execFileAsync } from "@ac-kit/node";
+/**
+ * Resolves `rev` (e.g. `"HEAD"`, a branch name, or a short SHA) to its full
+ * commit SHA at `options.execOptions.cwd`.
+ *
+ * @throws {ProcessExitWithOutputError} When `rev` cannot be resolved.
+ * @see https://git-scm.com/docs/git-rev-parse
+ */
+export async function gitRevParse(rev, options) {
+    const { stdout } = await execFileAsync("git", ["rev-parse", rev], {
+        ...options?.execOptions,
+        encoding: "utf8",
+        signal: options?.signal ?? undefined,
+    });
+    return stdout.trim();
+}
+//# sourceMappingURL=rev-parse.js.map

package/dist/rev-parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rev-parse.js","sourceRoot":"","sources":["../src/rev-parse.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAI7C;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAChC,GAAW,EACX,OAA2B;IAE3B,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,GAAG,CAAC,EAAE;QACjE,GAAG,OAAO,EAAE,WAAW;QACvB,QAAQ,EAAE,MAAM;QAChB,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,SAAS;KACpC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;AACtB,CAAC"}

package/dist/sparse-checkout.d.ts

@@ -0,0 +1,23 @@
+import type { GitCommandOptions } from "./command-options.js";
+export type GitSparseCheckoutInitOptions = GitCommandOptions & {
+    /**
+     * Use cone mode — directory-scoped patterns instead of full gitignore-style
+     * patterns.
+     */
+    cone?: boolean;
+};
+/**
+ * Enables sparse-checkout for the repository at `options.execOptions.cwd`.
+ *
+ * @see https://git-scm.com/docs/git-sparse-checkout
+ */
+export declare function gitSparseCheckoutInit(options?: GitSparseCheckoutInitOptions): Promise<void>;
+/**
+ * Restricts the working tree at `options.execOptions.cwd` to `paths` (cone-mode
+ * directory patterns when {@link gitSparseCheckoutInit} was called with `cone:
+ * true`).
+ *
+ * @see https://git-scm.com/docs/git-sparse-checkout
+ */
+export declare function gitSparseCheckoutSet(paths: readonly string[], options?: GitCommandOptions): Promise<void>;
+//# sourceMappingURL=sparse-checkout.d.ts.map

package/dist/sparse-checkout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sparse-checkout.d.ts","sourceRoot":"","sources":["../src/sparse-checkout.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,MAAM,MAAM,4BAA4B,GAAG,iBAAiB,GAAG;IAC9D;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CACf,CAAC;AAEF;;;;GAIG;AACH,wBAAsB,qBAAqB,CAC1C,OAAO,CAAC,EAAE,4BAA4B,GACpC,OAAO,CAAC,IAAI,CAAC,CAWf;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACzC,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,CAAC,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CAKf"}

package/dist/sparse-checkout.js

@@ -0,0 +1,30 @@
+import { execFileAsync } from "@ac-kit/node";
+/**
+ * Enables sparse-checkout for the repository at `options.execOptions.cwd`.
+ *
+ * @see https://git-scm.com/docs/git-sparse-checkout
+ */
+export async function gitSparseCheckoutInit(options) {
+    const args = ["sparse-checkout", "init"];
+    if (options?.cone) {
+        args.push("--cone");
+    }
+    await execFileAsync("git", args, {
+        ...options?.execOptions,
+        signal: options?.signal ?? undefined,
+    });
+}
+/**
+ * Restricts the working tree at `options.execOptions.cwd` to `paths` (cone-mode
+ * directory patterns when {@link gitSparseCheckoutInit} was called with `cone:
+ * true`).
+ *
+ * @see https://git-scm.com/docs/git-sparse-checkout
+ */
+export async function gitSparseCheckoutSet(paths, options) {
+    await execFileAsync("git", ["sparse-checkout", "set", ...paths], {
+        ...options?.execOptions,
+        signal: options?.signal ?? undefined,
+    });
+}
+//# sourceMappingURL=sparse-checkout.js.map

package/dist/sparse-checkout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sparse-checkout.js","sourceRoot":"","sources":["../src/sparse-checkout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAY7C;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAC1C,OAAsC;IAEtC,MAAM,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC;IAEzC,IAAI,OAAO,EAAE,IAAI,EAAE,CAAC;QACnB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACrB,CAAC;IAED,MAAM,aAAa,CAAC,KAAK,EAAE,IAAI,EAAE;QAChC,GAAG,OAAO,EAAE,WAAW;QACvB,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,SAAS;KACpC,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACzC,KAAwB,EACxB,OAA2B;IAE3B,MAAM,aAAa,CAAC,KAAK,EAAE,CAAC,iBAAiB,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC,EAAE;QAChE,GAAG,OAAO,EAAE,WAAW;QACvB,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,SAAS;KACpC,CAAC,CAAC;AACJ,CAAC"}

package/dist/status-v1.d.ts

@@ -0,0 +1,28 @@
+import type { ExecOptions } from "node:child_process";
+export type GitStatusCode = [string, string];
+export type GitStatusV1Entry = {
+    statusCode: GitStatusCode;
+    /** Path relative to the git root. */
+    path: string;
+    /** Original path in case of rename/copied contents, null otherwise. */
+    origPath: string | null;
+};
+export type GitStatusOptions = {
+    /** Include ignored files. */
+    ignored?: boolean;
+    /** An optional AbortSignal that can be used to abort the operation. */
+    signal?: AbortSignal | null;
+    /** Additional options to pass to the `execAsync` function. */
+    execOptions?: Omit<ExecOptions, "signal" | "encoding">;
+};
+/**
+ * Retrieves the git status in porcelain v1 format, optionally limited to the
+ * specified path(s).
+ *
+ * @param pathSpec Array of paths to limit the status to.
+ * @param options Options for the git status command.
+ * @returns Array of git status entries.
+ * @see https://git-scm.com/docs/git-status#_porcelain_format_version_1
+ */
+export declare function gitStatusV1Sync(pathSpec?: string[], options?: GitStatusOptions): Promise<GitStatusV1Entry[]>;
+//# sourceMappingURL=status-v1.d.ts.map

package/dist/status-v1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-v1.d.ts","sourceRoot":"","sources":["../src/status-v1.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAOtD,MAAM,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE7C,MAAM,MAAM,gBAAgB,GAAG;IAC9B,UAAU,EAAE,aAAa,CAAC;IAE1B,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IAEb,uEAAuE;IACvE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC9B,6BAA6B;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,uEAAuE;IACvE,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAE5B,8DAA8D;IAC9D,WAAW,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,QAAQ,GAAG,UAAU,CAAC,CAAC;CACvD,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACpC,QAAQ,GAAE,MAAM,EAAO,EACvB,OAAO,CAAC,EAAE,gBAAgB,GACxB,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAkD7B"}

package/dist/status-v1.js

@@ -0,0 +1,56 @@
+import { EOL } from "node:os";
+import { joinNonEmpty } from "@ac-kit/core";
+import { escapeCommandArg, execAsync } from "@ac-kit/node";
+/**
+ * Retrieves the git status in porcelain v1 format, optionally limited to the
+ * specified path(s).
+ *
+ * @param pathSpec Array of paths to limit the status to.
+ * @param options Options for the git status command.
+ * @returns Array of git status entries.
+ * @see https://git-scm.com/docs/git-status#_porcelain_format_version_1
+ */
+export async function gitStatusV1Sync(pathSpec = [], options) {
+    const pathArgs = pathSpec.map((p) => escapeCommandArg(p));
+    const args = [
+        ...pathArgs,
+        pathArgs.length > 0 ? "--" : "",
+        "--porcelain=v1",
+        options?.ignored ? "--ignored" : "",
+    ];
+    const { stdout } = await execAsync(`git status ${joinNonEmpty(args, " ")}`, {
+        ...options?.execOptions,
+        encoding: "utf8",
+        signal: options?.signal ?? undefined,
+    });
+    return stdout
+        .trimEnd()
+        .split(EOL)
+        .map((line) => {
+        // either "XY PATH" or "XY ORIG_PATH -> PATH"
+        const words = line.split(" ");
+        const [statusCodeFirstChar, statusCodeSecondChar] = words[0];
+        if (statusCodeFirstChar === undefined ||
+            statusCodeSecondChar === undefined) {
+            throw new Error(`Unexpected git status output line: ${line}`);
+        }
+        let path;
+        let origPath;
+        const pathSeparatorIndex = words.indexOf("->");
+        if (pathSeparatorIndex !== -1) {
+            // rename or copy
+            origPath = words.slice(1, pathSeparatorIndex).join(" ");
+            path = words.slice(pathSeparatorIndex).join(" ");
+        }
+        else {
+            origPath = null;
+            path = words.slice(1, pathSeparatorIndex).join(" ");
+        }
+        return {
+            statusCode: [statusCodeFirstChar, statusCodeSecondChar],
+            path,
+            origPath,
+        };
+    });
+}
+//# sourceMappingURL=status-v1.js.map

package/dist/status-v1.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-v1.js","sourceRoot":"","sources":["../src/status-v1.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAE,MAAM,SAAS,CAAC;AAE9B,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AA0B3D;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACpC,QAAQ,GAAa,EAAE,EACvB,OAA0B;IAE1B,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1D,MAAM,IAAI,GAAG;QACZ,GAAG,QAAQ;QACX,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE;QAC/B,gBAAgB;QAChB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE;KACnC,CAAC;IAEF,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,SAAS,CAAC,cAAc,YAAY,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE;QAC3E,GAAG,OAAO,EAAE,WAAW;QACvB,QAAQ,EAAE,MAAM;QAChB,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,SAAS;KACpC,CAAC,CAAC;IAEH,OAAO,MAAM;SACX,OAAO,EAAE;SACT,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACb,6CAA6C;QAC7C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAE9B,MAAM,CAAC,mBAAmB,EAAE,oBAAoB,CAAC,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;QAE9D,IACC,mBAAmB,KAAK,SAAS;YACjC,oBAAoB,KAAK,SAAS,EACjC,CAAC;YACF,MAAM,IAAI,KAAK,CAAC,sCAAsC,IAAI,EAAE,CAAC,CAAC;QAC/D,CAAC;QAED,IAAI,IAAY,CAAC;QACjB,IAAI,QAAuB,CAAC;QAE5B,MAAM,kBAAkB,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC/C,IAAI,kBAAkB,KAAK,CAAC,CAAC,EAAE,CAAC;YAC/B,iBAAiB;YACjB,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,kBAAkB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACxD,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAClD,CAAC;aAAM,CAAC;YACP,QAAQ,GAAG,IAAI,CAAC;YAChB,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,kBAAkB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACrD,CAAC;QAED,OAAO;YACN,UAAU,EAAE,CAAC,mBAAmB,EAAE,oBAAoB,CAAC;YACvD,IAAI;YACJ,QAAQ;SACR,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@ac-kit/cmd-git",
+  "version": "0.1.0",
+  "description": "Typed wrapper over the git CLI: invocation plus git status porcelain v1 parsing.",
+  "keywords": [
+    "cli",
+    "git",
+    "porcelain",
+    "wrapper"
+  ],
+  "homepage": "https://anthochamp.github.io/node-essentials/api/cmd-git/",
+  "bugs": {
+    "url": "https://github.com/anthochamp/node-essentials/issues"
+  },
+  "license": "BSD-3-Clause",
+  "author": "Anthony Champagne <dev@anthonychampagne.fr>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anthochamp/node-essentials.git",
+    "directory": "packages/cmd-git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "publishConfig": {
+    "main": "./dist/index.js",
+    "access": "public"
+  },
+  "scripts": {
+    "compile": "tsc -p ./tsconfig.build.json -outDir dist",
+    "compile:check": "tsc -noEmit -p ./tsconfig.json",
+    "clean": "rimraf dist",
+    "build": "yarn clean && yarn compile",
+    "test": "yarn run -T vitest run",
+    "prepack": "yarn build"
+  },
+  "dependencies": {
+    "@ac-kit/core": "^0.1.0",
+    "@ac-kit/node": "^0.1.0"
+  },
+  "devDependencies": {
+    "@ac-kit/tsconfig": "0.1.0",
+    "@ac-kit/typedoc-config": "0.1.0",
+    "@ac-kit/vitest-config": "0.1.0",
+    "@types/node": "26.5.1",
+    "@typescript/native": "typescript@7.0.2",
+    "rimraf": "6.1.3",
+    "typedoc": "0.28.20",
+    "typescript": "@typescript/typescript6@6.0.2"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}